Skip to main content
Glama
persistent-memory-mcp

persistent-memory-mcp

persistent-memory

PyPI Python Tests License: MIT

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 terminal session: pip install persistent-memory-mcp, then in Python a fact is remembered, a note is derived from it, the fact is corrected and the note is no longer served, then the fact is withdrawn and search returns nothing.

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-code

The 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 once

Output, 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 derives or indexes unreadable; cites keeps a link without propagating. plan_withdrawal lists 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

persistent_memory.PersistentMemory

OPERATIONS.md

MCP over stdio

persistent-memory-mcp --store DIR, written for you by setup

MCP.md

MCP over Streamable HTTP

persistent-memory-mcp --transport http (/mcp, token file required off loopback)

MCP.md

Hermes Agent memory provider

persistent-memory setup hermes-agent, from Hermes Agent's environment

HERMES-AGENT.md

Qdrant projection

--qdrant-url, --embed-url, --embed-model, or attach_projection

QDRANT.md

Typed core, CLI and HTTP service

hermes-memory, hermes-memory-typed

API.md

Structured rendering and admission

hermes_memory.admission_demo

STRUCTURED.md, ADMISSION.md

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 setup wrote; 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 /rpc under 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 tools
memory_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 artifactA
Read-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 noticesA
Read-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 withdrawalA
Read-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 versionA
Read-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_withdrawWithdraw an artifactA
DestructiveIdempotent

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

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers