agentic-memory

A memory server for coding agents (Claude Code, Claude Desktop, Cursor, Antigravity, Codex CLI, or any MCP-compliant client) that goes beyond the naive "five separate buckets" model of agent memory: non-destructive belief revision, injection-safe context synthesis, real embeddings with ANN search, multi-tenant namespace isolation, and a choice of a zero-dependency SQLite backend or a Postgres + pgvector + Row-Level-Security backend for real deployments.

🏛️ Architecture

Six memory layers behind one unified retrieval call. Diagram renders natively on GitHub (Mermaid) — open this file on github.com if you're viewing raw markdown:

flowchart TD
    ENV(["Real-Time Environment<br/>user queries / tool output"])

    subgraph L1["1 · SENSORY MEMORY"]
        L1D["Ring buffer, saliency-scored<br/>Retention: ms → minutes"]
    end

    subgraph L2["2 · WORKING MEMORY"]
        L2D["Token-budgeted session context<br/>chronological, auto-compressing<br/>Retention: minutes → hours"]
    end

    subgraph L3["3 · EPISODIC MEMORY"]
        L3D["Causal event trajectories<br/>vector similarity retrieval<br/>Retention: weeks → months"]
    end

    subgraph L4["4 · SEMANTIC MEMORY"]
        L4D["Subject-predicate-object graph<br/>non-destructive belief revision<br/>hybrid vector + text + PPR search"]
    end

    subgraph L5["5 · LONG-TERM MEMORY"]
        L5D["Ebbinghaus-decay retrievability<br/>Truth Maintenance System<br/>Retention: days → years"]
    end

    subgraph L6["6 · PROCEDURAL MEMORY"]
        L6D["Registered skills / action recipes<br/>success-rate tracked"]
    end

    UQ{{"unified_query()<br/>ranks + fuses all 6 layers by one<br/>relevance function (similarity +<br/>recency + importance + graph proximity)"}}
    OUT(["One synthesized,<br/>injection-safe context block"])

    ENV --> L1
    L1 -- "promotion on high saliency" --> L2
    L2 --> L3
    L2 --> L4
    L3 <-.-> L4
    L3 --> L5
    L4 --> L5

    L1 --> UQ
    L2 --> UQ
    L3 --> UQ
    L4 --> UQ
    L5 --> UQ
    L6 --> UQ
    UQ --> OUT

    classDef sensory fill:#d1f5d3,stroke:#2e7d32,color:#1b1b1b
    classDef working fill:#e3d9f7,stroke:#6a3fb5,color:#1b1b1b
    classDef episodic fill:#c9dcf7,stroke:#2451a8,color:#1b1b1b
    classDef semantic fill:#c3ecd9,stroke:#1b7a4d,color:#1b1b1b
    classDef longterm fill:#cfe8ff,stroke:#1565c0,color:#1b1b1b
    classDef procedural fill:#ffe6cc,stroke:#e07b00,color:#1b1b1b
    classDef fusion fill:#111111,stroke:#111111,color:#ffffff

    class L1,L1D sensory
    class L2,L2D working
    class L3,L3D episodic
    class L4,L4D semantic
    class L5,L5D longterm
    class L6,L6D procedural
    class UQ,OUT fusion

A single unified_query call ranks and fuses all six layers by one consistent relevance function (embedding similarity + recency + importance + graph proximity), then returns one synthesized, injection-safe context block — not six separate results the caller has to stitch together itself.

What makes this different from a naive per-layer memory store

• Non-destructive belief revision. Updating a fact never silently overwrites it. The old belief is marked superseded (with a timestamp and a pointer to what replaced it) rather than deleted — full audit history via get_belief_history() / get_semantic_belief_history().

• Injection-safe context synthesis. Every retrieved memory item is wrapped in <memory trust="..." source="..."> tags with an explicit preamble telling the LLM that memory content is untrusted historical data, not instructions. All angle brackets in stored content are escaped (not just the <memory> tag itself) — so a stored item can't forge any tag, including ones like <system>, to break out of its fence.

• Write-time trust isn't blind. Every stored item carries a trust level. Self-reported, unverified claims (an agent's own confidence/success/reward score) are ranking-discounted relative to system- or user-provided facts — an agent can't inflate its own memory's influence just by claiming high importance. A verify_memory() call lets a separate, more-trusted reviewer corroborate an item after the fact and restore full ranking weight; the original writer can never call it on its own write.

• Contradiction flagging, not silent overwrite. A cheap antonym-predicate heuristic flags directly conflicting facts about the same subject (e.g. "Dan LIKES pizza" vs "Dan HATES pizza") for review instead of guessing which one is right — this is not general semantic contradiction detection (an open NLP problem), just a fast, honest, zero-model check for the specific opposite-predicate case.

