Two optional files let you shape how Hiroshi behaves and how it understands your context. SOUL.md sets the assistant’s core identity — its personality, tone, and hard constraints. USER.md gives it knowledge about you — your stack, your conventions, and how you work. Neither file is required, but filling both in dramatically improves the quality and relevance of every response.
SOUL.md — Core identity
SOUL.md lives at ~/.hiroshi/SOUL.md. It is injected as a background system-level context layer on every conversation turn, before any agent-specific prompt. Think of it as the constitutional layer of your assistant: the values and operating principles that hold across all roles and sessions.
Use SOUL.md to define:
- Personality directives — the voice and character you want the assistant to project
- Tone guidelines — formal vs. casual, brief vs. thorough, direct vs. exploratory
- Ethical constraints — hard limits on what the assistant should never do or suggest
- Operating principles — rules of thumb that should govern every decision (e.g. prefer clarity over cleverness, always validate inputs)
Here is a concise example SOUL.md:
# Hiroshi — Core Identity
You are Hiroshi, a local-first AI developer assistant built for serious engineering work.
## Personality
- Direct and precise. Favour clarity over verbosity.
- Confident but never dismissive. Acknowledge uncertainty honestly.
- Pragmatic — recommend the simplest solution that actually solves the problem.
## Tone
- Technical and professional in code reviews and design discussions.
- Conversational and brief in casual clarification exchanges.
- Never use filler phrases like "Certainly!" or "Great question!".
## Ethical Constraints
- Never produce code that disables security controls or circumvents sandboxing.
- Do not make irreversible file system changes without explicit user confirmation.
- If a request is ambiguous, ask one clarifying question rather than guessing.
## Operating Principles
- Prefer idiomatic Rust over "clever" workarounds.
- Always include error handling — no `.unwrap()` in production-path code.
- When uncertain about a library API, say so and suggest checking the docs.
USER.md — Your personal context
USER.md lives at ~/.hiroshi/USER.md. While SOUL.md defines the assistant, USER.md defines you — the person the assistant is working with. This file is also injected as system-level context on every turn, giving Hiroshi a stable understanding of your environment without you having to repeat yourself in every conversation.
Use USER.md to capture:
- Your primary tech stack — languages, frameworks, build tools
- Preferred conventions — code style, naming patterns, commit message format
- Project structure — how your repositories are organised, where key files live
- Team context — teammates’ roles, shared services, deployment targets
- Operating boundaries — what you own, what you should not touch, escalation paths
Here is a practical example USER.md:
# About Me
## Stack
- **Primary language:** Rust (2021 edition)
- **Async runtime:** Tokio
- **Database:** SQLite via sqlx, with WAL mode enabled
- **Build tool:** Cargo with workspace layout
- **Python:** Used for skill scripts only — not a primary language
## Project Conventions
- Crate names use `snake_case`; type names use `PascalCase`
- All public functions must have doc comments (`///`)
- Commits follow Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`
- No `.unwrap()` or `.expect()` outside of test modules
## Repository Layout
- `/src/` — main binary crate
- `/skills/` — polyglot skill scripts (Python/Bash)
- `/docs/` — Mintlify documentation source
- `AGENTS.md`, `SOUL.md`, `USER.md` — live at `~/.hiroshi/`
## Team
- Solo project — no shared deployment pipeline
- Production target: single Raspberry Pi 5 running as home server
- External services in use: Telegram bot, Tailscale overlay network
## Boundaries
- Do not modify `hiroshi.db` directly — let Hiroshi manage its own database
- Do not commit secrets to version control — use environment variables
When to edit these files
Knowing which file to reach for — and when — keeps your configuration focused and effective.
Edit SOUL.md when you want to:
- Change the assistant’s communication style (more concise, more detailed, different tone)
- Add or tighten ethical constraints after observing unwanted behaviour
- Establish new operating principles for a phase of work (e.g. “prioritise performance over readability this sprint”)
Edit USER.md when you:
- Start a new project and want Hiroshi to understand its structure from the beginning
- Join a new team or change your primary tech stack
- Adopt new tooling, conventions, or deployment targets
- Notice the assistant making repeated incorrect assumptions about your environment
Keep USER.md up to date. Stale context — like a stack entry pointing to a framework you migrated away from six months ago — can cause the agent to make incorrect assumptions about your codebase, recommend the wrong libraries, or generate incompatible code. A quick five-minute review whenever your environment changes saves hours of correction downstream.
