[coding agents 3/3] Claude Code and Codex in the client: the MCP entry, the Stop hook, and capture - #1693

The tests cover what the installer promises: the exact `claude mcp add`
and `claude mcp remove` commands (with the remove that makes a second
install leave one entry), the `.mcp.json` shape, Codex's two tables in
`$CODEX_HOME`, in `~/.codex` and in a project's `.codex`, a second
install that writes nothing, disable that leaves other servers and other
tables in place, `--dry-run` that prints a diff and writes nothing, and
the `<file>.bak` copy of what a write replaced.

A Codex config with comments, other tables and a multi-line string that
holds table headers as text comes back byte for byte after an install and
a disable, which is what the text-level edit has to hold. Installs run
through `cli.main`, so they also hold that the agent commands need no
server URL for the REST client.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

The page says what an agent gets (the two MCP tools and the endpoint that
serves them), how to read the markers a result carries and which of them
`memory_expand` takes, how a tenant name is chosen, and the install and
disable steps for Claude Code and Codex in both scopes, with the command
and the file each one writes. It also states what the installer keeps:
one entry however often it runs, a `<file>.bak` beside every file it
writes, and a `--dry-run` that writes nothing.

Capture through the agents' Stop hooks is named as what comes next, and
ambient recall as designed and off, so a reader knows the tools are the
whole recall surface today. The page joins the Open Source group in the
navigation.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

One verb for the operation from EventMemory up: query.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

A coding agent records a session as a JSONL file: Claude Code one entry
per line under `~/.claude/projects`, Codex one record per line in the
rollout file under `$CODEX_HOME/sessions`. Each reader turns the entries
after a byte offset into bodies for `POST /v1/tenants/{tenant}/events`,
one event per message, tool call, tool result and injected passage, in
transcript order.

What holds:

- An event is held under the identity the transcript fixes, so reading
  the same entry twice produces the same event. A Claude Code entry
  carries its own uuid; a second event of that entry is named under it.
  A Codex record carries none, so its event is named under the session
  and the record's index in the file, which is why a mark carries both
  an offset and an index.
- Only `text` blocks reach the search surface, so a message is what a
  query finds and a tool call, its result and injected text stay on the
  timeline, reached by expanding from a message.
- Injected text says where it came from: a hook, a skill, a compaction
  summary, a system reminder or a slash command. Claude Code's own flags
  are read first and the opening of the text after them; Codex's
  developer channel is injected by construction and its tagged user
  passages by their tag.
- A reader never returns a line the agent has not finished writing, and
  it yields entries that carry nothing to remember with their offset, so
  a session that ends in them is not read again.
- A subagent runs in a session of its own, named by the agent id its
  entries carry or after the turn that launched it, with the parent in
  `properties.parent_session`.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

`memmachine agent capture {claude-code,codex} --server <url> --tenant
<name>` reads a hook's `session_id`, `transcript_path` and `cwd` from
standard input, reads the transcript from where the last run left off,
and posts the new events to `<server>/v1/tenants/<tenant>/events`.
`--transcript` and `--session-id` name them by hand instead.

What holds:

- How far a session has been posted is kept under the agent's own
  directory, `~/.claude/memmachine/capture-state.json` for Claude Code
  and `$CODEX_HOME/memmachine/capture-state.json` for Codex. The mark is
  a shortcut, not a record: a batch is stored whole or rejected whole
  under the ids the transcript fixes, so a lost mark costs one batch the
  server answers `event_exists` to, never a second copy of anything.
- A batch holds at most 200 events and no entry is split across two, so
  the mark a batch carries is past every event in it. The mark moves
  after each batch the server holds, so a failure part way through
  repeats only the rest.
- 200 and 409 `event_exists` are both "the server holds it". Anything
  else leaves the mark where it was and answers non-zero, so the next
  `Stop` posts the same entries again. The whole capture runs under a
  budget of five seconds by default, and running out of it is one of
  those failures.
- Nothing is written to standard output: an agent reads a hook's output
  as context, so what happened is reported on standard error.
