Agents Memory

Local markdown memory & cross-agent context engine for clankers. One persistent identity, shared across all your agents.

Quickstart

pip install agents-memory && agents-memory sync --init

Scaffolds ~/.agents/memory/, autowires MCP into installed IDEs, and registers assistant skills.

> [!TIP] > 🤖 Agent-Driven Setup: > Give your coding agent this repo (clone or URL), then tell it to "install and set up agents-memory."

Source checkouts can also be installed and managed with vand.

---

What it does

Vendors keep chat in product graves (Cursor jsonl, Claude sessions, Antigravity brains, Open AI exports). agents-memory is the portable layer on top: identity, project map, typed facts. Markdown on disk is the source of truth. MCP is a clerk, not a second store. The search index is disposable FTS5 — delete it, rebuild, same results.

| Layer | Where | What lives there | | --- | --- | --- | | Global | ~/.agents/memory/ | USER.md, PROJECTS.md, concepts, decisions, staging | | Per repo | /.agents/memory/ | facts, ADRs, in-progress work (gitignored) | | Always-on | host AGENTS.md / rules | short inject; agents search_memory for the rest |

Search. search_memory tries exact substring first, then FTS5 fill. get_related follows explicit frontmatter relations (refs, supersedes, same_as), not cosine similarity. Known project slug → get_project_memories.

Ingest → staging → distill. Catalog writes titles and paths to chats-index.md. Extract filters user lines into staging/ (PII, how-tos, dumps dropped). You (or distill_batch / memory-distill) promote durable facts into typed files. Chat bodies never become memory. Conversation logs belong to agents-traces.

IDE injection. One sync splices always-on context into hosts it knows (AGENTS.md / rules) and merges MCP where a config file already lives. Text outside `` stays. Details: [Where it runs](#where-it-runs).

Cloud sync (new in 1.1.0). Several machines, one vault — see below.

---

Where it runs

Floor: anywhere with a terminal or an MCP client. Markdown vault + python -m agents_memory mcp is enough. No IDE lock-in.

Deeper support is layered — sync --init autowires what it finds on disk; ingest only covers graves we actually parse.

| Layer | What you get | Who | |-------|----------------|-----| | Vault + MCP/CLI | Full tools (search_memory, add_memory, …) or CLI mirrors | Any MCP host / any shell | | Autowire on sync | Merge agents-memory into host MCP config; splice always-on AGENTS.md; install skills where the host has a slot | Cursor, Claude Code, Claude Desktop, Zed (context_servers), Antigravity / Gemini, Windsurf, Codex MCP paths, Roo, Cline | | Always-on / rules | Marked inject block + bound rules | ~/.agents/AGENTS.md (canonical); also Gemini, Zed, Claude home; rules → Cursor / Gemini / Windsurf | | Chat ingest | ingest catalog + extract → chats-index.md + staging (bodies stay in product folders) | Cursor, Claude Code, Antigravity, VS Code Copilot, Windsurf, Roo, Cline, Pi, Open AI GDPR export |

Ingest ≠ “supports the product.” Titles/paths + filtered user bullets only — same contract for every source ([abi/INGEST.md](abi/INGEST.md)). Distill is still agent/human judgment.

MCP without autowire: Aider, Continue, Goose, stock Copilot Chat, … — point the host at our stdio server yourself. Vault works; we just do not invent their config path.

Not ingested yet: live Codex rollouts, ChatGPT desktop LevelDB, vendor /memory clouds. Add a source when a parser exists — do not wholesale-import foreign memory.

---

Cloud sync

Mirror the personal store across laptops, a VPS, and other workstations. Each device keeps local files as the working copy. The server holds a merged bundle. MCP tools still run locally; push/pull keeps devices aligned.

1. Host (VPS / always-on box):

agents-memory remote serve --port 8443 --token 

2. Clients (laptops / workstations):

agents-memory connect https://memory.your-domain.com --token 

• New slugs append. Same-slug edits: incoming wins. Conflicts land in staging/sync-conflicts.md.
• Project trees sync as mirror/projects// in the bundle, then merge back into registered clones.
• Ingest still reads local chat folders, then pushes the distilled markdown.
• agents-memory disconnect pulls a last snapshot and restores stdio MCP.

Layout and merge rules: [abi/REMOTE.md](abi/REMOTE.md).

---

MCP tools

Primary surface. Agents talk to the vault here — not via scraping CLI help.

| Tool | What it does | | :--- | :--- | | search_memory | Exact substring, then FTS5 fill. Not chat graves. Known slug → get_project_memories. | | get_related | Follow frontmatter refs / supersedes / same_as from a hit id | | add_memory | File a typed fact; auto-syncs inject | | read_memory_file / write_memory_file | Raw file by id (user/USER.md, project//…) | | get_project_memories | One slug’s in-tree memory (call when opening a repo) | | list_projects / inventory_projects / register_project / ignore_project | Project map | | get_staging_inbox / distill_batch / auto_distill | Staging → typed memory | | delete_memory | Drop a search hit by id | | sync_local_agents_md | Rewrite always-on inject |

Fifteen tools. Full contract: [abi/MCP.md](abi/MCP.md). Session snap/grep/tail live on agents-traces.

---

CLI

Ops / install / batch. Humans and agents rarely need the vault CRUD verbs — those mirror MCP for scripts. Machine-readable catalog: python -m agents_memory --help-json (do not scrape --help).

| Command | Purpose | |---------|---------| | agents-memory sync [--init] [--push] | Always-on inject, first-run scaffold, optional mirror push | | agents-memory inventory [--register …] [--repair-moved] | Disk vs PROJECTS.md; register or fix moved clones | | agents-memory search / add / read / write / delete / related | MCP vault mirrors (scripts / no-MCP hosts) | | agents-memory ingest catalog\|extract\|status | Chat catalog and staging extract | | agents-memory distill [--auto] | Staging inbox / noise pass | | agents-memory check | Mechanical store health (no LLM) | | agents-memory rebuild-index | Rebuild disposable FTS5 cache (MCP start already rebuilds) | | agents-memory remote … / connect / disconnect | Cloud mirror (connect/disconnect = aliases) | | agents-memory serve / web | Local viewer / static HTML export | | agents-memory reset --yes | Clear local caches / temp state | | agents-memory mcp | stdio MCP clerk |

extract-openai is deprecated → ingest extract (openai-export source).

---

ABI

Implementation-agnostic layout in [abi/](abi/):

• [WHY.md](abi/WHY.md) — why markdown wins over RAG-as-memory
• [LAYOUT.md](abi/LAYOUT.md) — directory contract
• [KINDS.md](abi/KINDS.md) — typed taxonomy
• [HYGIENE.md](abi/HYGIENE.md) — lifetimes, write boundaries
• [MCP.md](abi/MCP.md) — tool surface
• [INGEST.md](abi/INGEST.md) — catalog → extract → distill
• [INJECTION.md](abi/INJECTION.md) — host inject
• [REMOTE.md](abi/REMOTE.md) — mirror bundle (and extra project roots)

---

Tests

python tests/run_all_tests.py

---

License

MIT. See [LICENSE](LICENSE).

Source & license

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

• Author: Lolaplex
• Source: Lolaplex/agents-memory
• License: MIT
• Homepage: https://pypi.org/project/agents-memory/

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