persistent-memory-mcp
Allows CrewAI agents/graphs to use the persistent-memory MCP tools for remembering, searching, deriving, and withdrawing entries.
Configures VS Code with GitHub Copilot to use the shared persistent memory store, enabling remember/search/derive/withdraw operations and notice delivery for invalidated memories.
Allows LangChain agents to load the persistent-memory MCP tools and use remember, search, derive, withdraw, and notice operations across sessions.
Allows LangGraph agents to load the persistent-memory MCP tools and use remember, search, derive, withdraw, and notice operations across sessions.
Allows OpenAI Agents SDK applications to connect to the memory server and use persistent memory operations such as remember, search, derive, and withdraw.
Allows Pydantic AI agents to use the persistent-memory MCP tools for remembering, searching, deriving, and withdrawing entries.
persistent-memory
AI agents act on what they remember, whatever they are built with: a coding assistant, a LangGraph or CrewAI graph, an OpenAI Agents SDK app, your own loop. They remember facts, summaries, procedures and lessons from earlier tasks. When a source is corrected or withdrawn, whatever was built from it keeps being served, and nothing tells the agent. persistent-memory records the exact source versions behind every derived item, refuses to serve anything that depends on a withdrawn or replaced version, and notifies each client that was shown it.
Python standard library only (SQLite with FTS5), Python 3.11 or later, Linux, macOS and Windows. This is an alpha release, 0.4.0a3: interfaces can still change. Import it as persistent_memory.