• Real embeddings, with a safety net. Defaults to sentence-transformers (all-MiniLM-L6-v2) when installed; falls back to a deterministic hash embedder otherwise. The vector index dimension is auto-detected from whichever embedder is actually active — mixing a database built with one embedder and a process running another raises a clear, actionable error at startup instead of silently corrupting or crashing mid-session.

• Real ANN search, with a safety net. Uses hnswlib HNSW when installed; falls back to brute-force NumPy cosine search otherwise — and near-exhaustive queries route to brute-force even when HNSW is available, since HNSW is optimized for k ≪ n and is measurably slower than a vectorized brute-force pass once k approaches the corpus size.

• Multi-tenant namespace isolation. Every memory item carries a namespace. On the Postgres backend this is enforced by Postgres Row-Level Security — not just an app-layer filter that a bug could skip. Consolidation, reflection, and graph export are all namespace-scoped too — none of them mix or leak data across tenants.

• Two backends, one API. SQLite by default (zero external dependencies, single-process). Postgres + pgvector + RLS for real multi-writer, multi-tenant deployments — same MemoryEngine API either way. Optional Qdrant and Milvus vector-store connectors are also included for teams that want a dedicated vector database instead.

Related MCP server: trw-mcp

📦 Installation

One package, every feature included by default (real sentence-transformers embeddings, hnswlib ANN search, and Postgres/pgvector support are all installed out of the box — no extras to pick). Not on PyPI yet — install straight from GitHub for now:

pip install "agentic-memory @ git+https://github.com/Verace-Pvt-Ltd/agentic-memory.git"

Or clone and install locally:

git clone https://github.com/Verace-Pvt-Ltd/agentic-memory.git
cd agentic-memory
pip install -e .

Connect it to your AI coding tool

Claude Code (recommended — plugin marketplace, gets autonomous hooks too):

/plugin marketplace add Verace-Pvt-Ltd/agentic-memory
/plugin install agentic-memory@agentic-memory

Same two steps non-interactively (CI, setup scripts) via the CLI:

claude plugin marketplace add Verace-Pvt-Ltd/agentic-memory
claude plugin install agentic-memory@agentic-memory

This registers the MCP server through Claude Code's plugin marketplace system and auto-registers 9 autonomous hooks (hooks/hooks.json) that read and write memory on every turn without the agent needing to call an MCP tool explicitly — see Autonomous operation via hooks below. Verify with claude plugin details agentic-memory@agentic-memory, which should list Status: enabled and Hooks (9). The Python package still needs to be installed separately first (see Installation above) — the plugin distributes the MCP registration, not a bundled Python runtime.

Any other tool (Cursor, Antigravity, Codex CLI, Claude Desktop, or any other MCP-capable agent): see SETUP.md — copy one prompt into your agent's chat and it detects your tool and configures itself, including autonomous hooks where that tool supports them.

Claude Code (manual, no plugin system — MCP tools only, no autonomous hooks):

claude mcp add agentic-memory -- agentic-memory --transport stdio

Any other MCP client (Claude Desktop, Cursor, Antigravity, Codex CLI — MCP tools only, no autonomous hooks unless configured per SETUP.md):

# Auto-install into Claude Desktop's config
agentic-memory --setup-claude

# Print copy-paste config snippets for Claude Desktop, Cursor, Antigravity, and Codex CLI
agentic-memory --print-config

MCP (Model Context Protocol) is a shared standard across all of these — the same server works with any of them via:

{
  "mcpServers": {
    "agentic-memory": {
      "command": "agentic-memory",
      "args": ["--transport", "stdio"]
    }
  }
}

🪝 Autonomous operation via hooks

MCP tools require the agent to decide to call them. Hooks make memory read/write happen automatically, tied to the host tool's own lifecycle events (a new session starting, a prompt being submitted, a tool call succeeding or failing, the session stopping) — no explicit tool call needed. Four tools have a real hook/lifecycle system this project integrates with, each adapter living in its own module (memory/hooks.py, memory/hooks_antigravity.py, memory/hooks_cursor.py, memory/hooks_codex.py) with a matching config template under hooks/. Confidence differs per platform — verified against real installed binaries where one was available in this environment, doc-derived only where it wasn't:

Claude Desktop and any other generic MCP client have no hook/lifecycle system to integrate with — they get the 16 MCP tools only, called explicitly by the agent.

