Agent Memory

io.github.theprodsde由 GitHub 帳號 theprodsde 發布v0.1.5更新於 Oct 24, 2026

Persistent agent memory with a decision layer: replay, restore, verify, or none — explainable.

發布方自己的服務:Memory.fit

已驗證STDIO僅桌面知識與記憶AI 與機器學習

概覽

AI 產生的概覽

為 AI 代理提供本機持久記憶,對每次查詢回傳明確的 replay、restore、verify 或 none 決策。

可以做什麼
以已存記憶解析查詢,回傳明確動作(replay、restore、verify 或 none)及信心分數與理由,並為 restore 決策產生格式化脈絡。儲存帶標籤、類型、作用域、信心與 TTL 的查詢/回答配對。分頁列出記憶,支援作用域與封存篩選,並依 ID 取得單筆記錄。封存記憶使其不參與檢索、永久刪除記憶,以及將近重複記憶合併為摘要項目。
適用情境
適合代理在多次工作階段中回答相同或相似問題,且需要控制已存答案是原樣重播、作為脈絡注入、先驗證還是略過。也適合可能過時的事實型答案、多個代理共用知識庫,以及需要稽核哪筆記憶作答及原因的情境。不適合對檔案語料做文件 RAG,也不應取代應用程式的權威資料庫。
執行需求
以本機 stdio 程序執行,透過 uvx 從 PyPI 套件 agent-memory-sdk 啟動,需要 Python 與 uv。預設使用本機 SQLite 儲存,目錄由 AGENT_MEMORY_DIR 指定(預設 ~/.agent_memory),集合由 AGENT_MEMORY_COLLECTION 指定。不需 API 金鑰;選用的 Redis 或 PostgreSQL 後端需要相應服務。
安裝前請注意
此伺服器會寫入本機持久儲存:remember_memory 新增項目,forget_memory 永久刪除,archive_memory 使其不參與檢索,consolidate_memories 合併近重複項目,變更應加以核對。儲存的記憶可能包含對話內容,並以檔案形式保存在設定的目錄中。重播的答案可能過時,verify 動作與 TTL 正是為此設計。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Agent Memory,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Agent Memory

[CI] [Python 3.10+] [License: Apache-2.0] [PyPI version] [MCP Registry]

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

[Agent Memory CLI demo: exact query REPLAYs, paraphrase RESTOREs as context, shared-word trap correctly returns NONE]

🚀 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:

mermaid
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:

Rot sourceMechanism in Agent Memory
Irrelevant memory injected into every promptDecision layer — NONE refuses to inject when nothing truly matches (34/36 on adversarial trap queries; the 2 misses fail safe to VERIFY)
Unbounded in-session historyPagedMemory — fixed in-context buffer; old turns page out to recall storage and return per-query (MemGPT-style tiers)
Instruction drift in long coding sessionsRESTORE re-injects the relevant convention fresh, near the end of context, exactly when a query needs it
Stale facts silently reusedVERIFY + custom verifier callbacks + TTL expiry + half-life temporal decay
Reminders that never adaptmark_correct() / mark_wrong() — confidence learning promotes memories that keep helping, demotes corrected ones
Knowledge lost when the session endsfrom_conversation() distills durable facts from conversation turns into the store

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.

CapabilityMem0Zep / GraphitiLetta (MemGPT)GPTCacheAgent Memory
Read-time decision (replay / inject / verify / skip)❌ always injects❌ always injects⚠️ LLM self-manages⚠️ replay only✅ REPLAY / RESTORE / VERIFY / NONE
Explainable per-decision scores❌❌❌❌✅ decision.explain()
Semantic answer cache (skip the LLM call)❌❌❌✅✅
Staleness protection at read time⚠️ write-side updates + expiration_date✅ temporal graph❌⚠️ eviction only✅ VERIFY + TTL + confidence decay
Adversarial trap-query eval published❔ none found❔ none found❔ none found❔ none found✅ 34/36 (94%)
LLM / API calls per memory op1+1+1+00
Local after model assets are installed/cached, zero API keys⚠️ self-hostable; needs an LLM for extraction⚠️ needs server + LLM⚠️ LLM per op✅✅ SQLite + local ONNX
Paged context tiers (MemGPT-style)❌❌✅❌✅ memory.paged()

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

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.