A real session from a fresh install from PyPI; only the typing is scripted. What it shows and how it was recorded.
Français · Connect your tools · Operations · MCP server · Evidence · Packages and releases
Install and connect
python3 -m venv ~/.persistent-memory
~/.persistent-memory/bin/pip install persistent-memory-mcp
~/.persistent-memory/bin/persistent-memory setup claude-codeThe package on PyPI is named persistent-memory-mcp; the commands and the import name stay persistent-memory and persistent_memory. While only pre-releases exist, pip selects the newest one without --pre. On Windows the commands are in .persistent-memory\Scripts\.
setup accepts claude-code, claude-desktop, cursor, vscode (GitHub Copilot), windsurf, codex and hermes-agent (Nous Research's Hermes Agent). Every tool you connect opens the same store in the platform's data folder: something remembered in one is found in the others, and a withdrawal made in one is reported to every tool that was shown the entry.
setup keeps the other entries of each configuration file, saves a backup before changing it, does not replace an entry of the same name that runs another server unless given --force, leaves a file it cannot parse untouched, and changes nothing when run twice. --dry-run shows the change first; persistent-memory status lists what is configured. SETUP.md gives the file written for each tool.
Related MCP server: Talamus
Any agent framework
The memory does not depend on a framework. In Python, use the library directly. Everything else goes through the MCP server, over stdio or Streamable HTTP, from any language. On 15 November 2026 each of these frameworks loaded the ten tools through its own MCP integration and ran remember, search, withdraw and search again, with the withdrawn entry gone: LangChain / LangGraph, OpenAI Agents SDK, Pydantic AI, CrewAI, LlamaIndex, Microsoft AutoGen, smolagents and the official MCP Python SDK. No model was called in these checks.
from agents import Agent # OpenAI Agents SDK
from agents.mcp import MCPServerStdio
memory = MCPServerStdio(params={"command": "persistent-memory-mcp", "args": ["--create"]})
agent = Agent(name="assistant", instructions="...", mcp_servers=[memory])FRAMEWORKS.md gives the versions checked and a snippet for each framework.
Example
Remember a source, derive a rule from it, show both to a session, then withdraw the source:
from persistent_memory import PersistentMemory
memory = PersistentMemory("demo-store", "team-notes", create=True)
port = memory.remember("The test server listens on port 9300.", source_id="port")
rule = memory.derive("Open port 9300 on the test firewall.",
parents=[port["ref"]], artifact_id="open-port")
parent = memory.explain("open-port")["parents"][0]["ref"]
print(parent == port["ref"]) # the exact parent version is recorded
found = memory.search("firewall 9300", session="chat-1")["items"]
print([item["artifact_id"] for item in found]) # chat-1 is shown both entries
memory.withdraw("port", "the port changed") # withdraw the source only
refused = memory.read(rule["ref"])
print(refused["allowed"], refused["reason"]) # the derived rule is refused too
print(memory.search("firewall 9300")["items"]) # and no longer found
print([(n["artifact_id"], n["state"]) for n in memory.notices("chat-1")["notices"]])
print(memory.notices("chat-1")["notices"]) # each notice is delivered onceOutput, from the installed wheel on Python 3.13:
True
['open-port', 'port']
False source_revoked
[]
[('open-port', 'withdrawn'), ('port', 'withdrawn')]
[]Correcting the source instead, with memory.correct("port", new_text, expected_version=...), refuses the rule with version_not_current (state superseded) and sends the same notices. A correction made against a version that is no longer current is refused with version_conflict.
Through MCP the same operations are the tools memory_remember, memory_derive, memory_search, memory_withdraw, memory_notices and five others; a notice arrives with the next tool result.
How it works
Authority apart from content. An authority database holds versions, dependencies and withdrawals; a freshness witness is kept beside it; content lives in its own database. Every read is checked against the current authority. See OPERATIONS.md.
Exact versions. A ref is a workspace, a stable artifact identity and an immutable version. A derived item (summary, procedure, lesson, index entry) names the exact parent versions it was made from. Corrections are compare-and-swap on the expected version.
Cascade. Withdrawing or correcting a source makes everything derived from it through
derivesorindexesunreadable;citeskeeps a link without propagating.plan_withdrawallists what would be blocked. Nothing is physically erased.Lessons are derived items.
learn(trace, feedback, lesson)stores a task trace and its feedback as sources and derives the lesson from both. Only the lesson is searchable, and withdrawing the trace or the feedback blocks it.Disposable projections. The search index and the optional Qdrant projection can be deleted and rebuilt. They only propose candidates; each one is read again through the authority, so a stale vector cannot bring back a withdrawn entry. Qdrant never holds content.
Notices. A ledger records which versions each session was shown (an MCP server process, an HTTP MCP session, a Hermes Agent session). When one of them stops being valid, that session is told once.
Old backups stay withdrawn. A restored content snapshot starts in quarantine and is reconciled with the current authority; withdrawn sources and what depends on them stay unreadable. See the recovery contract, or run
hermes-memory-demo --directory NEW_DIR.
Ways in
Door | Entry point | Documentation |
Python library |
| |
MCP over stdio |
| |
MCP over Streamable HTTP |
| |
Hermes Agent memory provider |
| |
Qdrant projection |
| |
Typed core, CLI and HTTP service |
| |
Structured rendering and admission |
|
The first five go through the same PersistentMemory class, so they expose the same memory and the same refusals. The typed interfaces use the same core and authority.
Evidence
The repository publishes its studies with protocols, observations and offline recalculation. All of them use synthetic scenarios and can be reproduced; each count holds only within its study's scope.
Lifecycle comparison: on 100 fixed trajectories, this memory and an SQLite reference with retained authority both served all 751 valid reads and blocked all 389 forbidden ones; restoring old authority with old content exposed 82 withdrawn or superseded records. A tie on these guarantees, not a superiority claim.
Confirmation study: on 100 scenarios, three repetitions each, GPT-6 Luna succeeded on 298/300 answers with memory and 29/300 without. Lexical retrieval reached 294/300, so superiority over it is not established. Two AI judges, no human audit.
Learned-experience study: Luna succeeded on 22/24 new tasks with a derived lesson, 13/24 with the complete trace and 7/24 without experience; with the lesson withdrawn, 7/24.
Answer-quality pilot: across eight histories whose evidence changes between sessions, 77/96 primary successes against 29/96 for versioned lexical retrieval.
Comparison with ECC Continuous Learning: all 128 outcomes from 32 cases are published; the predefined advantage criteria were not met.
The other studies, performance measurements and test receipts are in EVIDENCE.md; test selection and how to rerun the suite from an installed wheel are in TESTING.md.
Platforms and limits
Alpha. Names, options and file formats can change before a stable release.
Platforms. CI installs the wheel and runs the tests on Linux, macOS and Windows, Python 3.11 to 3.15. On Windows, keep the store on a local disk; a network path is not supported.
Token file on Windows. Off loopback the HTTP server requires
--token-file. On Linux and macOS that file must be readable by its owner only; Windows has no such mode bits and the file's access list is not inspected, so keep it in your own profile folder.One process per store is the tested case. Several processes are serialized by SQLite but are not part of the operations surface's tests.
Search. Lexical (FTS5 plus exact aliases) by default; semantic recall needs the Qdrant projection and an embeddings endpoint. The index covers up to 5,000 current entries per workspace.
Explicit admission. Nothing is stored unless a client calls remember, derive, correct or learn; conversations are not recorded by themselves.
Withdrawal is logical. It blocks future reads through this library. It does not erase bytes or recall text already shown or copied elsewhere, and it cannot detect a coordinated rollback of content, authority and witness together.
Client coverage. Claude Code, Codex CLI and Hermes Agent read the configuration that
setupwrote; Claude Code and Hermes Agent also stored and found entries through it in model turns. The Claude Desktop, Cursor, VS Code and Windsurf files follow each tool's documentation and are checked by tests, not opened in those applications.Trust boundary. The combined typed HTTP server also exposes the privileged core
/rpcunder the same token. It is meant for a trusted application, not a multi-tenant service.
License and project
MIT license, by Gilles Musy (Musyg). PACKAGES.md gives the release history and the optional policy registry, a separate distribution. The implementation package is hermes_memory, the project's historical name; it remains importable. Contributing · Version française · Source
Available Tools
10 toolsmemory_correctCorrect an artifactA
Replace an artifact's text when the user corrects it, keeping its history. Only applies if expected_version is still its current version; otherwise it is refused with version_conflict, and you search again. Metadata you leave out is kept. Whatever was derived from the old version stops being served and its readers are notified. To remove something entirely, use memory_withdraw.
Inputs: text (required), artifact_id (required), expected_version (required), aliases, +5 more.
memory_deriveDerive from exact parentsA
Store a summary, conclusion or procedure you built from entries already in memory, linked to the exact versions it came from. Use it instead of memory_remember whenever the text depends on stored entries: if one of them is later corrected or withdrawn, this artifact stops being served and sessions that saw it are notified. Returns artifact_id and ref.
Inputs: text (required), parents (required), kind, aliases, +5 more.
memory_explainExplain an artifactARead-onlyIdempotent
Explain why an artifact is or is not served: its state, its versions, what it was derived from and what depends on it. Metadata only, never text. Use it when a search leaves out something the user expects, or before a correction. Read-only; unknown_artifact if it does not exist. Give artifact_id or ref.
Inputs: ref, artifact_id.
memory_learnLearn a lessonA
After a task, store the lesson drawn from it, with the task trace and the feedback it got kept as its provenance. Only the lesson is returned by searches; withdrawing the trace or the feedback stops serving the lesson. For a fact the user states, use memory_remember.
Inputs: trace (required), lesson (required), feedback (required), kind, +6 more.
memory_noticesCheck noticesARead-only
List the artifacts this session was shown that have since been withdrawn, invalidated or superseded, so you stop relying on them and on what you said from them. Each is reported once. Other tool results already carry new notices as memory_notices; call this when you need to check explicitly, for example before a final answer.
Inputs: no named parameters.
memory_plan_withdrawalPlan a withdrawalARead-onlyIdempotent
Preview a withdrawal: list every version that memory_withdraw would stop serving, the artifact and everything derived from it, without changing anything. Use it to show the user the consequences before withdrawing.
Inputs: artifact_id (required).
memory_readRead one versionARead-onlyIdempotent
Re-read one exact version you got from memory_search or a write, for example before relying on it again later in a conversation. Returns its text if it is still valid; otherwise allowed is false and reason and state say why (superseded, withdrawn, expired), with no text. Read-only. To look for something, use memory_search.
Inputs: ref (required).
memory_rememberRemember a sourceA
Store a new fact, decision, document or procedure the user stated or confirmed, as a source. Do not use it for your own conclusions (memory_derive), for lessons after a task (memory_learn), or to change something already stored (memory_correct). Returns artifact_id and ref. Sending the same source_id with the same text again changes nothing; with a different text it is refused with version_conflict.
Inputs: text (required), kind, aliases, source_id, +4 more.
memory_searchSearch memoryARead-onlyIdempotent
Find stored facts, decisions and procedures by keywords. Use it before answering about anything the user said or decided earlier. Returns only current, valid versions, each with its text, kind, artifact_id and exact ref; withdrawn, superseded and expired versions are left out, and an empty list means nothing valid matches. Read-only. To re-read one version you already hold, use memory_read.
Inputs: query (required), as_of, kinds, top_k, +2 more.
memory_withdrawWithdraw an artifactADestructiveIdempotent
Stop serving an artifact the user says is wrong, outdated or must be forgotten, together with everything derived from it; sessions that saw them are notified. The text is not physically erased and the history keeps the reason. Run memory_plan_withdrawal first when the user should see what it blocks. To replace a text with a better one, use memory_correct instead.
Inputs: reason (required), artifact_id (required), event_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a sharply distinct role, and the descriptions explicitly route the agent between them (remember vs derive vs learn, search vs read, correct vs withdraw vs plan_withdrawal). The overlap-prone pairs (search/read, explain/plan_withdrawal) are separated by clear read-only vs mutating and metadata vs preview boundaries. No two tools appear to do the same thing.
All names share a consistent memory_ prefix with mostly verb second elements (search, read, remember, correct, explain, derive, learn, withdraw). Minor deviations: memory_notices is a noun rather than a verb, and memory_plan_withdrawal is a verb_noun compound while others are single verbs. Still highly predictable overall.
Ten tools is well within the sweet spot and each one earns its place: three write paths, two read paths, a correction path, a withdrawal path with a safe preview, plus explain and notices for lineage/notification. Nothing feels redundant or padding.
The lifecycle is well covered: create (remember/derive/learn), read (search/read), update (correct), soft-delete (plan_withdrawal/withdraw), and introspection (explain/notices). Minor gaps: no enumeration/list tool to browse artifacts without keywords, and no restore/undo path for a withdrawal (by design, since text is retained, but there is no way to re-serve it).
Maintenance
Related MCP Connectors
Shared memory for your AI agents. Every fact shows its source, and stale facts get replaced.
Agent memory that refuses to guess: evidence-gated recall, exact-source reads, verifiable deletion.
Memory for AI agents that stays correct as facts change.
Hosted agent memory with provenance, contradiction surfacing, and snapshot rollback.
Related MCP Servers
- AlicenseAqualityAmaintenancePersistent AI memory with SQLite hybrid search (FTS5 + semantic), built-in Qwen3 embedding, and rclone sync across machines.15307 PyPI13Apache 2.0
- AlicenseNot gradedqualityCmaintenanceLocal-first, source-grounded memory for AI agents, with citations, bitemporal history, review-gated corrections, and MCP tools for search and recall.4Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides a local-first, source-cited memory layer for AI agents, with MCP tools to search, read, explain sources, and propose/apply memory updates.84 npm13Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides AI agents a shared long-term memory layer with evidence-backed, auditable claims, enabling persistent, explainable, and conflict-aware recall across sessions.8MIT