# Agents Memory > Local markdown memory & cross-agent context engine for coding agents (MCP). - **Type:** MCP server - **Install:** `agentstack add mcp-lolaplex-agents-memory` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [Lolaplex](https://agentstack.voostack.com/s/lolaplex) - **Installs:** 0 - **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Lolaplex](https://github.com/Lolaplex) - **Source:** https://github.com/Lolaplex/agents-memory - **Website:** https://pypi.org/project/agents-memory/ ## Install ```sh agentstack add mcp-lolaplex-agents-memory ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Local markdown memory & cross-agent context engine for clankers. One persistent identity, shared across all your agents. ## Quickstart ```bash 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](https://github.com/Lolaplex/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** | `/.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](https://github.com/Lolaplex/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](#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`](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): ```bash agents-memory remote serve --port 8443 --token ``` **2. Clients** (laptops / workstations): ```bash agents-memory connect https://memory.your-domain.com --token ``` - New slugs append. Same-slug edits: incoming wins. Conflicts land in `staging/sync-conflicts.md`. - Project trees sync as `mirror/projects//` 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`](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//…`) | | `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`](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/`](abi/): - [`WHY.md`](abi/WHY.md) β€” why markdown wins over RAG-as-memory - [`LAYOUT.md`](abi/LAYOUT.md) β€” directory contract - [`KINDS.md`](abi/KINDS.md) β€” typed taxonomy - [`HYGIENE.md`](abi/HYGIENE.md) β€” lifetimes, write boundaries - [`MCP.md`](abi/MCP.md) β€” tool surface - [`INGEST.md`](abi/INGEST.md) β€” catalog β†’ extract β†’ distill - [`INJECTION.md`](abi/INJECTION.md) β€” host inject - [`REMOTE.md`](abi/REMOTE.md) β€” mirror bundle (and extra project roots) --- ## Tests ```bash python tests/run_all_tests.py ``` --- ## License MIT. See [LICENSE](LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [Lolaplex](https://github.com/Lolaplex) - **Source:** [Lolaplex/agents-memory](https://github.com/Lolaplex/agents-memory) - **License:** MIT - **Homepage:** https://pypi.org/project/agents-memory/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-lolaplex-agents-memory - Seller: https://agentstack.voostack.com/s/lolaplex - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.