The HQ Mental Model

Your HQ folder · everything lives in one of three homes

HQ is one folder on your computer, organized so that an AI assistant can find the right context for any piece of work, and so that what it learns today is still there tomorrow. Once you understand the layout and one core habit ("sessions are disposable; context is precious"), everything else in HQ makes sense.

The three homes#

Everything you care about lives in one of three places:

HQ/
├── personal/     ← YOU: your profile, preferences, personal projects and skills
├── companies/    ← EACH BUSINESS: isolated knowledge, projects, policies, workers
│   ├── acme/
│   └── northwind/
└── repos/        ← CODE: actual git repositories
    ├── public/
    └── private/

• personal/ is your private overlay: your profile, your own skills, your personal policies and projects. It belongs to you, not to any company, and it is never shipped or replaced when HQ updates.
• companies/ holds one folder per business or team you work with. Each company is a sealed compartment, its knowledge, credentials, and projects never mix with another company's. (More on why in Companies, projects, and repos.)
• repos/ holds real code repositories, split into repos/public/ (open source) and repos/private/. Companies point at repos; they don't contain them.

There are two other folders you'll see but rarely touch: core/ (the HQ system itself, replaced wholesale when you upgrade, so never store your own work there) and workspace/ (HQ's working memory: session records, handoff files, reports).

Sessions are disposable; context is precious#

A session is one conversation with your AI assistant. Sessions have a limited memory (a "context window"), and a session that runs too long starts forgetting and making sloppier decisions. So HQ treats sessions like paper cups: use one, save what mattered, throw it away, grab a fresh one.

What you keep is context, the files on disk. The daily rhythm looks like this:

1. Start a session with /startwork. HQ orients you: last session's summary, active projects, what's next.
2. Do the work.
3. End with /handoff. HQ writes everything a future session needs (summary, next steps, files touched) into workspace/threads/.

Tomorrow's session picks up exactly where today's left off, with a clean head. The full arc, plus mid-session saves and crash recovery, is covered in Sessions, checkpoints, and handoffs.

Knowledge compounds#

The payoff of this design shows up over weeks, not minutes. Every time you correct the assistant, discover a gotcha, or settle a decision, you can capture it with /learn. Learnings become policies (standing rules the assistant follows automatically) or knowledge notes filed under the right company or your personal space.

That means HQ on day 30 knows things HQ on day 1 didn't: your tone, your company's naming conventions, which deploy step always trips people up. Sessions stay disposable precisely because the knowledge lives in files, not in any one conversation. See Teaching HQ for the habit in detail.

The three profile files (and which one you should edit)#

New users often find three similarly named files and don't know which is which. Here's the untangle:

agents-profile.md lives at your HQ root and agents-companies.md lives in your personal/ folder. /setup writes them and HQ reads them when a session starts.

Rule of thumb: edit personal/knowledge/profile.md; let commands maintain the other two.

Common questions#

If you get stuck#

If the folders described here don't match what you see, your install may be incomplete, run /setup again; it detects and repairs missing pieces. Still confused? Try the I'm stuck guide or file a report with /hq-bug.