Back to packageRELEASE DETAILS

1.2.0

PyPI

agents-memory

Local markdown memory & cross-agent context engine for coding agents (MCP).

Published6 Oct 2026

Direct dependencies1

Transitive dependenciesNot calculated

README

Version 1.2.0 documentation

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

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 1

Native requirements

1 direct targetsNot calculated transitive count

Package / target	Requirement	Relationship
mcp Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`mcp<2,>=1.0.0`	runtime

Distribution files

2 collected

agents_memory-1.2.0-py3-none-any.whl

bdist_wheel · 190.08 KB · Python py3

Source file

agents_memory-1.2.0.tar.gz

sdist · 210.88 KB · Python source

Source file

Repository

PENDING

lolaplex/agents-memory

Shared repository data · GitHub

License detected in repository: Not collected

Metadata history

Meaningful changes

Current collected state Current

Observed since 20 Oct, 23:26 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:332c359d93c23e4757ae1a3e20122272e8837e8dfd437642d91c809c2e5ca302

Other collected versions

View all collected versions →