Sessions, memory & recall

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

These eight 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.

Update, append, supersede, or delete?

Four 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.

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.

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.

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. 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. 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 the supersede step fails the new memory is still written and kept, but the call returns an error naming it -- the target is then still active.

memory_append

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

memory_read

Read a memory by name within the current project, falling back to a global memory of the same name.

memory_delete

Delete a memory by name (removes the file and its index).

recall

Search memories and notes by meaning and keyword (fused), scoped to the current project plus global items. This is the single search entry point.