Agent Knowledge

agent-knowledge

> Long-term memory for AI agents — without vector embeddings.

[](https://pypi.org/project/compiled-memory/) [](https://pepy.tech/project/compiled-memory) [](https://pypi.org/project/compiled-memory/) [](LICENSE) [](https://github.com/yucx-go/agent-knowledge/actions/workflows/ci.yml) [](docs/mcp-integration.md) [](https://github.com/yucx-go/agent-knowledge/stargazers)

English | [简体中文](README.zh-CN.md)

A persistent knowledge base and long-term memory layer for AI agents. Conversations, documents, and decisions are auto-compiled into structured knowledge with claim/evidence provenance, append-only timeline, and contradiction detection. Pure Python, local-first, MIT licensed.

Ships as an MCP server (stdio JSON-RPC 2.0) for [Claude Code](examples/mcp/claude-code.json), [Cursor](examples/mcp/cursor.json), [Codex](examples/mcp/codex.toml), and any MCP-aware client. 96.6% R@5 on LongMemEval-S with zero vector dependencies — BM25 + Knowledge Graph + RRF only.

Why

LLM memory today is either flat RAG chunks or a key-value preference cache. Neither answers "how did we get here?".

agent-knowledge adds a knowledge-compilation layer: raw material is decomposed into Claims and Evidence, claims about the same entity are merged into a Compiled Truth, and a timeline is kept append-only — rewritten holistically when new evidence arrives. Every fact is traceable to its source, timestamp, and confidence.

Features

• 🧠 Compiled long-term memory — Claim / Evidence / Compiled Truth / append-only Timeline
• 🔍 Multi-path retrieval — Exact + BM25 + Knowledge Graph + weighted RRF + TF-IDF reranker
• 🚫 Zero vector dependencies — no embeddings, no vector database, no external services required
• 🔌 MCP server — stdio JSON-RPC 2.0, 8 tools + 2 resource URIs, works with Claude Code / Cursor / Codex / any MCP client
• 🪶 Local-first storage — human-readable YAML vault + SQLite event index, sync-friendly with git
• 🪝 Auto-capture hooks — 7 built-in hooks for messages, tool calls, decisions, file changes, errors
• ⚔️ Contradiction detection — polarity-based; surfaces "we used to say X, now we say not-X"
• 💤 Dream cycle — offline memory consolidation, deduplication, supersession
• 📊 Benchmarked — 96.6% R@5 / 0.9031 MRR on LongMemEval-S (ICLR 2025)
• 🪪 MIT licensed, Python 3.10–3.13, pure standard library + PyYAML

Before / After

Scenario: over 10 weeks the team revisits its frontend stack three times — Week 1 picks Vue, Week 6 evaluates React, Week 10 switches to React. All three meeting notes are in the agent's conversation history.

A new teammate asks the agent "what frontend are we on, and why?"

Without — RAG over chat history

The team decided to use Vue as the frontend framework.

Vector search returns the highest-similarity chunk (the earliest meeting note). No temporal awareness → stale answer.

With agent-knowledge — ak_query returns the entity (real vault YAML)

name: Frontend stack
entity_type: concept
compiled_truth:
  claims:
    - text: use React for the dashboard
      status: active
      confidence: 0.85
      evidence:
        - source_id: c3a9d1f2
          weight: 1.0
    - text: use Vue for the dashboard
      status: superseded
      confidence: 0.65
      evidence:
        - source_id: a1b2c3d4
          weight: 0.7
timeline:
  - date: 2026-02-01
    title: Decided on Vue
    source_id: a1b2c3d4
  - date: 2026-03-12
    title: Evaluated React
    source_id: b5e6f7a8
  - date: 2026-04-09
    title: Switched to React; Vue ecosystem limits
    source_id: c3a9d1f2

The agent now sees the current fact, the timeline, the sources, and the superseded prior claim in one call. Its answer naturally becomes "we're on React — switched from Vue in April due to ecosystem limits," with every fact traceable to a source.

Quick Start

pip install compiled-memory   # PyPI package; the Python module is `agent_knowledge`

ak init   ~/my-knowledge
ak ingest ~/my-knowledge --file ./meeting-notes.md
ak query  ~/my-knowledge "why did we pick React?"
ak dream  ~/my-knowledge       # offline consolidation
ak lint   ~/my-knowledge       # health check

Or run it as an MCP server, plugged into any MCP-aware client:

ak mcp ~/my-knowledge

Copy-paste configs for Claude Code / Cursor / Codex live in [examples/mcp/](examples/mcp/); the full tool list is in [docs/mcp-integration.md](docs/mcp-integration.md). Agents picking up this repo should read [AGENTS.md](AGENTS.md) first.

Architecture

┌─────────────────────────────────┐
│  Adapter Layer                  │  CLI · MCP · pull adapters
├─────────────────────────────────┤
│  UMSF Boundary                  │  unified data contract
├─────────────────────────────────┤
│  Knowledge Layer (core)         │  Compiler · Compiled Truth · Hooks · Dream
├─────────────────────────────────┤
│  Storage                        │  Vault (YAML) + EventIndex (SQLite)
├─────────────────────────────────┤
│  Search Layer                   │  Exact + BM25 + Graph + RRF + Reranker
└─────────────────────────────────┘

• Knowledge Layer — pure Python over local files, no external services
• Search Layer — zero dependencies by default; optional embedding model for stronger semantic recall
• Adapter Layer — UMSF unifies the boundary; a new agent adapter is ~80 lines

See [docs/architecture.md](docs/architecture.md).

Benchmark

LongMemEval-S (ICLR 2025) — 500 questions, ~48 sessions/question, ~115K tokens/question:

| Metric | Score | |:--------|:-----:| | R@5 | 96.6% | | R@10 | 98.2% | | MRR | 0.9031 | | NDCG@10 | 0.9218 |

Zero vector dependencies — BM25 + Exact Match + RRF only. Full per-type breakdown in [BENCHMARK.md](BENCHMARK.md).

Documentation

• [AGENTS.md](AGENTS.md) — project guide for AI agents
• [docs/architecture.md](docs/architecture.md) — five-layer architecture and data flow
• [docs/adapters.md](docs/adapters.md) — writing a new adapter
• [docs/mcp-integration.md](docs/mcp-integration.md) — MCP server integration
• [BENCHMARK.md](BENCHMARK.md) — benchmark reproduction
• [examples/mcp/](examples/mcp/) — ready-to-use MCP client configs

FAQ

How is this different from a vector database / RAG?

Vector RAG retrieves text chunks by embedding similarity. It cannot tell you whether a fact is current, has been superseded, or contradicts another fact in the corpus. agent-knowledge compiles raw input into structured Claims, merges claims per entity into a Compiled Truth with explicit active / superseded / disputed status, and keeps an append-only timeline — so the agent retrieves the current answer plus its lineage in one call.

You can still bring a vector model in as an optional reranking signal; it is not required.

Do I need a vector database (Chroma, Qdrant, Pinecone, …)?

No. Default retrieval is Exact Match + BM25 + Knowledge Graph + weighted RRF + TF-IDF reranker — all pure Python, all local. agent-knowledge has only one runtime dependency (PyYAML). On LongMemEval-S the vector-free path reaches 96.6% R@5, matching strong embedding-based baselines.

How is this different from mem0 / Letta / Zep / LangChain memory?

Most memory frameworks store fragments (messages, summaries, or embeddings) and retrieve by similarity. agent-knowledge is built around knowledge compilation instead: every claim has source provenance, every entity has a Compiled Truth, and the timeline is rewritten holistically when new evidence arrives. The output is traceable structured knowledge, not a bag of remembered turns.

Different optimization target — both are valid; pick by what you need.

Can I plug it into Claude Code / Cursor / Codex?

Yes — it ships as an MCP server (stdio JSON-RPC 2.0). Copy-paste configs are in [examples/mcp/](examples/mcp/):

• Claude Code: [examples/mcp/claude-code.json](examples/mcp/claude-code.json)
• Cursor: [examples/mcp/cursor.json](examples/mcp/cursor.json)
• Codex: [examples/mcp/codex.toml](examples/mcp/codex.toml)

Start the server with compiled-memory-mcp (default vault at ~/.agent-knowledge/vault) or ak mcp /path/to/your/vault.

Where does the data live? Is anything sent to the cloud?

Nothing leaves your machine by default. The vault is a directory of human-readable YAML files plus a SQLite event index — both git-friendly. No telemetry, no calls home, no required API keys.

What is UMSF?

Universal Memory Source Format — a small JSON schema that unifies how conversations, tool traces, decisions, and file changes are submitted to the vault. Eight event types, seven source types. It is what lets adapters for different agents (Claude Code, Codex, custom hermes/openclaw slots, …) share the same ingest pipeline. See [docs/architecture.md](docs/architecture.md).

Citation

If you use agent-knowledge in research or a publication, please cite:

@software{agent_knowledge_2026,
  author  = {Yu, Chengxin},
  title   = {agent-knowledge: long-term memory and knowledge compilation for AI agents},
  year    = {2026},
  url     = {https://github.com/yucx-go/agent-knowledge},
  version = {0.3.1}
}

A [CITATION.cff](CITATION.cff) is included for GitHub's automatic citation widget.

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: yucx-go
• Source: yucx-go/agent-knowledge
• License: MIT
• Homepage: https://pypi.org/project/compiled-memory/

Install and usage instructions live in the source repository linked above.