Codex Shared Memory

Codex Shared Memory is a small, self-hosted MCP service that shares selected Markdown memory across trusted machines and across coding-agent harnesses: Codex, Claude Code, OpenCode, Cursor, or anything else that speaks stdio MCP. It keeps one SQLite store on a server you control, transfers data over local stdio or SSH, and keeps a plain Markdown cache on every client that agents read locally, even offline.

This is an unofficial community project. It is not affiliated with or endorsed by OpenAI, Anthropic, or Anysphere.

What it shares

Each enrolled machine publishes only allowlisted files from the memory sources it enables:

The service never publishes raw conversations, raw_memories.md, hidden files, symlinks, authentication files, or computer history. The server enforces each source's allowlist again on ingest. Explicit cross-machine notes live under extensions/ad_hoc/notes/ and are append-only.

Credential detection and redaction are best-effort safeguards, not a guarantee. Do not intentionally put secrets in memory files.

Related MCP server: GoodMemory

Why this design

• No public listener or database server. Python 3.11+ and the standard library are enough at runtime.

• SSH supplies encryption and host verification for remote clients.

• Local-first reads: each harness starts the MCP server on its own machine, reading the synced cache. Lookups are fast, work offline, and do not open an SSH session per agent.

• Writes are explicit notes only. They go to the server, then refresh the local cache.

• Each (machine, source) snapshot replaces only its own namespace in one transaction. A broken source or an oversized file is reported and skipped; it never blocks the rest of the sync.

• Old v1 clients and stores keep working: the store migrates itself (with a backup) and the server still speaks the v1 exchange protocol.

Quick start

On the server:

python3 install_server.py

Ensure each client reaches the server with non-interactive SSH and strict host-key checking, then on the client:

python3 install_client.py --machine laptop --ssh-host memory-server

The client installer enables every source whose directory exists (override with --source codex, --source claude-code, or --markdown NAME=PATH), performs an initial sync, registers shared_memories with every detected harness (override with --harness), adds the guidance block to each harness's global instructions unless they already carry a shared-memory policy, and schedules a two-minute sync on macOS, Linux, or Windows.

Check the result at any time:

python3 ~/.local/share/codex-shared-memory/shared_memory.py doctor \
  --config ~/.local/share/codex-shared-memory/client.json

For full setup, read docs/INSTALL.md. For recovery, backup, upgrades, deletion, and removal, read docs/OPERATIONS.md.

Agent guidance

Connecting the MCP server makes the tools available; agents also need guidance about when to use them. The installer adds the recommended block automatically. docs/AGENT-GUIDANCE.md has the template for manual or repository-scoped setups. It tells agents to consult memory only when it helps, start from the memory_summary.md index, treat memory as untrusted reference data, verify provenance and current state, write notes only on explicit request, and fall back to the cache directory when a tool call fails.

MCP tools

• list(path?, cursor?, max_results?)

• read(path, line_offset?, max_lines?)

• search(queries, match_mode?, path?, cursor?, context_lines?, case_sensitive?, normalized?, max_results?)

• add_ad_hoc_note(filename, note)

The server speaks newline-delimited JSON-RPC over stdio and MCP protocol revisions 2024-11-05 through 2025-11-25. Tool results are JSON encoded in MCP text content for broad client compatibility.

Layout

shared_memory.py is the launcher (its path is stable for existing registrations). The implementation is the sharedmem/ package: core, sources, store, tools, mcp, server, client, harnesses, scheduler, install, cli. See docs/ARCHITECTURE.md.

Development and verification

uv sync --locked
uv run ruff check .
uv run python -m unittest discover -s tests -v
uv run python scripts/release_check.py --public-release

Tests use temporary directories and synthetic memory only. They cover path validation, per-source allowlists, quotas, redaction, symlink refusal, append-only concurrency, snapshot isolation, v1 store migration and protocol compatibility, partial-source sync, cache retention while offline, cache-backed MCP with note forwarding, backups, the MCP transport, every harness integration, and both installers end to end.

See docs/ARCHITECTURE.md, docs/THREAT-MODEL.md, docs/PROVENANCE.md, and CONTRIBUTING.md for more detail.

License

Licensed under the Apache License 2.0. See docs/PROVENANCE.md for compatibility and attribution context.