feat(core,server,web): Memory — notes an agent keeps between Sessions, in user and workspace scopes

[rank-Yu]

Adds agent_state/memory/: Markdown notes an agent maintains itself with the ordinary file tools. Each scope carries its own MEMORY.md index; only the indexes enter the model context, topic bodies are read on demand. Memory is not context compaction — compaction preserves one Session's short-term working state, Memory is what survives the Session ending.

Two scopes

Both belong to one agent and are never shared with another:

• User scope (memory/user/) — what stays true wherever the agent works: who the user is, their standing preferences, reference material not tied to one codebase. Every Session reads it.
• Workspace scope (memory/<workspace_memory_key>/) — facts about one Workspace: project decisions, feedback received, pointers into its external systems. Sessions of one agent in one Workspace share it; different Workspaces keep their topic files apart.

agent_state/memory/
├── user/                         # user scope, created with the agent (no marker: it stands for no path)
│   ├── MEMORY.md                 # this scope's index: one line per memory, links relative to the scope
│   └── prefers-pnpm.md
└── my-app-a81f32c4/              # created on the first Session in that Workspace
    ├── .workspace                # the Workspace path this key stands for
    ├── MEMORY.md
    └── testing-conventions.md

The workspace memory key is <safe-basename>-<8 hex of the real path's sha256> — identity is the directory itself, with no dependence on Git, so two symlinks to one directory resolve to a single key while moving or renaming a directory makes it a new Workspace (the old Memory stays on disk under the old key). user is safe to reserve because a generated key always carries a hyphen: a hyphen-free name can never be produced.

A temporary Workspace gets no Workspace scope. One is allocated per Session, so no later Session would ever run there to read it back — a bucket keyed off it would be write-only storage. Such a Session still gets the user scope, which is where anything it learns belongs anyway. The test is the directory's location — anything under an agent's workspaces/ — because a subagent inherits its parent's Workspace as an explicit argument, temporary ones included.

The .workspace marker exists because the key is a hash and cannot be read back into a path — without it the Web App could only ever label a Workspace my-app-a81f32c4. It is a dotfile, so it never shows up as a topic.

A topic file declares name (kebab-case, matching the file name) / description (one line used to decide relevance during recall) / updated_at in frontmatter — which scope a memory belongs to is expressed by its directory, so there is no type field (a type: line left in an earlier file parses as an unknown field and is ignored). In the body, [[name]] links related memories, and corrections / decisions carry Why: / How to apply: lines. Memory lives in Agent State and is readable by every Project member who can reach the agent, so credentials and sensitive personal data never belong in it.

What reaches the model

Only the indexes, through the template's {{MEMORY}} placeholder. It expands to memory.prompt — what Memory is for, the save mechanics in template-example form (a fenced frontmatter example, what is worth saving, the index contract with both injection caps, the hygiene rules), then a ## User memory section with its index — plus memory.workspace_prompt, a ## Workspace memory section, when the Session runs in a persistent Workspace. Both prompts are edited right on the Memory tab, so nothing about the injection is invisible.

The prompts are 100% static instruction text organized by Markdown headings, like the template's other sections — the indexes are their only injection points:

key	injected	carries
memory.prompt	always	{{MEMORY_USER_INDEX}}
memory.workspace_prompt	persistent Workspace only	{{MEMORY_INDEX}}

Both Directory lines are the same literal pattern <app_data_dir>/agents/<agent_id>/agent_state/memory/<…>, resolved by the model from the Environment section like the Skills paths. The user section ends in the literal user; the workspace section ends in <workspace_memory_key> — the one per-Session segment, riding the template's Environment section as the - Workspace Memory Key: {{WORKSPACE_MEMORY_KEY}} line next to CWD (the directory name the code already calls the workspace memory key). Patterns live in prompt text, values live in Environment; the line renders (none — temporary workspace) in a temporary Workspace and (none — memory is off) with Memory off, and nothing references it then.

