.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	`<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.

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.

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

Fifteen tools. Full contract: 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/:

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.