See SETUP.md for the exact install steps per platform, including where each hooks/*.json template needs to be copied.

🐘 Optional: Postgres / Supabase backend

For a real deployment with concurrent multi-process writers and enforced multi-tenant isolation, run Agentic Memory against Postgres + pgvector instead of SQLite. Self-hosted via Docker, no cloud account required:

docker compose up -d          # starts Postgres + pgvector (bare, unconfigured)
python -m memory.backends.postgres --migrate --dsn postgresql://postgres:postgrespassword@localhost:5433/memory

The migration step auto-detects the correct vector column dimension from whichever embedder is active in your Python environment (via get_embedding_dim()) and generates a secure app-role password if you don't supply one — nothing about the schema is hand-edited or hardcoded.

from memory.backends.postgres import PostgresBackend
from memory.engine import MemoryEngine

backend = PostgresBackend(dsn="postgresql://postgres:postgrespassword@localhost:5433/memory")
engine = MemoryEngine(backend=backend)

Row-Level Security policies enforce namespace isolation at the database engine level — a query for namespace="tenant_a" genuinely cannot see tenant_b's rows, even if application code has a bug.

Known limitations of the self-hosted Docker setup: no automated backups/point-in-time recovery, no high-availability/failover (single-container Postgres), and no encryption-at-rest beyond whatever the underlying disk provides — all buildable, none included out of the box today.

🔌 MCP Tools

Resources: memory://sensory/stream, memory://working/active, memory://semantic/graph.dot, memory://longterm/user. Prompt: synthesize_context.

🐍 Python SDK Quickstart

from memory import MemoryEngine

engine = MemoryEngine(db_path="memory.db")  # SQLite by default

engine.sensory_ingest("User clicked urgent alert", source="ui_event")
engine.working_update("user", "Can you deploy the payments service to prod?")
engine.working_update("assistant", "Running the blue-green deploy pipeline now.")

engine.episodic_record(
    title="Payments deploy",
    goal="Deploy payments service to prod",
    context="prod cluster",
    steps=[{"action": "run_pipeline", "input": {}, "output": {"status": "ok"}, "success": True}],
    outcome="success",
)

engine.semantic_add("User", "PREFERS", "blue-green deploys", confidence=0.9)
engine.long_term_store(
    "user_preference", "deploy_strategy", "blue-green",
    summary="User always wants blue-green deploys for prod",
    importance=0.9, is_pinned=True,
)

result = engine.query("deploy payments service to production")
print(result.synthesized_prompt_context)   # one injection-safe, ranked context block

stats = engine.consolidate()   # promote sensory -> working -> episodic -> semantic -> long-term

Every write accepts namespace= (default "default") and trust= (default TrustLevel.USER) for multi-tenant scoping and provenance tracking.

🧪 Testing

python3 -m pytest tests/ -v

98 tests covering persistence across restart, non-destructive belief revision, prompt-injection fencing (including non-<memory> tag names), namespace isolation across every subsystem (query, consolidation, reflection, DOT export, belief history), trust-weighted ranking and the verification mechanism, contradiction flagging, ANN index correctness (with and without hnswlib installed), embedding-dimension mismatch fail-fast behavior, eviction, Postgres dialect translation logic, and the Claude Code / Antigravity / Cursor / Codex CLI hook adapters. The Postgres backend has been verified against a real running instance (writes, reads, RLS enforcement, forget, evict) — not just reviewed statically.

⚠️ Known limitations

• No published benchmark comparison (LoCoMo, LongMemEval, or similar) against Mem0, Zep/Graphiti, or MemGPT/Letta exists yet — retrieval quality claims should be treated as unvalidated against other systems until that exists. Internal, judge-free retrieval measurements against the MemFail benchmark (arXiv:2605.26667) are available in benchmarks/.

• reflect() and episodic→semantic extraction (trigger_consolidation) use real LLM synthesis when called live through an MCP client that supports MCP sampling — the server asks the connected client's own model to synthesize insights / extract triples (ctx.sample(...) in mcp_server.py), so no separate API key or subscription is needed. This only works for live tool calls, since sampling requires an active client connection: headless paths (autonomous hooks, the background consolidation loop) have no live client to sample from and fall back to HeuristicReflector/HeuristicExtractor (template sentences / regex patterns) — real coverage, but not LLM-quality synthesis. If a sampling call fails or the connected client doesn't support it, the same heuristic fallback applies automatically, so reflect()/trigger_consolidation() never produce nothing. LLMReflector/LLMExtractor/StructuredPromptExtractor (in consolidator.py and utils.py) remain available as a separate, explicitly-opt-in path for anyone who wants headless LLM-backed extraction/reflection backed by their own Callable[[str], str] (e.g. a direct API call) — not wired in by default.

• Contradiction detection only catches the specific antonym-predicate-on-same-subject case (Tier 1). It does not detect general semantic contradictions between differently-worded facts — that remains an open problem no memory system solves generically without an expensive, unreliable LLM pass at write time.

• Postgres ANN search currently loads embeddings into an in-process index rather than querying pgvector's native index directly — works well at moderate scale, doesn't yet solve the "dataset too large for one process's memory" case that's part of the reason to use Postgres at all.

• Qdrant/Milvus connectors are real (genuine client calls, no fallback stub) but have only been exercised in local/embedded mode (:memory: Qdrant, milvus-lite) — not against a remote/distributed cluster.

🤝 Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for guidelines.

📜 License

MIT License — see LICENSE. © Verace Pvt. Ltd.