Two keys rather than one because substitution has no conditionals: a temporary Workspace must never be handed the Workspace section — its directory line and the scope-choice rule — so that half is simply not appended there.

A blank index injects an explicit "nothing saved yet" note, and injection is capped at 200 lines per scope, then at 25,000 characters total as a backstop for indexes whose few lines are enormous (cut at a line boundary) — past a cap a truncation note tells the model to open the full MEMORY.md itself, the file on disk untouched. The default prompt declares the line cap and asks for index lines under ~150 characters, so the model keeps the index short before ever hitting the caps; the character backstop lives only in code.

A template without {{MEMORY}} injects nothing — an agent created before Memory, for instance. Adoption is explicit: the Memory tab shows a hint with a one-click insert (POST …/memory/template-placeholder, an idempotent config write placing {{MEMORY}} before # Environment and the Workspace Memory Key line right after that heading). Nothing is ever spliced in automatically, and the assembled prompt is recorded in session_meta.

Deciding what is worth keeping, splitting topics and maintaining the indexes is the model's own work — the Harness decides where Memory lives and keeps writes inside it, nothing more.

Server

MemoryService + /api/projects/:p/agents/:a/memory — overview (switch + templateHasMemory + one entry per scope, user first), the placeholder insert, per-scope file listing, file read, file delete. The memory prompts ride the ordinary config route (AgentMemoryConfigDto reports effective values with the built-in defaults folded in). Deliberately read + delete only: content changes go through a chat Session where the model keeps frontmatter and index in step. The one write the API performs is mechanical — deleting a file also drops its ](<file>) lines from that scope's MEMORY.md, so the index never lists a file that is gone; a plain-prose mention survives.

No route accepts a path: a file is addressed by agent, scope key and a name inside that scope, each pattern-checked and then re-checked for containment after resolution. The user scope goes through the same routes under the key user, created on demand (it belongs to the agent, not to a Session that has run); a Workspace key with no directory still 404s. memory.enabled round-trips through the existing config route.

Web App

Agent settings gain a Memory tab between Prompt and Runtime. Top to bottom: the switch (writes on change rather than joining a tab-level Save, so turning Memory off never drags an unrelated half-finished edit along); a hint bar with a one-click placeholder insert when the template lacks {{MEMORY}}; every memory grouped by scope — user memory first, then one group per Workspace, titled by its directory basename with the full .workspace path beside it, newest activity first, each group collapsing on header click (the skill library's convention), the collapse state remembered in the browser per user × Project × Agent; and the two memory prompt editors with their own confirm-first Save.

Each group header carries an Add action — the edit modal's shape with a required content-or-source field (pasted text, a file path or a URL; the agent reads sources itself) and a live prompt preview — bridging into a new chat where the agent organizes the content into that scope. Both bridge drafts stay deliberately minimal, naming only the target (the memory's title / the scope by kind) and the ask: the save mechanics — frontmatter, index upkeep — already live in the agent's Memory prompt.

Rows show name, description and date, and are deliberately read-only:

• View renders the body (frontmatter stripped — the header already shows those fields) in a right drawer on desktop and a bottom sheet with half/full snap points on narrow screens, the chat page panels' interaction.
• Delete confirms, removes the file, and the server prunes its index lines.
• Edit opens a bridging modal first — the memory's file path, a requirement field, and a live preview of the generated prompt, the same shape as the skill import modal, with copy and open-a-new-chat actions — then jumps to a new chat with this agent through the same draft-cache route, the prompt prefilled and the requirement filled in (or left trailing to complete in the composer). A Workspace scope's chat (edit and import alike) also pins that Workspace, so the Session is injected with the very index it is about to change.

The agents list cards' stat line shows the memory count next to the tool / vault / schedule / skill counts, deep-linking to the Memory tab.

Turning Memory off keeps every file and the tab fully usable; it only stops Memory from entering the context and from preparing directories for new Sessions.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A5HjinDmtgqQ7jiAXagrbG

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.