Related Pages

Related topics: Correction Integrity: Revert, Route & Echo Guard, Framework Integrations, MCP Server & Deployment

mnemo Overview & Core Memory Primitives

Purpose and Scope

mnemo is a Python library positioned as the "governance / temporal pillar of verifiable memory" for AI agents and services. Source: README.md:1-40. The published 1.5.0 release centers on two intertwined capabilities: provable forget — the ability to demonstrate, with a signed artifact, that a subject's data has been removed — and bitemporal audit, the ability to inspect what was known along two independent timelines. Source: CHANGELOG.md:1-15.

The library targets builders of agent systems whose memory spans conversation histories, vector indexes, and scratchpads, and who must produce DPO-grade artifacts under GDPR Art. 17 (right to erasure) and EU AI Act record-keeping obligations. Source: README.md:15-30. Rather than treat memory as an opaque context buffer, mnemo exposes primitives that emit shareable, signed, audit-trail-friendly receipts.

Core Memory Primitives

Primitive: stored-with-temporal-metadata

The basic unit mnemo operates on is a record carrying both the stored payload and the temporal metadata required to reason about validity and lineage. Source: mnemo/mnemo.py:30-60. Higher-level stores — conversation logs, RAG indexes, scratchpads — compose over these primitives rather than managing timestamps themselves. The package re-exports its principal constructors and helpers through the public surface so callers can write import mnemo; mnemo.<symbol>. Source: mnemo/__init__.py:1-20.

`ErasureAuditor` and the `compliance_receipt` artifact

For provable forget (Pillar 2), mnemo exposes an ErasureAuditor class whose compliance_receipt method is the central artifact. Source: mnemo/mnemo.py:80-140. Its signature, as documented in the 1.5.0 release notes, is:

ErasureAuditor.compliance_receipt(
    subject, values, *, sign=None,
    pubkey=None, request_id=None, basis=None,
)

compliance_receipt walks each registered backing store, confirms the absence of each value in values for the given subject, and packages the per-store results into a signed proof-of-erasure receipt — the document a Data Protection Officer can hand a regulator under GDPR Art. 17 / EU AI Act record-keeping. Source: README.md:50-80. Source: mnemo/mnemo.py:100-160.

Parameter roles:

• subject — identifier of the data subject whose values are being verified as erased.
• values — enumeration of the specific data items that should be absent from each store.
• sign / pubkey — keypair used to sign the receipt so an external verifier can authenticate it.
• request_id — links the receipt back to the originating data-subject request (DSR).
• basis — the legal or policy basis (e.g., "GDPR Art. 17") under which erasure was claimed.

Source: mnemo/mnemo.py:120-165.

Bitemporal audit primitives

The bitemporal layer separates valid time (when the fact was true in the world) from transaction time (when mnemo recorded it). Source: README.md:40-70. Query helpers return records that carry both timestamps, which prevents retroactive tampering from going unnoticed: a later "I never knew this" claim can be cross-checked against the transaction-time axis. Source: mnemo/mnemo.py:170-220.

Architecture and Module Layout

mnemo follows a conventional single-package layout. The table below summarizes the principal source locations.

Source: pyproject.toml:1-30. Source: CHANGELOG.md:1-15.

The typical audit flow is:

1. A DSR arrives carrying a request_id and a list of subject values to erase.
2. The caller invokes ErasureAuditor.compliance_receipt(...) with the audit parameters.
3. The auditor walks each backing store, confirms absence per value, and assembles the receipt.
4. The receipt is signed (sign / pubkey), tagged with request_id and basis, and returned to the caller.

Source: mnemo/mnemo.py:120-180. Source: README.md:50-90.

When to Reach for mnemo

mnemo earns its cost in systems where memory is multi-store and subject to oversight — agent stacks, RAG pipelines, and persistence layers that must answer "did you actually forget X?" with a citable artifact. Source: README.md:20-40. For purely ephemeral context buffers where erasure needs no proof, the primitives add cost without benefit; in regulated environments that cost is justified by the signed, basised receipt the library produces.

Related Pages

Related topics: mnemo Overview & Core Memory Primitives, Provable Forget, Erasure Manifest & Compliance Audit

Correction Integrity: Revert, Route & Echo Guard

Correction Integrity is the third pillar of mnemo's governance/temporal stack. It guarantees that a memory correction — the act of replacing a stored value with a newer one — can be undone safely, routed to the right stores without leakage, and defended against echo-based replay or injection attacks that try to rewrite history through downstream consumers.

The three sub-systems covered on this page map directly to three dedicated benchmark probes:

Source: probes/INTEGRITY_BENCHMARK.md:1-40

1. Revert: Atomic, Auditable Undo

Revert is mnemo's answer to *"I corrected the wrong fact — can I roll it back?"* The benchmark in probes/integrity_bench_revert.py exercises a corrective write followed by a revert and asserts that the prior value is restored without leaving the corrected value behind in any store or audit log that future readers could mistake for canonical.

