{
"markdown": "# agentmem\n\nShared memory for Claude Code, Cursor, and Codex that knows what's still true. Save sessions, catch stale and conflicting rules, and stop your agent from repeating old mistakes.\n\n[](https://pypi.org/project/quilmem/)\n[](https://pypi.org/project/quilmem/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/thezenmonster/agentmem/actions)\n\n## The Problem\n\nYour AI coding assistant forgets everything between sessions. It repeats old mistakes. It can't tell current rules from outdated ones. Context compresses and recovery is painful.\n\nMost memory tools solve **storage**. agentmem solves **trust**.\n\n## Get Started (Claude Code / Cursor / Codex)\n\n```bash\npip install quilmem[mcp]\nagentmem init --tool claude --project myapp\n```\n\nThat's it. Restart your editor. Your agent now has 13 memory tools. Run `memory_health` to confirm.\n\n
\n \n
\n\n> **Python-only?** `pip install quilmem` works without the MCP extra. See the [Python API](#python-api) below.\n\n## 60-Second Demo\n\n```python\nfrom agentmem import Memory\n\nmem = Memory()\n\n# Store typed memories\nmem.add(type=\"bug\", title=\"loudnorm undoes SFX levels\",\n content=\"Never apply loudnorm to final mix. It re-normalizes everything.\",\n status=\"validated\")\n\nmem.add(type=\"decision\", title=\"Use per-line atempo\",\n content=\"Bake speed into per-line TTS. No global pass.\",\n status=\"active\")\n\n# Something you're not sure about yet\nhypothesis = mem.add(type=\"decision\", title=\"Maybe try 2-second gaps before CTA\",\n content=\"Hypothesis from last session. Needs testing.\",\n status=\"hypothesis\")\n\n# Search — validated and active memories rank highest.\n# Deprecated and superseded memories are excluded automatically.\nresults = mem.search(\"audio mixing\")\n\n# Context-budgeted recall — fits the best memories into your token limit\ncontext = mem.recall(\"building a narration track\", max_tokens=2000)\n\n# Lifecycle — promote what's proven, deprecate what's not\nmem.promote(hypothesis.id) # hypothesis -> active -> validated\nmem.deprecate(hypothesis.id, reason=\"Disproven by data\")\n\n# Supersede: replace an outdated memory with a newer one\nreplacement = mem.add(type=\"decision\", title=\"Use 1-second gaps before CTA\",\n content=\"Confirmed by A/B test.\", status=\"active\")\nmem.supersede(hypothesis.id, replacement.id) # old points to replacement\n\n# Health check — is your memory system trustworthy?\nfrom agentmem import health_check\nreport = health_check(mem._conn)\n# Health: 85/100 | Conflicts: 0 | Stale: 2 | Validated: 14\n```\n\n## What Makes This Different\n\n**Other memory tools store things.** agentmem knows what's still true.\n\n| | Mem0 | Letta | Mengram | agentmem |\n|---|---|---|---|---|\n| Memory storage | Yes | Yes | Yes | Yes |\n| Full-text search | Vector | Agent-driven | Knowledge graph | **FTS5** |\n| Memory lifecycle states | No | Partial | No | **hypothesis -> active -> validated -> deprecated -> superseded** |\n| Conflict detection | No | No | Partial | **Built-in** |\n| Staleness detection | No | No | No | **Built-in** |\n| Health scoring | No | No | No | **Built-in** |\n| Provenance tracking | No | No | No | **source_path + source_hash** |\n| Trust-ranked recall | No | No | No | **Validated > active > hypothesis** |\n| Human-readable source files | No | No | No | **Canonical markdown** |\n| Local-first, zero infrastructure | No | Self-host option | Self-host option | **Yes, always** |\n| MCP server | Separate | Separate | Yes | **Built-in** |\n\n## Truth Governance\n\nThe core idea: every memory has a **status** that tracks how much you should trust it.\n\n```\nhypothesis New observation. Not yet confirmed. Lowest trust in recall.\n |\n active Default. Currently believed true. Normal trust.\n |\n validated Explicitly confirmed. Highest trust in recall.\n\n deprecated Was true, no longer. Excluded from recall. Kept for history.\n superseded Replaced by a newer memory. Points to replacement.\n```\n\n**Why this matters:** Without governance, your agent's memory accumulates stale rules, contradictions, and outdated decisions. It doesn't know that the voice setting from January was overridden in March. It retrieves both and the LLM picks randomly. Governed memory solves this.\n\n## Conflict Detection\n\n```python\nfrom agentmem import detect_conflicts\n\nconflicts = detect_conflicts(mem._conn)\n# Found 2 conflict(s):\n# !! [decision] \"Always apply loudnorm to voice\"\n# vs [decision] \"NEVER apply loudnorm to voice\"\n# Contradiction on shared topic (voice, loudnorm, audio)\n```\n\nagentmem finds memories that contradict each other:\n- Detects topic overlap (Jaccard similarity)\n- Separates **duplicates** from **contradictions**\n- Sentence-level negation matching (not just keyword scanning)\n- Severity: `critical` (both active) vs `warning` (one deprecated)\n\n## Staleness Detection\n\n```python\nfrom agentmem import detect_stale\n\nstale = detect_stale(mem._conn, stale_days=30)\n# [decision] \"Use atempo 0.90\" — Source changed since import (hash mismatch)\n# [bug] \"Firewall blocks port\" — Not updated in 45 days\n```\n\nFinds outdated memories by:\n- Age (not updated in N days)\n- Source file missing (referenced file was deleted)\n- Hash drift (source file content changed but memory wasn't updated)\n\n## Health Check\n\n```python\nfrom agentmem import health_check\n\nreport = health_check(mem._conn)\nprint(f\"Health: {report.health_score}/100\")\nprint(f\"Conflicts: {len(report.conflicts)}\")\nprint(f\"Stale: {len(report.stale)}\")\n```\n\nScores your memory system 0-100 based on: conflicts, stale percentage, orphaned references, deprecated weight, and whether you have any validated memories.\n\n## Provenance-Aware Sync\n\nSync canonical markdown files into the DB with source tracking:\n\n```python\n# Each memory tracks where it came from\nmem.add(type=\"bug\", title=\"loudnorm lifts noise\",\n content=\"...\",\n source_path=\"/docs/errors.md\",\n source_section=\"Audio Bugs\",\n source_hash=\"a1b2c3d4e5f6\")\n```\n\nThe sync engine:\n- **Same hash = skip** (idempotent, re-running changes nothing)\n- **Different hash = update** (source file changed)\n- **Section removed = deprecate** (with reason)\n- **Section restored = resurrect** (reactivates deprecated memory)\n\n## Three Interfaces\n\n### Python API\n\n```python\nfrom agentmem import Memory\n\nmem = Memory(\"./my-agent.db\", project=\"frontend\")\n\n# CRUD\nrecord = mem.add(type=\"decision\", title=\"Use TypeScript\", content=\"...\")\nmem.get(record.id)\nmem.update(record.id, content=\"Updated reasoning.\")\nmem.delete(record.id)\nmem.list(type=\"bug\", limit=20)\n\n# Search + recall\nresults = mem.search(\"typescript migration\", type=\"decision\")\ncontext = mem.recall(\"setting up the build\", max_tokens=3000)\n\n# Governance\nmem.promote(record.id) # hypothesis -> active -> validated\nmem.deprecate(record.id, reason=\"No longer relevant\")\nreplacement = mem.add(type=\"decision\", title=\"Use v2 approach\", content=\"...\")\nmem.supersede(record.id, replacement.id) # links old to replacement\n\n# Session persistence\nmem.save_session(\"Working on auth refactor. Blocked on token refresh.\")\nmem.load_session() # picks up where last instance left off\n\n# Health\nmem.stats()\n```\n\n### CLI\n\n```bash\n# Get started in 30 seconds\nagentmem init --tool claude --project myapp\n\n# Check if everything's working\nagentmem doctor\n\n# Core\nagentmem add --type bug --title \"CSS grid issue\" \"Flexbox fallback needed\"\nagentmem search \"grid layout\"\nagentmem recall \"frontend styling\" --tokens 2000\n\n# Governance\nagentmem promote \nagentmem deprecate --reason \"Fixed in v2.3\"\nagentmem health\nagentmem conflicts\nagentmem stale --days 14\n\n# Import + sessions\nagentmem import ./errors.md --type bug\nagentmem save-session \"Finished auth module, starting tests\"\nagentmem load-session\n\n# MCP server\nagentmem serve\n```\n\n### MCP Server\n\nBuilt-in [Model Context Protocol](https://modelcontextprotocol.io/) server for Claude Code, Cursor, and any MCP client.\n\n```bash\npip install quilmem[mcp]\n```\n\n**Claude Code config** (`.claude/settings.json`):\n\n```json\n{\n \"mcpServers\": {\n \"agentmem\": {\n \"command\": \"agentmem\",\n \"args\": [\"--db\", \"./memory.db\", \"--project\", \"myproject\", \"serve\"],\n \"type\": \"stdio\"\n }\n }\n}\n```\n\n**MCP tools:** `add_memory`, `search_memory`, `recall_memory`, `update_memory`, `delete_memory`, `list_memories`, `save_session`, `load_session`, `promote_memory`, `deprecate_memory`, `supersede_memory`, `memory_health`, `memory_conflicts`\n\n**Tell your agent how to use memory:** Copy the [agent instructions](docs/agent-instructions.md) into your `CLAUDE.md`, `.cursorrules`, or `AGENTS.md`. This teaches your agent the session protocol, trust hierarchy, and when to search vs add.\n\n## Typed Memory\n\nSeven types that cover real agent workflows:\n\n| Type | What it stores | Example |\n|---|---|---|\n| `setting` | Configuration, parameters | \"Voice speed: atempo 1.08\" |\n| `bug` | Errors and their fixes | \"loudnorm lifts noise floor\" |\n| `decision` | Rules, policies, choices | \"3rd-person narration banned\" |\n| `procedure` | Workflows, pipelines | \"TTS -> speed -> 48kHz -> mix\" |\n| `context` | Background knowledge | \"Project uses FFmpeg + Python 3.11\" |\n| `feedback` | User corrections | \"Always pick, don't ask\" |\n| `session` | Current work state | \"Working on auth. Blocked on tokens.\" |\n\n## Trust-Ranked Recall\n\n`recall()` doesn't just find relevant memories. It finds the **most trustworthy** relevant memories:\n\n1. FTS5 search returns candidates\n2. Each scored: `relevance (25%) + trust status (20%) + provenance (20%) + recency (15%) + frequency (10%) + confidence (10%)`\n3. Validated canonical memories rank above unprovenanced hypothesis memories\n4. Deprecated and superseded memories are excluded entirely\n5. Packed greedily into your token budget\n\n## Project Scoping\n\n```python\nfrontend = Memory(\"./shared.db\", project=\"frontend\")\nbackend = Memory(\"./shared.db\", project=\"backend\")\n\nfrontend.search(\"bug\") # Only frontend bugs\nbackend.search(\"bug\") # Only backend bugs\n```\n\n## Battle-Tested\n\nThis isn't theoretical. agentmem was built under production pressure over 2+ months of daily use:\n- 65+ YouTube Shorts produced with zero repeated production bugs\n- 330+ memories governing voice generation, FFmpeg assembly, image prompting, upload workflows\n- Every bug caught once, fixed once, never repeated\n- Governance engine reduced conflicts from 1,848 false positives to 11 real findings\n\n## How It Works\n\n- **Storage:** SQLite with WAL mode (concurrent reads, thread-safe)\n- **Search:** FTS5 with porter stemming and unicode61 tokenizer\n- **Ranking:** Composite score: text relevance + trust status + provenance + recency + frequency + confidence\n- **Governance:** Status lifecycle, conflict detection, staleness detection, health scoring\n- **Sync:** Provenance-aware with source hashing and resurrection\n- **Zero infrastructure:** No API keys, no cloud, no vector DB. Just a `.db` file.\n\n## License\n\nMIT\n\n\n",
"bytes": 11340,
"sha": "53b375aff70877af7c4a9dc78197eafd0a93074fda151210e156cf28d837485a",
"repo_slug": "thezenmonster/agentmem",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_thezenmonster_agentmem_12fecf0f/readme"
}
![\"agentmem](\"assets/demo.svg\")
\n