Cross Agent Memory Kit

cross-agent-memory-kit

English | [Українська](README.uk.md)

What is it for: AI coding agents start every session cold. They forget the decisions, conventions, and dead ends from your last conversation, so you keep re-explaining the same context. This kit gives them a persistent, self-updating memory: after each session it distills what happened into durable facts and stores them, so the next session - on any agent, on any of your machines - already knows.

Working solo, one memory follows you across devices. Sharing one account with a team or family? The optional multi-user mode gives each person a private memory plus a shared store, with hard isolation so private notes stay private - see [MULTI-USER.md](MULTI-USER.md).

Reproducible configuration for mcp-memory-service on macOS and Linux machines (not tested on Windows), plus the custom Claude Code skill and post-session distillation hook that wrap it.

This repo is the source of truth. Point any AI agent (Claude Code, Codex, Gemini, Cursor, Windsurf, Lovable, Kiro, ...) at this folder and it has everything needed to reproduce the setup on a fresh machine.

Current setup version: 0.2.0-dev from VERSION.

What you get when you reproduce this

1. mcp-memory-service running locally as a stdio MCP server. SQLite-vec storage. Persists facts, decisions, conventions, mistake notes, and session distillations across conversations.
2. A /mcp-memory-query skill (or its equivalent for non-Claude agents) that teaches the agent how to retrieve from the service.
3. A post-session distillation hook that, after each Claude Code session, sends the transcript to a chosen LLM (Claude, Codex, Gemini, OpenRouter, ...) and stores the extracted artifacts + facts back into the memory service.
4. LangSmith tracing for every distillation call, so you can see prompt, response, latency, and cost per session in the LangSmith dashboard.
5. Optional multi-device sync. Switch the server to its hybrid backend and one memory is shared across all your machines, with Cloudflare (D1 + Vectorize) as the source of truth and a local SQLite cache per device. See [MULTI-DEVICE-SYNC.md](MULTI-DEVICE-SYNC.md).
6. Optional multi-user split (shared account). When one agent account is used by several people - a company team or a family - give each person a private memory store plus a shared team/family store, with hard isolation (separate Cloudflare D1 databases, so others physically cannot read your private memory). Run python3 onboard_multiuser.py, or hand the copy-paste install prompt in [MULTI-USER.md](MULTI-USER.md) to your agent. See [MULTI-USER.md](MULTI-USER.md).

Repo layout

cross-agent-memory-kit/
├── onboard.py                        # interactive install wizard (start here)
├── onboard_multiuser.py              # wizard for a shared account (private + shared stores)
├── .env.example                      # template - copy to .env and fill in
├── .env                              # (gitignored) actual secrets
├── .gitignore
├── LICENSE
├── README.md                         # this file
├── MULTI-DEVICE-SYNC.md              # share one memory across devices (Cloudflare)
├── MULTI-USER.md                     # one account, many people: private + shared memory
├── CHANGELOG.md
├── VERSION                           # machine-readable setup repo version
├── USECASES.md                       # what this setup is used for
├── LESSONS_LEARNED.md                # gotchas, design decisions
├── config/
│   ├── providers.example.yaml        # provider/model config for the hook
│   └── profiles.example.yaml         # reference shape of one person's stores (multi-user)
├── hooks/
│   └── distill_session.py            # Claude Code SessionEnd wrapper
├── distill/
│   ├── engine.py                     # shared distillation flow
│   ├── prompt.md                     # single source of truth for memory rules
│   ├── storage.py                    # writes to mcp-memory-service DB
│   ├── providers.py                  # LLM provider calls and config
│   ├── registry.py                   # optional project/client slug registry
│   └── adapters/                     # raw transcript -> normalized transcript
├── wrappers/
│   ├── codex_session_scan.py         # Codex pull-based scanner/wrapper
│   ├── cursor_session_scan.py        # Cursor pull-based scanner/wrapper
│   ├── provenance_backfill.py        # dry-run provenance audit/backfill helper
│   └── usage_report.py               # token usage report from distill_runs
├── launchd/
│   └── memory-distill.plist.template # rendered per-machine by the watcher installers
├── skills/
│   ├── mcp-memory-query/
│   │   └── SKILL.md                  # retrieval skill (single-user)
│   └── mcp-memory-multiuser/
│       └── SKILL.md                  # retrieval + write-routing skill (shared account)
└── scripts/
    ├── install.sh                    # idempotent low-level installer
    ├── check_version.py              # VERSION / changelog / tag verification
    ├── install_codex_watcher.sh      # installs the Codex launchd scanner
    ├── install_cursor_watcher.sh     # installs the Cursor launchd scanner
    └── setup_multiuser_cloudflare.sh # creates shared + per-person Cloudflare D1/Vectorize

Prerequisites

• macOS or Linux (Windows untested).
• Python 3.10+ available as python3.
• One or more of these LLM CLIs / API keys:
• claude CLI (Anthropic-logged-in) - subscription auth, used by default
• codex CLI - subscription auth
• gemini CLI - subscription auth
• cursor-agent CLI - subscription auth
• OPENROUTER_API_KEY - per-token billing
• ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY - per-token billing

You only need ONE provider configured. The hook picks based on config/providers.yaml.

Quickstart: the interactive wizard

The fastest path is onboard.py. It walks you through everything: creates/reuses the venv, picks a distillation provider, optionally configures the Cloudflare hybrid backend for multi-device sync, writes .env and config/providers.yaml, and prints the exact MCP server block to paste into your agent's config. It never overwrites an existing memory database.

git clone  cross-agent-memory-kit
cd cross-agent-memory-kit
python3 onboard.py            # interactive; --help for non-interactive flags

The wizard never edits your agent config files for you - it prints the JSON/TOML block and tells you where to paste it, so it can't corrupt a config by guessing.

Quickstart: manual

If you prefer to do it by hand:

git clone  cross-agent-memory-kit
cd cross-agent-memory-kit
cp .env.example .env                    # then edit .env with your keys
cp config/providers.example.yaml config/providers.yaml   # then edit if you want a non-default provider
bash scripts/install.sh                 # idempotent: creates/reuses venv, prints MCP config blocks

install.sh does the following, idempotently:

1. Creates a Python venv at ~/.local/share/mcp-memory-service-venv/ only if it does not already exist.
2. Checks whether mcp-memory-service, LangSmith, LangChain providers, python-dotenv, and pyyaml already import successfully.
3. Skips dependency installation when the existing venv is healthy.
4. Installs missing dependencies without forcing upgrades when the venv is incomplete.
5. Prints the MCP server block to add to each AI agent's config.
6. Does not auto-edit agent configs, install skills, wire hooks, or modify the memory database.

To intentionally upgrade Python packages, pass:

bash scripts/install.sh --upgrade-deps

Existing install: preservation-first rule

If mcp-memory-service is already working through Claude Code or another agent, do not reinstall from scratch. Do not delete or recreate:

• ~/.local/share/mcp-memory-service-venv/
• ~/Library/Application Support/mcp-memory/ on macOS
• ~/.local/share/mcp-memory/ on Linux
• any sqlite_vec.db, sqlite_vec.db-wal, or sqlite_vec.db-shm files

For Codex, Cursor, Gemini, or Kiro on a machine that already has the service, the usual task is only:

1. Point the agent's MCP config at the existing venv Python:

``text /Users//.local/share/mcp-memory-service-venv/bin/python -m mcp_memory_service.server ``

1. Install the agent-specific retrieval instructions or skill.
2. Restart the agent so the MCP tools are loaded.

scripts/install.sh is safe to run for verification because it now reuses an existing healthy venv and preserves the database path it detects. Still, agents should prefer registering the existing server over running package installation when the venv and DB are already present.

Manual setup, per AI agent

Claude Code

The MCP server config goes into ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "/Users//.local/share/mcp-memory-service-venv/bin/python",
      "args": ["-m", "mcp_memory_service.server"],
      "env": {}
    }
  }
}

The skill goes into ~/.claude/skills/mcp-memory-query/SKILL.md (copy from skills/mcp-memory-query/SKILL.md in this repo).

The SessionEnd hook goes into ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/cross-agent-memory-kit/hooks/distill_session.py",
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

The hook script's shebang points at the venv Python (which has mcp_memory_service importable). It is only a Claude wrapper; distillation rules live in distill/prompt.md and the shared engine under distill/.

Codex CLI

MCP servers are registered in ~/.codex/config.toml:

[mcp_servers.memory]
command = "/Users//.local/share/mcp-memory-service-venv/bin/python"
args = ["-m", "mcp_memory_service.server"]

For Codex skills, copy the repo skill folder directly:

mkdir -p ~/.codex/skills/mcp-memory-query
cp skills/mcp-memory-query/SKILL.md ~/.codex/skills/mcp-memory-query/SKILL.md

Only create a Codex-specific copy in this repo, for example skills/codex_mcp-memory-query/SKILL.md, if the installed Codex skill must diverge from the shared skill. As of 2026-05-06, the Codex-installed skill is identical to skills/mcp-memory-query/SKILL.md, so no separate Codex copy is needed.

Codex doesn't currently expose a SessionEnd hook. The repo provides a pull-based scanner that watches Codex session JSONL files and calls the shared distillation engine with Codex provider defaults:

python wrappers/codex_session_scan.py --dry-run --quiet-minutes 0 --lookback-days 2 --limit 2

Install the macOS launchd watcher:

bash scripts/install_codex_watcher.sh

The installer first marks existing quiet Codex sessions as baseline in ~/.local/state/cross-agent-memory-kit/codex-processed.json, then runs the scanner daily at 04:00 local time. The scheduled scan looks back 14 days and handles at most five sessions. It stops after three consecutive failures, retries failed sessions with exponential backoff, and quarantines a session after three automatic attempts. State is saved after each handled session, and a file lock prevents overlapping scans.

Codex provider calls pass the prompt through stdin and read the validated JSON response from --output-last-message under --output-schema. They use --ignore-user-config so unrelated settings in ~/.codex/config.toml cannot break scheduled distillation, and --ephemeral prevents the provider call from creating a new scanner input. The scanner defaults to the verified gpt-5.5 selector. Pass --model to override it after verifying another exact selector with the installed CLI and account.

Scheduled scans set LANGSMITH_TRACING=false and LANGCHAIN_TRACING_V2=false. Tracing remains available for manual runs by explicitly setting LANGSMITH_TRACING=true.

Retry one quarantined session in a bounded run:

python wrappers/codex_session_scan.py --session-path /absolute/path/to/session.jsonl --retry-quarantined --limit 1

Reset a known failure record without deleting processed state:

python wrappers/codex_session_scan.py --reset-failure SESSION_ID --dry-run --limit 1

Historical distill_runs are retained. If cleanup is ever required, first copy the SQLite database to a dated backup, then run a separately reviewed SQL delete command. The installer and scanner do not delete historical runs.

Codex scanner logs:

~/.local/state/cross-agent-memory-kit/logs/codex.log
~/.local/state/cross-agent-memory-kit/logs/codex-launchd.out.log
~/.local/state/cross-agent-memory-kit/logs/codex-launchd.err.log

Cursor

Cursor's MCP config lives in ~/.cursor/mcp.json with the same shape as Claude Code's mcpServers block.

For the skill: paste SKILL.md contents into a Cursor Project Rule under .cursor/rules/mcp-memory-query.mdc.

Cursor doesn't expose a SessionEnd hook. The repo provides a pull-based scanner that watches Cursor session JSONL files and calls the shared distillation engine with Cursor provider defaults:

python wrappers/cursor_session_scan.py --dry-run --quiet-minutes 0 --lookback-days 2 --limit 2

Install the macOS launchd watcher:

bash scripts/install_cursor_watcher.sh

The installer first marks existing quiet Cursor sessions as baseline in ~/.local/state/cross-agent-memory-kit/cursor-processed.json, then runs the scanner daily at 04:00 local time. Future quiet sessions are distilled once with DISTILL_PROVIDER=cursor-cli and DISTILL_MODEL=sonnet-4. The launchd job uses --limit 0 so the daily run drains all unprocessed quiet sessions.

Cursor scanner logs:

~/.local/state/cross-agent-memory-kit/logs/cursor.log
~/.local/state/cross-agent-memory-kit/logs/cursor-launchd.out.log
~/.local/state/cross-agent-memory-kit/logs/cursor-launchd.err.log

Windsurf

Windsurf (Cascade) reads MCP servers from ~/.codeium/windsurf/mcp_config.json, with the same mcpServers shape as Claude Code. You can also open it from the Cascade panel: click the MCPs icon, then Configure.

{
  "mcpServers": {
    "memory": {
      "command": "/Users//.local/share/mcp-memory-service-venv/bin/python",
      "args": ["-m", "mcp_memory_service.server"],
      "env": {}
    }
  }
}

For the skill, paste SKILL.md into your Windsurf rules (global rules, or a file under .windsurf/rules/). Windsurf has no SessionEnd hook, so distill manually or on a schedule, the same way as Codex/Cursor.

Gemini CLI

Gemini CLI uses ~/.gemini/settings.json:

{
  "mcpServers": {
    "memory": {
      "command": "/Users//.local/share/mcp-memory-service-venv/bin/python",
      "args": ["-m", "mcp_memory_service.server"]
    }
  }
}

Skill equivalent: paste SKILL.md into GEMINI.md at the project root.

Hook: same as Codex/Cursor - manual or scheduled invocation.

Kiro.dev

Kiro reads ~/.kiro/settings/mcp.json. Same mcpServers shape as Claude Code. Skills get pasted into Kiro's steering doc.

Lovable

Lovable is a cloud app builder, so it works differently from the local agents above: it connects to MCP servers by URL, not by spawning a local process. The stdio config in this repo does not apply directly - Lovable cannot reach a Python process on your machine.

To use this memory server with Lovable, first run mcp-memory-service in a remote/HTTP transport so it has a reachable HTTPS endpoint (see the mcp-memory-service docs for its HTTP server mode). Then, in Lovable, open Connectors > Chat connectors, add a custom MCP server, and enter:

• Server URL: your memory server's HTTPS endpoint
• Auth: OAuth, bearer token, or API key a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: internetyev
• Source: internetyev/cross-agent-memory-kit
• License: MIT

Install and usage instructions live in the source repository linked above.