Agent Memory

Agent Memory

Persistent semantic memory for AI agents with intelligent decision-making.

🚀 Created by: TheProdSDE

---

The problem

Most AI memory systems retrieve and inject past context into every prompt. This leads to wasted tokens, inconsistent responses, and agents that blindly replay stale or wrong answers.

Agent Memory adds a decision layer:

flowchart TD

A[User Query] --> B[Resolve Memory] B --> C[Decision Engine] C -->|High confidence match| D[🔄 Replay — return stored answer] C -->|Moderate match| E[📋 Restore — inject as context] C -->|Needs validation| F[✅ Verify — validate before reuse] C -->|No match| G[❌ None — answer from scratch]

style D fill:#0d47a1,color:#fff style E fill:#e65100,color:#fff style F fill:#1b5e20,color:#fff style G fill:#b71c1c,color:#fff

Every resolve() returns an explicit action with a scored, explainable rationale — not just a retrieved chunk. Adversarial eval: 34/36 (94%) on trap queries — the 2 misses return VERIFY (cautious), never a wrong REPLAY — see benchmarks.

---

Context rot — what this solves (and what it can't)

Context rot is the measured degradation of LLM accuracy as the context window fills — long before the token limit. Stale chunks, irrelevant retrievals, and unbounded conversation history don't just waste tokens; they actively degrade answers ("lost in the middle", instruction drift, distractor sensitivity).

Context rot has two causes. Agent Memory addresses the first; nothing outside the model itself can address the second.

1. What goes into the context — controllable, and this SDK's job:

2. How the model attends over tokens already in its context — not controllable from outside. Attention degradation over long context is a property of the model. No memory layer changes that. What Agent Memory does is keep the context small and relevant enough that the model rarely enters the degraded regime in the first place.

The honest claim: Agent Memory prevents context pollution — the dominant controllable cause of context rot in agentic systems. It doesn't change model attention behavior, and it only helps if your agent routes context through resolve() / PagedMemory instead of concatenating history by hand.

---

How it compares

Today you need three tools wired together to get what resolve() does in one call: a semantic cache (GPTCache) for replay, a memory layer (Mem0 / Zep) for context, and custom staleness logic for verification. No existing tool decides — at read time — *whether and how* a memory should be used.

Cells about other projects are capability checks against their own source or docs (mem0 checked on 2026-09-27), not measured behaviour; ❔ means we have not tested it rather than that it is absent. Corrections welcome — see docs/comparison.md for sourcing and the benchmark RFC for the review process.

Because hosted or model-backed configurations can add an LLM or embedding API round-trip per memory operation, their latency includes provider, model, and network costs. Exact latency depends on each project's configuration; this repository does not publish a universal 100ms–2s floor. Agent Memory resolves in-process in SQLite-only mode; measured latency depends on corpus shape and cache state (see performance and stress-testing details).

On *retrieval*, we publish a cleaned-release retrieval-proxy measurement below. On *end-to-end accuracy* (LLM answering + judge, where Mem0 and Zep publish), we don't quote numbers we haven't measured yet — that stage is next on the roadmap. → Full feature matrix and trade-offs (including where they're better): [docs/comparison.md](docs/comparison.md)

Benchmarked on LongMemEval (ICLR 2025)

LongMemEval is a benchmark for conversational-history retrieval. These results measure Agent Memory's RESTORE/retrieval tier, not REPLAY, VERIFY, TTL, or end-to-end answer correctness. Each question runs against a separate SQLite store containing that question's haystack; aggregate ingestion totals are not the size of one queried store. All ingestion uses zero LLM calls and $0 in API charges:

• LongMemEval_S (500 independent ~48-session haystacks; 124K turn-pair entries across all runs): 98.1% session Recall@5 with local ONNX embeddings, 96.0% lexical-only, 10.04ms lexical / 19.56ms semantic p50 retrieval. The report includes p90/p95/p99 and run-resource measurements.

• LongMemEval_M (500 independent ~500-session haystacks; ~2,500 turn-pair entries per queried store): 87.0% session Recall@5 with lexical retrieval, 12.05ms p50. This uses the official cleaned re-release and turn-pair indexing; it is not directly comparable with the paper's original-release session-index baselines.

Full methodology, per-type tables, scope notes (what this benchmark does and doesn't test), and negative results are in the [benchmark report](benchmarks/longmemeval/REPORT.md). Reproduce the semantic _S result with uv run python benchmarks/longmemeval/run_retrieval.py --semantic.

Real software, not a prototype

Every claim below is reproducible from this repo:

• 34/36 (94%) on adversarial decision-quality eval, and the 2 misses fail safe (VERIFY, never wrong REPLAY) — agent-memory eval (methodology)
• LongMemEval retrieval proxy: 98.1% Recall@5 (_S, semantic) · 87.0% (_M, lexical) — 500 independent haystacks; not an end-to-end or paper-baseline head-to-head, full report
• Reproducible stress harness for synthetically seeded workloads up to 1,000,000 entries; archive the JSON output before publishing a performance claim (methodology)
• Stress-test benchmark charts: latency percentiles, seed throughput, resource use, action mix, and cache/decision rates for lexical FTS5 runs at 10K, 100K, and 1M entries, with workload and archived result JSON documented in stress-testing
• 412 collected tests across 25 test modules — decision quality, concurrency, all 4 backends, MCP server, adapters — run in CI on every push
• Published on PyPI and the official MCP Registry
• Ships with a REST API, Streamlit dashboard, CLI, LangChain/LlamaIndex adapters, and async counterparts for memory read/write and decision operations

---

When to use it — real use cases

Where Agent Memory saves real money

A GPT-4o call costs ~$0.005. A support agent handling 50,000 queries/day with 70% repeat rate:

• Without memory: 50,000 × $0.005 = $250/day
• With Agent Memory: 15,000 LLM calls + cache misses = $75/day
• Saving: ~ $175/day (~$64k/year)
• Savings depend on your repeat rate and how similar incoming queries are to previously stored ones — measure in your own pipeline.

REPLAY avoids an LLM call when policy permits it. The latency and cost difference depends on the local workload, provider, model, and network; measure both paths in your own pipeline.

Is it right for your use case?

Good fit:

• Agent answers the same or similar questions across sessions
• You have fact-sensiti