Sessions, memory & recall

The nine tools an agent uses most - open a session, write, edit and read memory, and search the store.

These nine tools are the agent loop. In a repo mapped to a project, most of them need no project argument at all: session_start binds the connection, and everything after it inherits that scope.

The shape of a session

session_start returns the project briefing and binds the session to the connection. session_end persists findings for the next agent's briefing. Both are optional in the sense that Claude Code's hooks already open an ambient session per agent - calling session_start explicitly adopts it and gets you the full briefing rather than the short injected one.

If tasks_update ever fails claiming a task is held by your own session id, the connection binding was lost. Re-run session_start with the same name to rebind.

Edit, update, append, supersede, or delete?

Five ways to change memory, and picking the wrong one is how a store rots:

The distinction that matters is supersede vs. delete. Superseding is how the store stays honest about its own history: the old memory leaves the briefing and recall, but an agent that follows an old reference still finds it, marked invalid, pointing at what replaced it. Delete is for mistakes - things that were never true - not for things that stopped being true.

A supersedes that fails is reported rather than swallowed: the new memory is still written and kept, and the call returns an error naming it. The target is then still active, so re-run the supersede.

Edit vs. supersede

memory_edit is cheap, which is exactly why its boundary has to be explicit. Edit is for changes that carry no new claim: a typo, broken formatting, a stale path or command, a stage's Status flip, a description, a tag. If the meaning changes - the conclusion is now different, the advice reversed - that is a new memory, and it goes through memory_write with supersedes.

The reason is provenance. A supersession retires the old memory into readable history; an in-place edit leaves no trace that the store ever believed something else. Using edit to change what a memory claims silently rewrites the record.

memory_edit is also the only way to change a memory's description or tags without rewriting its body, and tags_remove is the only way to clear a tag at all - an empty tags array reads as absent everywhere else.

Concurrency: content_hash and expect_hash

memory_read and notes_read return a content_hash - the SHA-256 of the whole file. Pass it back as expect_hash on memory_edit, notes_edit, or notes_update, and the write is refused if the stored file has moved on since you read it. Omit it and the write is unconditional.

It answers a different question from the daemon's own serialization. Every application write already goes through a per-file lock, so two agents can no longer interleave a read and a write and lose one of them. What the lock cannot see is an agent acting on something it read minutes ago, or the owner editing the markdown in an editor - which is why the precondition is checked against the file, inside the lock, rather than against the index (the watcher re-indexes on a debounce, so the index would happily confirm the stale hash).

Scope

memory_write fails closed: with no session and no explicit project, it is rejected as ambiguous rather than silently landing in the global scope. Pass project: global to write a deliberately cross-project memory.

memory_edit targets a memory that already exists, so it resolves like memory_append: the session's scope first, then a global fallback. The write is judged against the project the memory actually sits in.

Recall is the only search tool

There is one search entry point. recall fuses FTS5 keyword matching and vector similarity with reciprocal rank fusion, nudges the fused order by favorite and utility (both bounded), scoped to the current project plus global items, and packs results into a token budget. A call that finds nothing is recorded as a miss - recurring misses become the gardener's memory-wanted proposals.

The optional kind filter restricts hits to memories of one frontmatter kind. It implies memories-only: combining it with scope=notes is rejected as contradictory rather than returning a misleading empty result, and a kind-filtered miss still counts as memory-wanted demand.

With kind set, query becomes optional: a kind alone is the browse mode behind briefing hints like recall kind=convention - the scope's active memories of that kind, listed newest-first under the same limit and token budget. A browse is a listing, not a search: no fusion, no favorite or utility boost, its hits record as passive exposure (never query-gated demand), and an empty browse records no miss - "this project has no conventions yet" is not a missing memory.

It degrades rather than fails: if the embedding provider is unreachable, recall falls back to keyword-only results instead of erroring. A local misconfiguration is surfaced instead of hidden - the two cases are deliberately not treated alike.

Results and failures

session_start

Begin or resume an agent work session and bind it to this connection. Returns the project briefing. Later memory/recall/notes calls inherit this session's project scope, so you rarely pass project again.

session_update

Record interim progress on the current session (working findings so far). Uses the bound session unless you pass one.

session_end

Complete the current session, persisting its findings for future briefings. Uses the bound session unless you pass one.

memory_write

Create or update a durable memory -- the compact knowledge a future session must not miss (a constraint, gotcha, decision, runbook). Long-form write-ups belong in notes_create; put the one-line lesson here. Writing an existing name updates it in place (its id is stable). On a new name, a semantically similar existing memory is reported as an advisory hint; the write still proceeds. The hint is withheld when the target project's content is fenced from you (see the withheld marker on the response) -- the write lands either way. Pass supersedes to replace a DIFFERENT, now-outdated memory: it is marked invalid and leaves every index (briefing, recall) but stays readable with a pointer here. If superseding fails, the new memory is still written and kept; the error says how to retry.

memory_append

Append markdown to an existing memory's body. The memory keeps its id. To create a new memory, use memory_write.

memory_edit

Edit an existing memory in place with exact search/replace, instead of resending its whole body through memory_write. Each edit's old_string must match the current body exactly and uniquely (or pass replace_all); all edits apply together or none do, so a failed match changes nothing. It is also the only way to change a memory's description or tags on their own: send description/tags_add/tags_remove with no edits and the body is left untouched (memory_write requires a body, so there was no metadata-only path before this), and tags_remove is the only way to clear a tag at all. Returns a unified diff of what landed plus the new content_hash. Use this for corrections that do not change what the item CLAIMS: typos, broken formatting, a stale path or command, a stage's Status flip, metadata. If the MEANING changes -- the conclusion is now different, the advice reversed -- that is a new memory: use memory_write with supersedes, which retires the old one into readable history instead of erasing what it used to say.

memory_read

Read a memory by name within the current project (falling back to a global memory of the same name), or directly by id.

memory_delete

Delete a memory by name: the markdown file leaves the disk and its index row goes with it, with no provenance and no pointer left behind. Prefer nearly anything else. To replace knowledge that turned out to be wrong, use memory_write with supersedes -- the old memory drops out of every index (briefings, recall) but stays readable, pointing at what replaced it, which is how a later reader learns the thing was reconsidered rather than that it was never believed. To retire something merely stale, leave it for the gardener's archive proposal. Reserve deletion for memories written by mistake: a duplicate, a test, a write into the wrong project.

recall

Search durable knowledge (memories, notes) and the work record (tasks, trials, session findings) by meaning and keyword (fused), scoped to the current project plus global items. This is the single search entry point. Work-record hits carry a status (a task's status, a trial's outcome) and match on keyword only. With kind set and no query it lists that memory kind newest-first instead (browse).