vbcherepanov/total-agent-memory — Persistent memory for Claude Code & Codex CLI.

Description and use

**Brief Summary (2‑3 sentences)**
vbcherepanov/total-agent-memory is a Python‑based open‑source library that provides persistent, graph‑backed memory for Claude Code and Codex CLI agents. It automatically extracts a knowledge graph from interactions, stores multi‑representation embeddings, and offers a 3‑D WebGL visualizer; its LongMemEval benchmark scores R@5 = 97.45 %. The project is self‑hostable, works with Ollama, and is positioned as a turnkey way to turn ad‑hoc prompts and tool calls into repeatable, memory‑rich agent workflows.

**Value Proposition**

• **Unified Agent Memory:** Turns isolated prompt‑tool calls into a durable, queryable knowledge store, enabling agents to recall past context, decisions, and results across sessions.
• **Rich Representations:** Combines graph relationships, dense embeddings, and visual 3‑D maps, making it easy to surface relevant facts, detect patterns, and debug agent behavior.
• **High Retrieval Quality:** LongMemEval R@5 = 97.45 % demonstrates that the system can retrieve the right piece of knowledge with very high precision, a critical metric for Retrieval‑Augmented Generation (RAG) pipelines.
• **Plug‑and‑Play Integration:** Exposes a clean API/SDK and a CLI, so existing Claude Code or Codex scripts can be wrapped with minimal code changes, and it can be run on‑prem or via Ollama for flexible deployment.

**Practical Adoption Path**

| Step | Action | Reason |
|------|--------|--------|
| 1️⃣ | **Spin up a test instance** – clone the repo, install dependencies (pip install -r requirements.txt), and run the provided Docker compose or the total-agent-memory CLI. | Quick validation of environment compatibility and baseline performance. |
| 2️⃣ | **Integrate with your agent** – replace direct Claude/Codex calls with the library’s MemoryClient wrapper (or call the REST API). The wrapper automatically logs each prompt, tool invocation, and response into the persistent graph. | Gives agents immediate memory without rewriting core business logic. |
| 3️⃣ | **Define schema / topics** – optionally add domain‑specific node types or edge labels to tailor the knowledge graph to your use case (e.g., “Ticket”, “Customer”, “Resolution”). | Improves relevance of graph queries and downstream embeddings. |
| 4️⃣ | **Leverage retrieval** – use the built‑in search(query, top_k=5) function or embed‑based similarity to fetch prior context before each new prompt. | Demonstrates the RAG benefit and reduces hallucination. |
| 5️⃣ | **Monitor & visualize** – open the 3‑D WebGL dashboard (/visualizer) to see the evolving graph, spot bottlenecks, and audit agent decisions. | Provides transparency for developers and stakeholders. |
| 6️⃣ | **Scale & harden** – move the storage backend to a production database (PostgreSQL/Neo4j) and enable Ollama or a dedicated LLM inference server for higher throughput. | Prepares the system for production traffic and compliance requirements. |

**Production Readiness**

• **Activity & Community**: 34 ⭐, 9 🍴, last commit 2026‑05‑14; active issue response and recent releases indicate healthy maintenance.
• **Architecture**: Modular Python core, optional Docker deployment, and a language‑agnostic REST/CLI surface make it easy to embed in existing pipelines.
• **Performance**: Benchmark (LongMemEval R@5 = 97.45 %) shows state‑of‑the‑art retrieval accuracy; the 3‑D visualizer runs in any modern browser with minimal overhead.
• **Deployability**: Self‑hostable on‑prem or via Ollama; no vendor lock‑in, and the storage layer can be swapped (SQLite for dev, PostgreSQL/Neo4j for prod).
• **Risk Considerations**: License (MIT‑style) and security posture need a final audit, but no red flags appear in the repo; the small contributor base suggests adding a secondary maintainer for long‑term resilience.

Overall, total-agent-memory is mature enough for a pilot in a production environment, especially where reproducible, memory‑aware agent workflows and transparent debugging are required.

Problem

vbcherepanov/total-agent-memory helps turn isolated prompts and tools into repeatable agent workflows.

Outcome

High for an OSS candidate: recent activity, adoption, and ecosystem signals are strong enough for a serious pilot.

Workflow

• coordinate multi-agent workflows
• add tool-use pipelines
• standardize agent memory

Evidence

Persistent memory for Claude Code & Codex CLI. Auto-extracted knowledge graph, multi-representation embeddings, 3D WebGL visualization. LongMemEval R@5=97.45%. Self-hosted, Ollama-optional

Source