- Events carry the agent, the project (the repository root of the
  session's directory, or the directory) and, on tool events, the tool's
  name.

`codex_home_directory` and the two argument validators are named for the
capture client to use, which is the only change to the installer here.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

`memmachine agent install` now writes the `Stop` hook that runs capture,
beside the MCP entry it already wrote, and `disable` takes both back out.
Claude Code reads it from `~/.claude/settings.json` for user scope and
`.claude/settings.json` for project scope; Codex reads it from
`$CODEX_HOME/hooks.json` and `<cwd>/.codex/hooks.json`.

What holds:

- Both agents read the same shape, a `hooks` object whose `Stop` key
  holds groups of handlers, so one edit serves both.
- The handler names the interpreter this client is installed in by its
  own path and reaches the client as a module of it, because both agents
  run a handler's command through a shell whose PATH need not hold that
  interpreter.
- A handler is recognized as ours by the capture command in it, whatever
  server, tenant and interpreter it names, and is replaced where it
  stands, so a second install leaves one behind and does not rewrite a
  file that already reads as the edit would leave it.
- Every other hook, every other event and every other key of the file is
  carried over, a write is backed up to `<file>.bak` like the other
  files, and disabling removes our handler and nothing else: a `Stop`
  key or a `hooks` key left holding nothing goes with it.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

The page said capture was coming; it is here, so it says what capture
records instead: messages, tool calls with their arguments, tool results
and injected text, of which only messages are embedded and the rest is
read by expanding from a message.

It also states the `Stop` hook the installer writes for each agent and
scope, the state file that holds how far a session has been posted and
why deleting it costs one rejected batch rather than a duplicate, and
the command that posts a transcript by name, which is how a session from
before the install reaches memory. "What is coming" now names the
session outline and ambient recall, which are what is left.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

The capture's report on standard error read "captured 1 events". It now
agrees with the count it carries.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

A `tool_result` block names a tool, and the server's block takes no
empty name, so a result the reader could not pair with a call would have
been rejected -- and a batch is rejected whole, so that one result would
have held up every event after it for as long as the session ran.

Such a result is now named `unknown`, which says the transcript carried
no name. Claude Code still reads the entries before its mark for the
call's real name first; a Codex output whose call id is in no record of
the file has nowhere else to look.

Checked against the block kinds the server registers: every event body
both readers produce validates as an `EventSpec` and encodes as an
`Event`, over text, tool_call, tool_result and injected blocks.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

The server holds a tool result and an injected passage as one segment
each, however long they are, and an expansion step is counted in
segments, so one long result would spend a whole step on itself and
crowd out the turns around it.

Both readers now cap those two blocks at `ONE_SEGMENT_MAX_BYTES`, 8192
bytes of UTF-8, cutting at the character boundary at or before the cap
and writing one line after it, `[truncated: N of M bytes]`, so a reader
of the memory knows the passage goes on and by how much. The marker is
the reader's rather than the agent's, so it follows the cap instead of
eating into it.

A message's text is not capped: it is what a query matches, and it is
already segmented by the server.

The cap and the cut are one constant and one function in a module both
readers hold to, since the two must agree on them.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

A batch is rejected whole, so `event_exists` for a batch says the server
holds one of its events, not that it holds them all. A session resumed
or forked from another repeats entries under the ids they were stored
under, so such a batch mixes events already held with events that are
new, and moving the mark over it lost the new ones.

The batch is now posted again an event at a time, in the order it was
read, where `event_exists` is that one event and says it is held. The
mark moves only once the server holds every event of the batch, so
nothing is stored twice and nothing is lost, and the second pass is paid
for only on the conflict path. A failure part way through that pass
leaves the mark before the whole batch, which the next `Stop` posts
again.

The count reported on standard error is now what the server stored, not
what was sent, so a batch that was mostly held says so.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

The event-by-event pass a conflicting batch falls back to started over
on every failure, so a batch that conflicts over a slow link could run
out of the budget at the same place each turn and never get past it.

Events go in the order the transcript holds them, so once the server
holds one, every event before it is held as well. Each event now carries
the mark that stands once it is held -- the mark past its entry for the
last event that entry produced, and the mark before the entry for the
events ahead of it, since an entry is passed only when every event of it
is held -- and the mark is written where the pass reached, whether it
reached the end or stopped for any reason on the way.

A failure part way through therefore keeps what was held and the next
`Stop` posts only what is left, while an entry whose events are half
held is still read again whole, so nothing is stored twice.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

A dry run of the user-scope install printed only the add, and failed
outright where no claude executable was on PATH, although it runs
nothing. It now prints the remove and the add it would run, and the
PATH lookup happens only for a real run.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE