# Cross Agent Memory Kit > Persistent, self-updating memory for AI coding agents (Claude Code, Codex, Cursor, Gemini, Kiro, Hermes). Built on mcp-memory-service: a post-session distillation hook, a retrieval skill, optional Cloudflare multi-device sync, multi-user mode (private + shared memory on one shared account), and an interactive install wizard. - **Type:** MCP server - **Install:** `agentstack add mcp-internetyev-cross-agent-memory-kit` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [internetyev](https://agentstack.voostack.com/s/internetyev) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [internetyev](https://github.com/internetyev) - **Source:** https://github.com/internetyev/cross-agent-memory-kit ## Install ```sh agentstack add mcp-internetyev-cross-agent-memory-kit ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/doobidoo/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. ```bash 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: ```bash 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 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 ``` 2. Install the agent-specific retrieval instructions or skill. 3. 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`: ```json { "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`: ```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`: ```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: ```bash 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: ```bash python wrappers/codex_session_scan.py --dry-run --quiet-minutes 0 --lookback-days 2 --limit 2 ``` Install the macOS launchd watcher: ```bash 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: ```bash 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: ```bash 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: ```text ~/.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: ```bash python wrappers/cursor_session_scan.py --dry-run --quiet-minutes 0 --lookback-days 2 --limit 2 ``` Install the macOS launchd watcher: ```bash 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: ```text ~/.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. ```json { "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`: ```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](https://github.com/doobidoo/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](https://github.com/internetyev) - **Source:** [internetyev/cross-agent-memory-kit](https://github.com/internetyev/cross-agent-memory-kit) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-internetyev-cross-agent-memory-kit - Seller: https://agentstack.voostack.com/s/internetyev - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.