Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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.0a2: interfaces can still change. Import it as persistent_memory.

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 0.4.0a2 is the only release, pip selects it 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.

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.14. 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

Metadata

Release files for persistent-memory-mcp 0.4.0a2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for persistent-memory-mcp 0.4.0a2
File Size Uploaded Provenance Actions
persistent_memory_mcp-0.4.0a2.tar.gz 5.5 MB With provenance Details for persistent_memory_mcp-0.4.0a2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for persistent-memory-mcp 0.4.0a2
File Interpreter ABI Platform Actions
persistent_memory_mcp-0.4.0a2-py3-none-any.whl Python 3 none any Details for persistent_memory_mcp-0.4.0a2-py3-none-any.whl

Total release size: 5.6 MB

Release files / persistent_memory_mcp-0.4.0a2.tar.gz

Download URL persistent_memory_mcp-0.4.0a2.tar.gz
Size 5.5 MB
Tags Source
SHA-256 checksum
How to use checksums
3c2b6306ed83fedc2965fbdcc3ba0f7200d45b2e2b577086ef92ca0dfb278ffd
BLAKE2b-256 checksum
How to use checksums
e16f509775ce1cd578adf4200070542f2e38e25a46d8a101f31ab23271dd60f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / persistent_memory_mcp-0.4.0a2-py3-none-any.whl

Download URL persistent_memory_mcp-0.4.0a2-py3-none-any.whl
Size 96.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
723dc014a49af41ff0f5140b9e224eac5c107b2773517253e188b4751239540f
BLAKE2b-256 checksum
How to use checksums
df6d42696c44a1acb9e62d0eb3dff751ea2a3ea06f2957f4438b6b0e242e7318
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for persistent-memory-mcp 0.4.0a2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for persistent_memory_mcp-0.4.0a2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page