Ingests OpenAI/ChatGPT session logs and extracts durable rules, facts, and architecture decisions into the local memory store.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agents-memory search memory for the decision on microservices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pip install agents-memory && agents-memory sync --initScaffolds ~/.agents/memory/, autowires MCP into installed IDEs, and registers assistant skills.
🤖 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.
Related MCP server: agent-julia
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 |
|
|
Per repo |
| facts, ADRs, in-progress work (gitignored) |
Always-on | host | short inject; agents |
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 <!-- agents-memory-sync --> stays. Details: Where it runs.
Cloud sync (new in 1.1.0). Several machines, one vault — see below.
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 ( | Any MCP host / any shell |
Autowire on sync | Merge | Cursor, Claude Code, Claude Desktop, Zed ( |
Always-on / rules | Marked inject block + bound rules |
|
Chat ingest |
| 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). 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.
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 <YOUR_SECRET_TOKEN>2. Clients (laptops / workstations):
agents-memory connect https://memory.your-domain.com --token <YOUR_SECRET_TOKEN>New slugs append. Same-slug edits: incoming wins. Conflicts land in staging/sync-conflicts.md.
Project trees sync as mirror/projects/<slug>/ 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.
After a cleanup, remote push --replace (or remote bump-epoch) bumps the vault epoch. Older clients replace-pull on the next sync. Local edits since the last baseline land in staging/epoch-questions.md (get_staging_inbox) and are not pushed back. Set AGENTS_MEMORY_MIN_CLIENT_VERSION=1.2.0 on the server so 1.1.x writers get HTTP 426.
Layout and merge rules: abi/REMOTE.md.
Primary surface. Agents talk to the vault here — not via scraping CLI help.
Tool | What it does |
| Exact substring, then FTS5 fill. Not chat graves. Known slug → |
| Follow frontmatter |
| File a typed fact; auto-syncs inject |
| Raw file by id ( |
| One slug’s in-tree memory (call when opening a repo) |
| Project map |
| Staging → typed memory |
| Drop a search hit by id |
| Rewrite always-on inject |
| Propose a hard rule into staging (the user applies it) |
Sixteen tools. Full contract: abi/MCP.md. Session snap/grep/tail live on agents-traces.
Always-on rules live in ~/.agents/memory/rules/HARD.md, one imperative rule per line. A project can add projects/<slug>/RULES.md. One renderer builds a <memory_rules> block for the MCP instructions, the first tool result of each session (plus a project's rules on its first project-scoped call), agents-memory context, and the synced AGENTS.md / agent rule. Budget: 30 lines and 2000 characters globally, 10 lines per project (AGENTS_MEMORY_RULES_MAX_LINES, AGENTS_MEMORY_RULES_MAX_CHARS, AGENTS_MEMORY_RULES_PROJECT_MAX_LINES). Agents only propose_rule into staging/rule-proposals.md; the user edits with agents-memory rules.
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 |
| Always-on inject, first-run scaffold, optional mirror push |
| Disk vs |
| MCP vault mirrors (scripts / no-MCP hosts) |
| Chat catalog and staging extract |
| Staging inbox / noise pass |
| Rendered hard rules |
| Edit hard rules (budgeted) |
| Mechanical store health (no LLM) |
| Rebuild disposable FTS5 cache (MCP start already rebuilds) |
| Cloud mirror ( |
| Local viewer / static HTML export |
| Clear local caches / temp state |
| stdio MCP clerk |
extract-openai is deprecated → ingest extract (openai-export source).
Implementation-agnostic layout in abi/:
WHY.md — why markdown wins over RAG-as-memory
LAYOUT.md — directory contract
KINDS.md — typed taxonomy
HYGIENE.md — lifetimes, write boundaries
MCP.md — tool surface
INGEST.md — catalog → extract → distill
INJECTION.md — host inject
REMOTE.md — mirror bundle (and extra project roots)
python tests/run_all_tests.pyMIT. See LICENSE.
This server cannot be deployed
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Shared AI memory. ChatGPT, Claude, Cursor and any MCP app read and write the same memory.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