A dedicated ABA-style probe, probes/revert_aba_probe.py, targets the classic compare-and-swap trap: a value is corrected away, the system re-creates the original value through an unrelated path, and a naive revert would silently overwrite the *new* original with the *old* original. The probe forces mnemo to tag reverts with the bitemporal identity of the fact being undone, not just its byte content, so that the revert fails closed when the lineage has drifted. Source: probes/revert_aba_probe.py:1-60

The core contract is enforced in mnemo/mnemo.py, where every write produces a versioned record and revert() consults the bitemporal index to identify the exact record to invalidate rather than blindly re-writing the head. This is the same index that powers ErasureAuditor.compliance_receipt, so a revert is provably attested in the same receipt that proves a forget. Source: mnemo/mnemo.py:1-120

2. Route: Hitting the Right Stores, and Only Those

A correction that lands in one store but not another is worse than no correction — it produces *inconsistent memory*. The routing sub-system ensures that when Mnemo.correct(subject, old_value, new_value) is called, every store that previously observed old_value receives the correction, and stores that did not observe it remain untouched.

probes/integrity_bench_inject.py stress-tests this by:

1. Writing the same key to multiple stores through different code paths.
2. Issuing a correction that should only touch a subset.
3. Asserting that the un-targeted stores still resolve to the original value and that no "correction echo" leaked into their audit trails.

The implementation relies on the store registry walked in mnemo/mnemo.py during a write: each successful write registers the (store, key, version) tuple, and correct() fans out only to the stores in that registry. Stores added *after* the original write do not retroactively receive the correction, which is the intended behaviour — routing is grounded in observation, not in policy. Source: mnemo/mnemo.py:120-240

3. Echo Guard: Defending Against Replay & Re-injection

The Echo Guard closes the loop on downstream consumers (LLM context assemblers, retrieval pipelines, cache layers) that may have already cached the pre-correction value. Without protection, a downstream consumer that re-queries the store could "echo" the stale value back into the working memory on the next turn, effectively undoing the correction.

probes/integrity_bench_echo.py simulates exactly this: it caches the old value in a downstream layer, issues a correction, forces a downstream re-read, and verifies that the corrected value is what comes back. The guard works by stamping each value with a causal version token issued at write-time; consumers are required to surface that token, and correct() invalidates every cached occurrence whose token predates the correction. Source: probes/integrity_bench_echo.py:1-80

When the guard detects a stale echo, it raises a structured StaleEchoError rather than silently merging — preserving the same fail-closed posture used by the revert ABA probe. Source: probes/integrity_bench_echo.py:80-140

How the Three Sub-systems Compose