[LongMemEval_S retrieval by question type]

[LongMemEval_M result and published baseline context]

Full methodology, per-type tables, scope notes (what this benchmark does and doesn't test), and negative results are in the benchmark report. 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

Use caseWithout memoryWith Agent MemorySaving
Support bot handling 10k identical FAQ queries/dayEvery query costs 1 LLM callIf roughly 75% of requests match reusable memories, those matches can REPLAY without an LLM callPotentially lower LLM cost; measure your workload
Coding agent that re-derives project conventions each sessionWastes 2–5 LLM calls per session to "remember" conventionsConventions stored once are REPLAYED/RESTORED from the first query of every later sessionNo re-derivation overhead
Research agent building knowledge over multiple sessionsEach session starts cold; re-reads the same sourcesFacts and summaries are RESTORED as contextPersistent cross-session knowledge
Customer onboarding bot answering the same steps repeatedlyAlways generates a responseHigh-confidence workflows are REPLAYED verbatimConsistent identical answers
Tool-output caching for expensive API callsCalls the external API every timeResults stored with TTL; REPLAY within TTL, re-call afterReduced external API cost
Policy-compliance agent that must verify facts before replayingSilent hallucination risk on stale datarequires_verification=True routes relevant matches to VERIFY; low-scoring matches return NONEAuditability + safety

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-sensitive answers that can go stale (prices, limits, policies)
  • Multiple agents or services share a knowledge base
  • You need audit trails — knowing which memory answered and why

Not the right tool:

  • Document RAG over a corpus of files → use a vector database for that
  • Replacing your application's source-of-truth database
  • Agents that never repeat similar queries

Features at a glance

FeatureWhat it does
Decision engineEvery resolve() returns REPLAY / RESTORE / VERIFY / NONE — never silent injection
Explainabilitydecision.explain() shows per-component scores: semantic, recency, confidence, usage
Hybrid retrievalBM25 FTS5 + optional vector KNN + RRF fusion — fast and accurate
4 backendsSQLite (default, zero-setup) · ChromaDB · Redis · PostgreSQL
Framework adaptersDrop-in BaseMemory for LangChain and LlamaIndex
MCP serverWorks with Cursor, Claude Code, VS Code via Model Context Protocol
REST APIFastAPI server with 9 endpoints + Swagger UI
DashboardStreamlit UI — stats, memory browser, live resolve sandbox
Multi-agentSHARED / NAMESPACED / ISOLATED memory across multiple agents
Confidence learningEvent-driven confidence updates + half-life temporal decay
Memory graphRelationship edges, path-finding, clusters, PageRank importance
Paged contextMemGPT-style tiers: in-context buffer → recall → archival; bounded working set per query
Conversation distillationfrom_conversation() auto-extracts facts, preferences, and entities from turns
Async APIaremember, aresolve, alist, … — memory read/write and decision operations have async counterparts
TTL & statesAutomatic expiry, archiving, near-duplicate consolidation

→ Full feature reference: docs/features.md


Performance

Latency, CPU, and memory use depend on the corpus, query distribution, cache state, embedding mode, machine, and operating system. The bundled harness uses a repeatable synthetic workload; it does not establish a production SLA.

The current lexical FTS5 benchmark results and charts are archived with their source JSON in the stress-test methodology. See that document for commands, workload scope, and guidance on interpreting results.


When to use it

Use Agent Memory when:

  • You want an agent to remember past interactions without injecting all of them into every prompt
  • You need explicit control over when memory is used (replay exact answers vs inject as context vs verify first)
  • You have different memory trust levels (user preferences vs potentially-stale facts vs tool outputs)
  • Multiple processes, services, or agents share the same memory store
  • You need audit trails — every replay is traceable to a specific stored entry with a score breakdown

Don't use it for:

  • Document RAG (search over a corpus of files) — use a vector database for that; Agent Memory stores query→answer experiences
  • A replacement for your database — it stores transient agent knowledge, not your application's source-of-truth data

Quick Start

bash
pip install agent-memory-sdk
python
from agent_memory import Memory, MemoryAction
memory = Memory(persist_dir=".agent_memory")
# Store once after a good answermemory.remember(    "How do I reset my password?",    "Go to Settings → Security → Reset Password.",    type="conversation", tags=["auth"],)
# Decide before every LLM calldecision = memory.resolve("How do I reset my password?")
if decision.action == MemoryAction.REPLAY:    return decision.response          # exact match — no LLM call needed
if decision.action == MemoryAction.RESTORE:    context = memory.format_restore_context(decision)    return call_llm(query, system_extra=context)
# VERIFY or NONE — validate or answer fresh

→ Full integration pattern and API reference: docs/usage.md


Local Setup

Option 1 — SQLite (zero dependencies, recommended to start)

bash
pip install agent-memory-sdk
# Store somethingagent-memory remember "How do I reset my password?" \  "Go to Settings → Security → Reset Password." \  --type conversation --tags auth,faq
# Ask the exact question back → REPLAY (no LLM call needed)agent-memory resolve "How do I reset my password?"# ✅ REPLAY   confidence: 0.88# response: Go to Settings → Security → Reset Password.
# Ask a paraphrase → RESTORE (inject as context, don't answer verbatim)agent-memory resolve "I forgot my password"# 📋 RESTORE  confidence: 0.77# [1] score=0.77  How do I reset my password? → Go to Settings → …
# See what's storedagent-memory stats

Option 2 — Redis or Postgres backend

bash
# Spin up the servicesdocker compose -f docker-compose.dev.yml up -d
# Install the backend extrapip install "agent-memory-sdk[redis]"      # or [postgres]
# Use itagent-memory --backend redis remember "API limit" "1000 req/min" --type factagent-memory --backend redis resolve "What is the rate limit?"

Option 3 — Streamlit dashboard (visual exploration)

bash
pip install "agent-memory-sdk[dashboard]"
# Seed demo data (optional)python scripts/seed_demo.py --data-dir .agent_memory
# Open the dashboardAGENT_MEMORY_DIR=.agent_memory agent-memory-dashboard# → http://localhost:8501

Option 4 — Development / from source

bash
git clone https://github.com/TheProdSDE/agent-memory-sdk.gitcd agent-memory-sdkpython -m venv .venv && source .venv/bin/activatepip install -e ".[dev]"make test          # run all testsmake check         # lint + type check

Dashboard

An interactive Streamlit dashboard for exploring memories, testing the resolve sandbox, and monitoring stats.

[Agent Memory dashboard slideshow: stats, memory table, replay/verify/none resolve results]

bash
pip install "agent-memory-sdk[dashboard]"AGENT_MEMORY_DIR=.agent_memory agent-memory-dashboard   # → http://localhost:8501
# Seed demo data (optional — run only when you want it)python scripts/seed_demo.py --data-dir .agent_memory

MCP Server

Agent Memory is published on the MCP Registry — install it in any MCP-compatible client with zero manual setup.

Add to your MCP client

Cursor — add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json globally:

json
{  "mcpServers": {    "agent-memory": {      "command": "uvx",      "args": ["agent-memory-sdk"]    }  }}

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json
{  "mcpServers": {    "agent-memory": {      "command": "uvx",      "args": ["agent-memory-sdk"]    }  }}

Claude Code — add to .claude/settings.json in your project:

json
{  "mcpServers": {    "agent-memory": {      "command": "uvx",      "args": ["agent-memory-sdk"]    }  }}

uvx installs the package on first run — no pip install needed.

Custom storage location

json
{  "mcpServers": {    "agent-memory": {      "command": "uvx",      "args": ["agent-memory-sdk"],      "env": {        "AGENT_MEMORY_DIR": "/path/to/your/memory",        "AGENT_MEMORY_COLLECTION": "my_project"      }    }  }}
VariableDefaultDescription
AGENT_MEMORY_DIR~/.agent_memoryDirectory for the persistent SQLite store
AGENT_MEMORY_COLLECTIONagent_memoriesCollection name (one DB per collection)

Tools exposed

ToolWhat it does
resolve_memoryRetrieve memory and get an explicit decision: replay / restore / verify / none — with confidence score and reasoning
remember_memoryStore a query/response pair with optional tags, type, scope, confidence, TTL
list_memoriesPaginated list of stored memories with scope and archive filters
get_memory_by_idFetch a single memory entry by ID
forget_memoryPermanently delete a memory
archive_memoryArchive a memory (excluded from retrieval, not deleted)
consolidate_memoriesMerge near-duplicate memories into summary entries

→ Full MCP setup guide and Docker config: docs/mcp.md


Integrations

agent-memory-sdk is the core — every integration delegates to Memory.

IntegrationInstall extraExample
Core SDK (SQLite)(none)basic_usage.py
LangChain BaseMemory[langchain]langchain_integration.py
LlamaIndex BaseMemory[llamaindex]llamaindex_integration.py
Redis backend[redis]redis_backend.py
PostgreSQL backend[postgres]postgres_backend.py
Multi-agent isolation(none)multi_agent.py
FastAPI REST server[api]rest_api.py
Confidence + Graph(none)confidence_and_graph.py
Benchmark harness(none)benchmark_harness.py

→ Setup instructions and code snippets for each: examples/README.md


Tech Stack

ComponentTechnology
LanguagePython 3.10+
StorageSQLite · ChromaDB · Redis · PostgreSQL
RetrievalBM25 FTS5 + Vector KNN + RRF fusion
InterfacesMCP · FastAPI · Streamlit · CLI
AdaptersLangChain BaseMemory · LlamaIndex BaseMemory
Search DSABloom filter (NONE fast-path) · Dynamic IDF stop words · RRF fusion
Testingpytest (412 collected tests) · ruff · mypy
CI/CDGitHub Actions — test matrix 3.10–3.13 → release gate → PyPI

No API keys required — everything runs locally.


Documentation

DocContents
docs/usage.mdIntegration pattern, API reference, MemoryEntry / MemoryDecision fields
docs/features.mdDecision actions, hybrid retrieval, types, scopes, TTL, graph, multi-agent
docs/mcp.mdMCP server setup for Cursor, Claude Code, VS Code; Docker config
docs/cli.mdCLI commands, REST API server, dashboard launch, eval dataset format
docs/roadmap.mdAll shipped features, what's next, GitHub Project board
docs/release.mdCI-automated release process, versioning, rollback
docs/architecture.mdRetrieval pipeline, scoring policy, system design
docs/comparison.mdFeature matrix vs Redis, mem0, Zep, LangMem, LlamaIndex, MemGPT
docs/stress-testing.md10K / 100K / 1M latency benchmarks with methodology
docs/benchmarks.mdEval results and reproduce commands
docs/why-decision-layer.mdThe failure mode this project exists to fix
examples/README.mdIndex of all runnable examples
CONTRIBUTING.mdDev setup, test commands, PR checklist

Status & Roadmap

All planned features through v0.5.0 are shipped. Track what's next on the GitHub Project →

→ docs/roadmap.md

Release

Tag-triggered, fully CI-gated: git tag v0.x.y && git push origin v0.x.y

→ docs/release.md


Contributing

See CONTRIBUTING.md for dev setup, test commands, and the PR checklist.


Citation

If you use Agent Memory SDK or its benchmark suite in your research, articles, or projects, please cite this repository using GitHub's Cite this repository button.

For reproducible benchmark comparisons, reference the exact SDK version, benchmark dataset version, configuration, and Git commit.


License

Apache-2.0 — see LICENSE.


Support


Agent Memory helps agents decide: Replay → Restore → Verify → Ignore

Built with ❤️ by TheProdSDE

mcp-name: io.github.theprodsde/agent-memory

來源:README.md,提交 62bab6e

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.5最新Sep 23, 2026

評分

已滿足適用檢查項的 40%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。

其他 Memory 整合