Metadata-Version: 2.4
Name: agents-memory
Version: 1.3.0
Summary: Local markdown memory & cross-agent context engine for coding agents (MCP).
Author: Lolaplex
License-Expression: MIT
Project-URL: Homepage, https://github.com/Lolaplex/agents-memory
Project-URL: Repository, https://github.com/Lolaplex/agents-memory
Project-URL: Documentation, https://github.com/Lolaplex/agents-memory/tree/main/abi
Project-URL: Bug Tracker, https://github.com/Lolaplex/agents-memory/issues
Keywords: mcp,agents,memory,cursor,claude,coding-assistant
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.0.0
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Lolaplex/.github/main/assets/agents-memory/hero-4x1.png" alt=".agents / memory" width="1280">
</p>

<p align="center">
  <a href="https://github.com/Lolaplex/agents-memory/releases"><img src="https://img.shields.io/badge/version-1.2.0-blue.svg?style=flat-square" alt="Version 1.2.0"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Standard-orange.svg?style=flat-square" alt="MCP"></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-3776AB.svg?style=flat-square&logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="https://pypi.org/project/agents-memory/"><img src="https://img.shields.io/pypi/v/agents-memory.svg?style=flat-square" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
</p>

<p align="center">
  <strong>Local markdown memory &amp; cross-agent context engine for clankers.</strong><br>
  One persistent identity, shared across all your agents.
</p>

## 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** | `<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 `<!-- agents-memory-sync -->` stays. Details: [Where it runs](#where-it-runs).

**Multi-device sync.** Unified across all stack domains via [`agents-sync`](https://github.com/Lolaplex/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`](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`**](https://github.com/Lolaplex/agents-sync).

`agents-sync` coordinates state across local workstations, laptops, and remote VPS agent servers:

```bash
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`](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/`](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

---

## Tests

```bash
python tests/run_all_tests.py
```

---

## License

MIT. See [LICENSE](LICENSE).
