agents-memory 1.2.0

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.

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	<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 <!-- agents-memory-sync --> stays. Details: 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). 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 <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.

---

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/<slug>/…)
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
propose_rule	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.

Hard rules

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.

---

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 context [--project X] [--format md|json]	Rendered hard rules
agents-memory rules show|add|edit|remove|set|check	Edit hard rules (budgeted)
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). remote pull --replace matches this machine to the snapshot. remote push --replace and remote bump-epoch publish a cleaned vault
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/:

• 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)

---

Tests

python tests/run_all_tests.py

---

License

MIT. See LICENSE.