flowchart LR
    A[Write old_value] --> B[Store registry<br/>recorded]
    B --> C[correct&#40;old, new&#41;]
    C --> D{Revert possible?}
    D -- yes --> E[revert&#40;token&#41;]
    E --> F[ABA check<br/>revert_aba_probe]
    D -- no --> G[Route fan-out<br/>integrity_bench_inject]
    G --> H[Echo invalidation<br/>integrity_bench_echo]
    H --> I[compliance_receipt]

All three flows terminate in ErasureAuditor.compliance_receipt, so a regulator-facing audit trail contains, in one artifact, the correction, the routing map, the invalidation of downstream echoes, and the revert lineage. Source: mnemo/mnemo.py:240-360, probes/INTEGRITY_BENCHMARK.md:40-80

Operational Guidance

• Run all three probes together in CI. They share fixtures and exercise overlapping invariants; running them in isolation can mask cross-pillar regressions documented in probes/INTEGRITY_BENCHMARK.md.
• Treat StaleEchoError as a contract violation, not a warning. It indicates that a downstream consumer bypassed the causal token protocol described in probes/integrity_bench_echo.py:80-140.
• Never bypass revert() to "edit" a record. Direct writes skip the ABA protection in probes/revert_aba_probe.py and break the audit chain consumed by compliance_receipt.

Related Pages

Related topics: Correction Integrity: Revert, Route & Echo Guard, Framework Integrations, MCP Server & Deployment

Provable Forget, Erasure Manifest & Compliance Audit

1. Purpose and Scope

"Provable Forget" is the second governance pillar of mnemo 1.5.0, designed to turn a forget request from an internal cleanup operation into a verifiable, regulator-ready artifact. Rather than merely deleting a value, mnemo records *what* was checked, *where* it was searched, and *what* was returned as missing, then bundles that record into a signed receipt.

The module is responsible for:

• Enumerating every store that *could* contain a subject's data (vector, kv, graph, cache, etc.).
• Producing a structured deletion manifest describing the erasure attempt.
• Running the audit and packaging the outcome as a tamper-evident proof-of-erasure receipt.
• Aligning the audit with GDPR Art. 17 ("right to erasure") and EU AI Act record-keeping duties that a Data Protection Officer (DPO) must discharge.

Source: mnemo/erasure_auditor.py:1-40

2. The Deletion Manifest

The deletion manifest is the canonical, machine-readable description of "what an erasure means for this subject". It sits one layer below the auditor and is consumed both by the runtime delete path and the verification probes.

It typically captures:

• subject — the data principal identifier (user id, account, pseudonym).
• values — the canonicalized representations being erased (embeddings, raw text, graph nodes).
• basis — the legal/contractual ground (e.g. gdpr_art_17, consent_withdrawn, retention_expired).
• request_id — a unique correlation id tying the manifest to the originating request.
• stores — the explicit set of stores the erasure must traverse.

By separating *intent* (manifest) from *proof* (receipt), mnemo lets operators replay or challenge an erasure without re-running destructive code.

Source: mnemo/deletion_manifest.py:1-60

3. `ErasureAuditor.compliance_receipt()`

The headline API is ErasureAuditor.compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=). It is the single entry point a DPO uses to convert an erasure intent into a shareable artifact.

3.1 Parameters

3.2 Workflow

flowchart LR
    A[Deletion Request] --> B[Build Deletion Manifest]
    B --> C[Sweep Stores vector, kv, graph, cache]
    C --> D{Any residual hit?}
    D -- No --> E[Audit verdict: clean]
    D -- Yes --> F[Audit verdict: residual]
    E --> G[Sign receipt]
    F --> G
    G --> H[Proof-of-Erasure Receipt]

The resulting receipt contains: which stores were checked, per-store results, the verdict, the basis, the request id, and a signature over a canonical encoding of those fields. The signature makes the receipt tamper-evident and transferable to a regulator.

Source: mnemo/erasure_auditor.py:40-160

4. Runtime Integration

The auditor is not a sidecar; it is wired into the main mnemo runtime so that any write path can be asked, after the fact, "is this subject actually gone?" The top-level facade in mnemo.py exposes the audit entry point alongside the normal memory APIs, ensuring operators do not need a second client to verify compliance.

This co-location also allows the auditor to reuse mnemo's store handles directly, so the audit probes the same backend that production reads see — avoiding the common bug where a verification harness checks a different store than the one serving traffic.

Source: mnemo/mnemo.py:1-120

5. Verification Probes

Three probes ship with the release to make the audit behavior exercisable and regression-resistant:

• probes/forget_subject_tombstone_probe.py — asserts that after a forget call, the subject's tombstone is present and queryable across stores.
• probes/forget_verification_bench.py — benchmarks the auditor under varied store counts and value cardinalities, producing latency and coverage numbers for compliance reports.
• probes/temporal_gate_demo.py — demonstrates interaction between the bitemporal audit layer and the erasure layer, showing that a forget issued at time t is correctly evaluated against both valid-time and transaction-time.

Together these probes let a maintainer prove, on every CI run, that the audit still detects residuals and that the signed receipt remains verifiable after refactors.

Source: probes/forget_subject_tombstone_probe.py:1-80 Source: probes/forget_verification_bench.py:1-80 Source: probes/temporal_gate_demo.py:1-80

6. Practical Usage

A typical DPO-facing flow is:

1. Receive a deletion request and assign a request_id.
2. Call the runtime's forget path, which writes tombstones and updates stores.
3. Call ErasureAuditor.compliance_receipt(subject, values, basis="gdpr_art_17", request_id=...).
4. Persist the returned signed receipt in the audit ledger.
5. Hand the receipt (or its hash plus signature) to the regulator on demand.

Because the receipt is self-describing and signed, it can be stored, transmitted, or even published without leaking the original values — only fingerprints and verdicts travel.

Source: mnemo/erasure_auditor.py:160-240 Source: mnemo/deletion_manifest.py:60-140

Related Pages

Related topics: mnemo Overview & Core Memory Primitives, Provable Forget, Erasure Manifest & Compliance Audit

Framework Integrations, MCP Server & Deployment

Mnemo ships as a memory layer that plugs into popular agent frameworks and exposes its capabilities through a Model Context Protocol (MCP) server. This page documents the integration surface, how each framework adapter is structured, and the deployment options available in release 1.5.0.

Overview

The mnemo/integrations/ package groups thin, framework-specific adapters that adapt mnemo's core memory primitives — recall, write, forget, audit — to the conventions of each downstream system. A standalone MCP server (mnemo_mcp.py) makes the same primitives available to any MCP-capable client (e.g., Claude Desktop, MCP-aware IDEs).

The integrations are registered through mnemo/integrations/__init__.py, which re-exports the adapter classes and provides a small factory helper so that consumers can resolve an adapter by framework name without importing submodules directly. Source: mnemo/integrations/__init__.py:1-40.

flowchart LR
    App[Agent Application] --> Adapter[Framework Adapter]
    Adapter --> Core[mnemo core<br/>MnemoClient]
    Core --> Store[Memory Store]
    Core --> Audit[ErasureAuditor]
    MCP[MCP Client<br/>e.g. Claude Desktop] --> MCPSrv[mnemo_mcp.py]
    MCPSrv --> Core

Framework Adapters

Each adapter implements a narrow surface that maps framework-native concepts (checkpointer, memory module, retriever) onto mnemo operations. The adapter always returns a framework-native object so the host code does not need to know about mnemo internals.

Autogen

mnemo/integrations/autogen.py exposes a MnemoMemory class conforming to AutoGen's memory protocol. It forwards add, query, and reset calls to the mnemo client and translates framework messages into mnemo's MemoryRecord tuples. Source: mnemo/integrations/autogen.py:1-80.

LangGraph

The LangGraph adapter provides a MnemoCheckpointer usable as graph.checkpointer. State snapshots are serialized as mnemo records keyed by (thread_id, checkpoint_id) so a graph can be resumed across processes. Source: mnemo/integrations/langgraph.py:1-120.

LlamaIndex

mnemo/integrations/llamaindex.py registers mnemo as a BaseMemory implementation. It also exposes a MnemoRetriever for use with LlamaIndex query engines, returning TextNode instances reconstructed from mnemo payloads. Source: mnemo/integrations/llamaindex.py:1-100.

Google ADK

mnemo/integrations/google_adk.py adapts mnemo to the Google Agent Development Kit's session service interface, allowing ADK agents to share memory across turns and across sessions with bitemporal audit support. Source: mnemo/integrations/google_adk.py:1-90.

MCP Server

mnemo_mcp.py runs an MCP server that exposes mnemo operations as tools and resources. It is the recommended deployment for Claude Desktop and similar hosts that prefer tool-based memory access over a Python import.

Typical tools registered by the server: mnemo_write, mnemo_recall, mnemo_forget, mnemo_audit. The server is launched either as a stdio process (python -m mnemo.mnemo_mcp) or over HTTP/SSE for remote hosts. Source: mnemo/mnemo_mcp.py:1-60.

The MCP layer deliberately reuses the same MnemoClient that the framework adapters use, so audit, retention, and provable-forget semantics introduced in 1.5.0 — including ErasureAuditor.compliance_receipt() for GDPR Art. 17 / EU AI Act record-keeping — remain consistent across every integration surface. Source: mnemo/mnemo_mcp.py:60-160.

Deployment

Mnemo's deployment story is intentionally minimal:

• Library mode — import MnemoClient (or a framework adapter) directly in the host application. Suitable for single-process agents and notebooks.
• Sidecar mode — run mnemo_mcp.py as a separate process and connect any MCP-aware client. Suitable for multi-tool hosts and shared memory across agents.
• Server mode — expose the MCP server over HTTP/SSE behind your existing gateway. Authentication keys and per-tool scoping are configured through the standard mnemo environment variables consumed in mnemo_mcp.py.

Configuration (storage backend, retention windows, signing keys for compliance_receipt) is loaded once at construction time and applies uniformly to library, sidecar, and server deployments, ensuring that provable-forget guarantees made by the ErasureAuditor hold regardless of how the system is wired in. Source: mnemo/integrations/__init__.py:20-60.

Choosing an Integration

• Use the Autogen or ADK adapter when the host already constructs those agent runtimes and you want mnemo's audit trail to flow automatically.
• Use the LangGraph adapter when you need durable, resumable graph state with bitemporal history.
• Use the LlamaIndex adapter for retrieval-heavy RAG workloads where mnemo's payload storage replaces a vector store.
• Use the MCP server when the host cannot import mnemo directly or when you want a single memory instance shared across heterogeneous agents.

All paths converge on the same underlying client, so compliance features added in 1.5.0 — such as signed compliance_receipt artifacts — are available uniformly through every entry point discussed above. Source: mnemo/mnemo_mcp.py:100-200.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/DanceNitra/mnemo

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/DanceNitra/mnemo

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/DanceNitra/mnemo

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/DanceNitra/mnemo

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/DanceNitra/mnemo

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/DanceNitra/mnemo

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mnemo with real data or production workflows.

• mnemo 1.5.0 — provable forget + bitemporal audit - github / github_release
• mnemo 1.4.0 — soft-delete residual probes (+ 1.3.0 clean memory) - github / github_release
• mnemo 1.2.0 — universal-executor gate - github / github_release
• mnemo 1.1.0 — security hardening - github / github_release
• mnemo 1.0.0 — first stable release - github / github_release
• mnemo 0.7.22 - github / github_release
• mnemo 0.7.20 - github / github_release
• Capability evidence risk requires verification - GitHub / issue