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.
Multi-device sync. Unified across all stack domains via agents-sync.
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 (agents-sync)
Cloud and multi-device synchronization for ~/.agents/memory/ (and the entire ~/.agents stack: skills, docs, rules, traces, identity) has been decoupled into the dedicated package: agents-sync.
agents-sync coordinates state across local workstations, laptops, and remote VPS agent servers:
pip install agents-sync
# Connect this node to your cloud vault
agents-sync connect https://vps.example.com:8765 --token YOUR_TOKEN
# 2-way sync across all stack domains (memory, skills, docs, rules, traces, identity)
agents-sync sync
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 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-memoryLAYOUT.md— directory contractKINDS.md— typed taxonomyHYGIENE.md— lifetimes, write boundariesMCP.md— tool surfaceINGEST.md— catalog → extract → distillINJECTION.md— host inject
Tests
python tests/run_all_tests.py
License
MIT. See LICENSE.
Metadata
Release files for agents-memory 1.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agents_memory-1.3.0.tar.gz | 160.3 kB | Without provenance | Details for agents_memory-1.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agents_memory-1.3.0-py3-none-any.whl | Python 3 | none | any | Details for agents_memory-1.3.0-py3-none-any.whl |
Total release size: 305.5 kB
Release files / agents_memory-1.3.0.tar.gz
| Download URL | agents_memory-1.3.0.tar.gz |
|---|---|
| Size | 160.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
714f4892a1331aca11185ab22be3fe5912d6fe60123f5c5570b1109d4607eaf0
|
|
BLAKE2b-256 checksum How to use checksums |
e72fecfa1ae8f3c386b173ca5aeb9bf1dc68a6ecdc1d75839fc46ae6b6502163
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
Release files / agents_memory-1.3.0-py3-none-any.whl
| Download URL | agents_memory-1.3.0-py3-none-any.whl |
|---|---|
| Size | 145.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b49d124934971235bbd90735b349a988a1fc2f2b1195e2f3590af124d07699ca
|
|
BLAKE2b-256 checksum How to use checksums |
767a3443dd0737b3e4e0869de19b740c6652c6e5c5d0ee5008c5ca3c171d0b98
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
Security for agents-memory 1.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.