Memory

Writing must never slow a turn. Reading must never be trusted blindly. The two directions have opposite rules, and both are best-effort.

plate 06out, in, and back again

Out: nothing waits on it

A session is behind a mutex and a commit is a short lock. Putting a socket round trip inside one would make every entry wait on another process, so what is committed is queued and the turn carries on. If the write never lands, the entry is still in the window — only the durable record is lost.

In: nothing is trusted blindly

Recall returns memories with a confidence. Anything below the floor is dropped rather than hedged, and what survives is written into the window as one user message that says what it is — never slipped in as though the conversation had contained it.

bound	limits
inject floor	how sure balthasar must be before a memory reaches the window at all
live floor	the lower bar for something recalled inside the current session
window share	the fraction of the context memory may ever occupy
most	a hard count, so a broad query cannot flood a turn

The frame line is written first. A recall that found only weak matches still says so — a hedged recall presented as certainty is worse than no recall at all.

Back: did it help

A turn reports what it used and how that went. balthasar decides for itself whether the action followed from anything it gave; a harness claiming a match it did not verify would be asserting an analysis rather than reporting an event.

→ {"call":"used","args":["inject-1788683868-e3b0c442",{"tool":"shell","action":"…"}]}
← {"ok":true,"family":1,"n":1,"result":[{"action":"use-1788683868-inject-17886"}]}
→ {"call":"outcome","args":["use-1788683868-inject-17886",{"kind":"succeeded"}]}

Without it a memory layer can rank by recency and by similarity, and never by whether anything it offered was any use.

Which store a directory gets

plate 07walk up until something claims it

A store somebody made deliberately wins first; then the checkout the directory is in. Five worktrees of one project share one memory rather than starting each other's amnesia.

Both walks stop before a directory nobody owns. Without a ceiling, one stray marker high up collects everything beneath it — and both kinds occur naturally: a leftover store in the temporary directory, and a .git at $HOME, which is what an ordinary dotfiles repository is. Either would put unrelated projects into a single memory. The rule is stricter for the inferred marker than the deliberate one: a repository at $HOME is not the project a subdirectory belongs to, while a store somebody explicitly created there is.

Resuming

With balthasar running there is no journal on disk at all — it is the store, and a second copy is a copy that goes stale. magi --resume asks balthasar which runs this project has had and replays the newest.

$ magi -p "remember the number 8231, just say ok"
ok
$ magi --resume -p "what number did I ask you to remember?"
8231

A separate process, after the first one and the balthasar it started are both gone. What survives is the store, not a running thing.

backwhat may run nextsessions