Agent memory: sessions, notes, compaction & project scope

Agent CLIs are one-shot by nature — every message would normally start a stranger. Mastery HQ layers several kinds of memory on top so your agents behave like colleagues instead — and scopes all of it per project, so two windows on two different jobs can never blend.

Project scope: separate windows, separate projects

Every agent window works in a project scope, always visible on the 📁 chip above its input bar and announced in the transcript before its first task of a session:

Default — isolated. A window with no project set works on its own project: its working notes, memory, and recall cover only itself. Use one window for a website and another for a trading bot and nothing crosses over — they’re separate unless you link them.
Linked — same project name. Give two windows the same project name and they collaborate on one project: recall sees each other’s notes and handoffs, and they share that project’s durable memory. Link them with the 📁 chip or by typing project <name> in each window (project off isolates a window again; bare project shows the current scope).
Orchestrated. The Kanban crew and Hermes share context across the agents they drive on purpose — that’s what an orchestrator is for. A routed task still respects a target window’s own project: a window you dedicated to a project keeps that project’s memory even when Hermes hands it work.

One window reused across different jobs is covered too: its notes follow the project (each project name has its own notes file), so switching project swaps the right memory in — and the injected notes always name the project they belong to, with an instruction to ask before mixing anything else in.

Files live per project too. A window without an assigned GitHub repo runs inside its scope’s own working folder — projects/<name>/ in the workspace folder (the scope banner names it) — so two projects can never mix files in one place. Setting a project whose folder already has content asks first: join the existing project, or pick a new name? Repeat the same project <name> to join; choose another name for a fresh folder. An assigned repo still wins — that window works in its git worktree as before.

Organized and labeled, as a routine. Every CLI agent carries a standing file routine: deliverables go in labeled type subfolders — docs/ (markdown, docx, csv, slides), images/, video/, audio/, src/, data/ — with descriptive, dated, kebab-case names (docs/2026-07-21-launch-brief.md), never output.csv or final2.md. Media an agent requests with [[image: …]], [[video: …]], [[reel: …]], or [[bumper: …]] is filed the same way: it lands in that window’s projects/<name>/images/ or video/ with a labeled, dated filename. Everything stays findable in the Assets gallery (Tools → Assets), which lists project folders alongside the shared homes.

Sessions (· linked)

Claude Code and Codex windows keep a resumable conversation: the first reply links the session (the header shows · linked and the real model name), and every later message resumes it — across minimize, reload, and app restarts. New conversation starts over. The token meter in the header counts real usage for linked Claude sessions and a running estimate elsewhere; it survives restarts.

Recall last session

Close Mastery HQ and the work isn’t lost: every agent’s transcript is saved to disk at the end of every exchange (agents/<name>/last-session.json in the workspace folder — no fragile “save on shutdown” step to trust). When that agent’s window comes back blank, it offers ↺ Recall last session · 2h ago · 34 lines — one click restores the conversation into the window.

Recall pairs with the session link above: on Claude Code and Codex, the restored conversation continues for real — your next message resumes the same CLI session, context and all. On agents without resumable sessions the transcript returns for reference, and the durable facts live on in the agent’s notes.

Working notes

Each agent keeps working notes per workspace and per project — durable facts it curates itself at the end of replies. Notes are injected as working memory on future runs (always named with the project they belong to) and editable by you via the Notes drawer. Notes belong to the agent, the workspace, and the scope: Alex’s notes never leak into Bo’s, and a window’s website notes never ride into its forex work.

recall <query> searches this window’s scope — its own notes and handoffs, plus any windows linked onto the same project. recall all <query> deliberately searches the whole workspace, every window’s project included.

Compaction & handoffs

Long conversations degrade before they overflow. The context meter warns at 50% and turns red at your threshold (Settings → Agents → Context & memory); Compact asks the agent to write a handoff of goals, decisions, and state, then seeds the next fresh session with it. Auto-compact does this for you when enabled.

Project memory

Durable facts live per scope. Windows linked onto a named project share that project’s memory file (projects/<name>/project.md) — its distilled slice rides their prompts, so every member knows the ground rules. The workspace-wide project.md remains Hermes’s brief for unlinked agents it routes work to — say remember for the project: the demo city is Porto in the Ninja window and it’s logged with a date. Strike through a line (~~…~~) to retire a fact. You can also hand a conversation across agents: hand this to Bo compacts the source session and seeds the target with the handoff.

Good to know

Files live in the workspace folder on disk (agents/<name>/notes.md — plus notes-<project>.md per linked project — agents/<name>/last-session.json, project.md, projects/<name>/project.md) — see data location.
A failed resume (expired session) retries fresh automatically; you’ll see it start over rather than error out.
Recall is per agent per workspace, keyed by the agent’s name — rename an agent and it looks for its own history under the new name.
The scope announcement prints once per window per app session (and whenever you change the project), so which project a window serves is stated before any work runs.

Frequently asked questions

Why does my agent's header say · linked?

Linked means the window holds a resumable CLI conversation: your next message continues the same session, with full context, even after an app restart. New conversation unlinks it and starts fresh.

I closed Mastery HQ — is the agent's conversation gone?

No. The transcript is saved to disk after every exchange, and a fresh window offers ↺ Recall last session — one click brings the conversation back. On Claude Code and Codex the session link resumes too, so the agent actually remembers the context, not just the text.

What happens when the context meter turns red?

The conversation is approaching your compaction threshold. Compact (or let auto-compact run) and the agent writes a handoff summary; the next fresh session starts seeded with it instead of a full context window.

I ran two agents on two different projects and they mixed things up — how do I keep them apart?

They are apart by default now: every window is isolated (its notes, memory, and recall cover only itself) unless you link windows by giving them the same project name. Each window announces its scope before its first task, and the 📁 chip above the input always shows it. If you reuse ONE window across jobs, set its project first (type project <name>) — its notes switch files with the project.