[coding agents 3/5] Install the MemMachine MCP server in Claude Code and Codex by edwinyyyu · Pull Request #1689 · MemMachine/MemMachine

edwinyyyu · 2026-09-17T20:41:36Z

Slice 3 of design/coding_agent_integration.md (#1579): the client-side glue that points Claude Code and Codex at a MemMachine server's memory tools. Directly on main; it depends on no server change to land, but it is only useful once the server serves /v1/mcp (the v1 API and MCP PRs that follow), so it merges after #1691.

What it does

memmachine agent install {claude-code,codex} --server <url> --tenant <name> [--scope user|project] [--dry-run] and memmachine agent disable {claude-code,codex} [--scope ...], in memmachine_client.coding_agent. The MCP entry is <server>/v1/mcp over streamable HTTP with the header X-MemMachine-Tenant: <tenant>, one tenant per human user.

Claude Code, user scope: runs claude mcp remove --scope user memmachine then claude mcp add --transport http --scope user memmachine <url> --header "X-MemMachine-Tenant: <tenant>" through the claude on PATH (the add refuses a name it already holds, so a reinstall removes first); without one, prints the exact command and exits non-zero. Project scope writes .mcp.json in the current directory, merging with what is there.
Codex: writes [mcp_servers.memmachine] (url) and [mcp_servers.memmachine.http_headers] into $CODEX_HOME/config.toml (default ~/.codex/config.toml) or <cwd>/.codex/config.toml, by text, replacing exactly those two tables where they stand or appending them, with every other byte of the file preserved; the result is parsed back before it is written, and an entry in a form the editor does not own (inline table, dotted key) is refused rather than duplicated.
Every file write backs the file up to <file>.bak first; an unchanged file is not rewritten; --dry-run prints the command or a unified diff.
Docs: docs/open_source/coding_agents.mdx, in the navigation.

Verified

Flag names and file shapes against the current Claude Code MCP documentation and the Codex configuration reference, and empirically against claude 2.1.274 (isolated HOME and CLAUDE_CONFIG_DIR) and codex-cli 0.149.1 (CODEX_HOME on a temp dir): the add command produces the documented entry, a second add fails without the preceding remove, codex mcp get memmachine reports streamable_http with the header, and disable leaves codex mcp list empty. 22 tests cover both agents, both scopes, reinstall, disable, dry run, preservation of unrelated content, the backup, and the missing claude.

Two calls to review

The client package supports Python 3.10, where tomllib does not exist. The Codex commands refuse on 3.10 with a clear message rather than adding a tomli dependency; the alternative is tomli>=2; python_version < "3.11" in the client's dependencies.
Claude Code's user-scope file is written by claude itself, which keeps its own backups, so the installer makes no .bak there.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

Stack: coding agents

Slices of design/coding_agent_integration.md (#1579), in dependency order. 1 sits on the event-memory port stack (#1684 → #1686 → #1685 → #1687 → #1688). 2 depends on 1 in code. 3 shares no code with the server, so its branch is on main, but it depends on 2 functionally: it writes a configuration for the endpoint 2 serves, and merges after it. 4 registers the block kinds capture writes, on 2. 5 is the capture client on 3, and depends on 4 functionally.

Slice	PR	Base	Content
1/5	#1690	#1688	the v1 event-memory API: tenants, query, expand, events
2/5	#1691	#1690	`memory_query` and `memory_expand` served at `/v1/mcp`
3/5	#1689	main	`memmachine agent install` for Claude Code and Codex, and the docs page
4/5	#1692	#1691	block kinds for tool calls, tool results and injected text
5/5	#1693	#1689	capture through the agents' `Stop` hooks, in the client

`memmachine agent install {claude-code,codex} --server <url> --tenant <name>` points an agent at a MemMachine server's memory tools, and `memmachine agent disable` takes it back out. Both agents speak MCP over streamable HTTP with static headers, so one endpoint (`<server>/v1/mcp`) and one header (`X-MemMachine-Tenant`) serve both, and the tools live on the server. Claude Code's user scope belongs to the `claude` executable, so the installer runs `claude mcp add --transport http --scope user` through it, preceded by `claude mcp remove` because `add` refuses a name it already holds; without that executable on PATH the error names the command to run by hand. Project scope writes `.mcp.json` in the current directory. Codex gets `[mcp_servers.memmachine]` and its `http_headers` table in `$CODEX_HOME/config.toml`, or in `<cwd>/.codex/config.toml` for project scope. A file this installer writes is parsed before it is edited, backed up to `<file>.bak`, and left alone when it already holds the entry, so a second install changes nothing. The Codex tables are replaced or appended as text and every other line is carried over, and the result is parsed back before it is written, so a config the installer cannot edit safely (an inline table, a dotted key) is refused rather than duplicated. Reading TOML needs Python 3.11's tomllib, so on 3.10 the Codex commands say that instead of guessing. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01YBbQgZiCqeoLu83EkbEFHE

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

edwinyyyu

Docs gaps (line comments), plus one on the installer: agent install --dry-run for the Claude user scope checks PATH for claude before the dry-run branch, so a dry run fails on a machine without claude, and its output shows only the add command, not the remove that precedes it.

edwinyyyu · 2026-09-17T22:16:05Z

+
+## Choosing a tenant name
+
+A tenant is one human user: every session of every agent that user runs


The page never says the tenant must exist on the server before the tools work: #1691's resolve_tenant raises TenantNotFoundError -> ToolError, creation is PUT /v1/tenants/{tenant} (#1690), and the installer makes no HTTP request. A reader who follows this section gets tool errors until someone creates the tenant.

Said on #1693 in 947e874: the installer makes no request to the server, the tenant is created once with PUT /v1/tenants/{tenant}, and until then the tools answer an error naming it and the hook keeps its mark and posts again next turn.

edwinyyyu · 2026-09-17T22:16:05Z

+  as one. Its two ends are the handles a further expansion continues
+  from.
+
+A direction that comes back empty means the session ran out that way.


#1691 does not answer an empty side with nothing; it returns a sentence ("Nothing earlier: the session starts here." / "Nothing later: ...").

Corrected on #1693 in 947e874: the page quotes the two sentences.

edwinyyyu · 2026-09-17T22:49:57Z

Folded into #1693, which is the whole client side of the coding-agent integration: the installer, the Stop hook it registers, and capture. Its branch was the base of #1693's, so every commit here is there.

edwinyyyu and others added 4 commits September 17, 2026 13:41

Use neutral names in the coding agents docs examples

f9bc730

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

edwinyyyu mentioned this pull request Sep 17, 2026

[coding agents 1/3] Serve the v1 event-memory API: tenants, query, expand, events #1690

Draft

edwinyyyu changed the title ~~Install the MemMachine MCP server in Claude Code and Codex~~ [coding agents 3/4] Install the MemMachine MCP server in Claude Code and Codex Sep 17, 2026

edwinyyyu and others added 2 commits September 17, 2026 14:02

Name the tool memory_query in the coding agents docs

7b460d2

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

Name the tool memory_query in the installer's module docstring

f6b7bb0

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

edwinyyyu mentioned this pull request Sep 17, 2026

[coding agents 2/3] Serve memory_query and memory_expand over MCP at /v1/mcp #1691

Draft

edwinyyyu marked this pull request as ready for review September 17, 2026 21:13

edwinyyyu changed the title ~~[coding agents 3/4] Install the MemMachine MCP server in Claude Code and Codex~~ [coding agents 3/5] Install the MemMachine MCP server in Claude Code and Codex Sep 17, 2026

edwinyyyu mentioned this pull request Sep 17, 2026

[event memory 5/7] Block kinds for tool calls, tool results, injected text and thinking #1692

Draft

edwinyyyu commented Sep 17, 2026

View reviewed changes

edwinyyyu mentioned this pull request Sep 17, 2026

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

Draft

edwinyyyu closed this Sep 17, 2026

Navigation Menu

Repository navigation

[coding agents 3/5] Install the MemMachine MCP server in Claude Code and Codex - #1689

[coding agents 3/5] Install the MemMachine MCP server in Claude Code and Codex#1689
edwinyyyu wants to merge 6 commits into
MemMachine:mainfrom
edwinyyyu:feat/coding-agent-installer-main

edwinyyyu commented Sep 17, 2026 •

edited

Loading

Uh oh!

edwinyyyu left a comment

Uh oh!

edwinyyyu Sep 17, 2026

Uh oh!

edwinyyyu Sep 17, 2026

Uh oh!

edwinyyyu Sep 17, 2026

Uh oh!

edwinyyyu Sep 17, 2026

Uh oh!

edwinyyyu commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		## Choosing a tenant name

		A tenant is one human user: every session of every agent that user runs

Conversation

edwinyyyu commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What it does

Verified

Two calls to review

Stack: coding agents

Uh oh!

edwinyyyu left a comment

Choose a reason for hiding this comment

Uh oh!

edwinyyyu Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

edwinyyyu Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

edwinyyyu Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

edwinyyyu Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

edwinyyyu commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

edwinyyyu commented Sep 17, 2026 •

edited

Loading