Skip to main content

.agents / memory

Version 1.2.0 MCP Python 3.10+ PyPI License

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/:


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)

Source distribution for agents-memory 1.3.0
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)

Table of built distributions (wheels) for agents-memory 1.3.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page