Introduction

Mnemo is an MCP-native memory database for AI agents. It provides persistent, structured memory with semantic search, access control, hash-chain verification, and multi-agent collaboration primitives.

Key Features

• 21 MCP Tools: core memory ops (remember, recall, forget, forget_subject, share, consolidate), git-like state (checkpoint, branch, merge, replay), delegation & verification (delegate, verify, trajectory_audit), attention state, agent-controlled mem_*, and plan memory — see the tools reference
• Hybrid Retrieval: Vector similarity (USearch/pgvector) + BM25 full-text (Tantivy) + recency + graph signals fused via Reciprocal Rank Fusion
• Access Control: Owner-based permissions, ACL sharing, transitive delegation with time bounds
• Integrity Verification: SHA-256 hash chains over memory records with tamper detection
• Git-like State Management: Checkpoint, branch, merge, and replay agent memory states
• Cognitive Forgetting: Ebbinghaus decay curves, consolidation, archival strategies
• Memory Poisoning Detection: Anomaly scoring with automatic quarantine
• Multiple Backends: DuckDB (embedded) or PostgreSQL (distributed)
• REST API: Full HTTP API alongside MCP stdio transport
• SDKs: Python (with LangGraph, CrewAI, OpenAI Agents integrations), TypeScript, Go

Use Cases

• Agent Memory: Give LLM agents persistent memory across conversations
• Multi-Agent Collaboration: Share memories between agents with fine-grained permissions
• Audit Trails: Immutable event logs with hash-chain integrity verification
• Knowledge Management: Store, retrieve, and organize agent-generated knowledge

Architecture

Mnemo is built in Rust for performance and safety. The workspace contains:

Quick Start

Installation

From source

cargo install --path crates/mnemo-cli

With Docker

docker pull ghcr.io/mnemo-ai/mnemo:latest
docker run -v mnemo-data:/data ghcr.io/mnemo-ai/mnemo:latest

Running

Basic (embedded DuckDB, noop embeddings)

mnemo --db-path my-agent.db

With OpenAI embeddings

export OPENAI_API_KEY=sk-...
mnemo --db-path my-agent.db

With PostgreSQL backend

mnemo --postgres-url "postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost/mnemo"

With REST API

mnemo --db-path my-agent.db --rest-port 8080

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mnemo": {
      "command": "mnemo",
      "args": ["--db-path", "/path/to/memory.db"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Python SDK

pip install mnemo-db   # `mnemo` itself is held by a 2021 notebook project

from mnemo import MnemoClient

client = MnemoClient(db_path="agent.db")
result = client.remember("The user prefers dark mode")
memories = client.recall("user preferences")

First Operations

Once running, the agent (or you via MCP client) can:

1. Store a memory: mnemo.remember with content and optional metadata
2. Retrieve memories: mnemo.recall with a natural language query
3. Share with other agents: mnemo.share to grant access
4. Verify integrity: mnemo.verify to check hash chain consistency

Architecture

System Overview

┌──────────┐  ┌───────────┐  ┌──────────┐  ┌──────────┐
│MCP Client│  │REST Client│  │  gRPC    │  │  psql    │
│ (stdio)  │  │  (HTTP)   │  │ (tonic)  │  │ (pgwire) │
└────┬─────┘  └─────┬─────┘  └────┬─────┘  └────┬─────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
┌────────────────────────────────────────────────────────┐
│                    MnemoEngine                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ Remember │ │  Recall  │ │ Forget/  │ │Checkpoint│ │
│  │ Pipeline │ │ Pipeline │ │Share/... │ │/Branch/  │ │
│  │          │ │  (RRF)   │ │          │ │Merge     │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│       └─────────────┴────────────┴────────────┘       │
│                         │                              │
│  ┌──────────────────────▼──────────────────────────┐  │
│  │          StorageBackend (trait)                   │  │
│  │   ┌──────────┐              ┌─────────────┐     │  │
│  │   │  DuckDB   │              │  PostgreSQL  │     │  │
│  │   │           │              │  + pgvector  │     │  │
│  │   └──────────┘              └─────────────┘     │  │
│  └──────────────────────────────────────────────────┘  │
│                                                         │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │VectorIndex │ │FullText  │ │Embeddings│ │Encrypt │ │
│  │USearch/PG  │ │ Tantivy  │ │OpenAI/   │ │AES-256 │ │
│  │  (HNSW)   │ │ (BM25)   │ │ONNX/Noop │ │  GCM   │ │
│  └────────────┘ └──────────┘ └──────────┘ └────────┘ │
│                                                         │
│  ┌────────────┐ ┌──────────┐ ┌──────────────────────┐ │
│  │   Cache    │ │ColdStore │ │  Poisoning Detection  │ │
│  │ (in-mem)   │ │  (S3)    │ │  + Prompt Injection   │ │
│  └────────────┘ └──────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Crate Structure

Data Model

MemoryRecord

The core data structure. Key fields:

Retrieval Pipeline

Recall uses Reciprocal Rank Fusion (RRF) to combine:

1. Vector similarity (cosine via USearch or pgvector HNSW)
2. BM25 full-text (Tantivy)
3. Recency scoring (exponential decay with configurable half-life)
4. Graph expansion (1-2 hop relation traversal)

Weights are configurable via hybrid_weights parameter. Permission-safe ANN pre-filtering ensures only authorized memories appear in results.

Access Control

Three-tier permission model:

1. Owner: Agent who created the memory has full access
2. ACL: Explicit grants via share with permission levels (Read, Write, Delete, Share, Delegate)
3. Delegation: Transitive, scoped, time-bounded permission delegation with depth limits

Hash Chain Integrity

Every memory record is linked via SHA-256 hashes:

Record₁ → content_hash = SHA256(content + agent_id + timestamp)
Record₂ → prev_hash = SHA256(content_hash₂ + content_hash₁)
Record₃ → prev_hash = SHA256(content_hash₃ + content_hash₂)

The verify tool checks the entire chain for tampering using constant-time comparisons.

Security Layers

• Encryption: AES-256-GCM at-rest content encryption (pluggable via ContentEncryption)
• Validation: agent_id charset/length validation at engine level
• Poisoning: anomaly scoring + prompt injection pattern detection → quarantine
• CORS: configurable origin allowlist, defaults to localhost
• Error sanitization: internal errors logged only, generic messages returned

MCP Tools Reference

Mnemo registers 21 MCP tools via the rmcp framework. Each is available over the STDIO transport when running the mnemo binary.

Every tool takes a single JSON object argument (the fields below) and returns a JSON-encoded text result. On failure a tool returns an isError result whose text is the error message rather than throwing. Required arguments are bold; all others are optional with sensible defaults.

Role filtering. When the server is built with MnemoServer::with_role_filter, a caller only sees the tools its role is allowed to call in tools/list, and a denied tools/call returns a structured -32601 (method-not-found) error instead of a silent empty result. Without a filter every tool below is visible and callable.

The ten core tools also have dedicated pages (linked in the tables). The remaining eleven are documented inline here.

Core memory operations

Checkpoint, branch, merge & replay (git-like state)

Delegation & verification

Attention state (arXiv:2605.18226)

Requires the server to be built with MnemoServer::with_attention_state; otherwise both tools return an error result.

Agent-controlled memory — mem_* family (AutoMEM)

A flat, agent-managed store: nothing is written unless the agent explicitly calls mem_write. Entries are tagged agent-managed and are only visible to mem_read (not the general recall pipeline).

Plan / experience memory (DocTrace)

Caches successful retrieval/reasoning plans for replay. Requires the server’s experience-memory mode to be enabled.

A note on audit-log export

mnemo.export_audit_log is referenced by the manifest schema but is not one of the 23 registered tools above. The audit-log export capability itself already exists today as a library API: mnemo_compliance::export_audit_log(events, format, signer) (with verify_ndjson_signed), which produces a signed NDJSON / EU-AI-Office CSV bundle from the hash-chained event log.

The earlier capability-lease design (per-read lease tokens gating forget_subject / audit-log export) was removed as dead code — it was never wired, and on the stdio transport a single-operator lease is ceremony rather than isolation. The design is captured in #126 for a future multi-caller (authenticated) transport where it has real value.

mnemo.remember

Store a new memory record with optional metadata, tags, and relationships.

Input Schema

Response

Example

{
  "content": "User prefers dark mode and larger fonts",
  "memory_type": "episodic",
  "importance": 0.8,
  "tags": ["preferences", "ui"]
}

mnemo.recall

Retrieve memories using semantic search, full-text search, exact filters, graph traversal, or hybrid retrieval.

Input Schema

Strategies

• vector: Cosine similarity via USearch/pgvector
• bm25: Full-text search via Tantivy
• exact: Filter-only (no embeddings needed)
• graph: Vector seeds + 2-hop graph expansion with RRF
• hybrid (default): Vector + BM25 + recency + graph fused via RRF

Response

Each memory includes: id, agent_id, content, memory_type, scope, importance, tags, score, created_at, updated_at.

Example

{
  "query": "user preferences",
  "strategy": "hybrid",
  "limit": 5,
  "min_importance": 0.3
}

mnemo.forget

Remove or decay memories using various strategies.

Input Schema

Strategies

Criteria (for bulk forget)

Response

mnemo.share

Grant another agent access to a memory.

Input Schema

Response

mnemo.checkpoint

Create a named snapshot of the current agent memory state.

Input Schema

Response

mnemo.branch

Create a named branch from a checkpoint for isolated memory experimentation.

Input Schema

Response

mnemo.merge

Merge a branch back into the main agent memory state.

Input Schema

Response

mnemo.replay

Replay events that occurred after a given checkpoint.

Input Schema

Response

mnemo.verify

Verify the SHA-256 hash chain integrity of memory records.

Input Schema

Response

mnemo.delegate

Delegate permissions to another agent with optional scoping and time bounds.

Input Schema

Scoping

If memory_ids is provided, the delegation applies only to those specific memories. If tags is provided, it applies to memories matching those tags. If neither is provided, the delegation applies to all memories.

Transitive Delegation

When max_depth > 0, the delegate can further delegate to other agents, up to the specified depth.

Response

REST API

The REST API provides HTTP access to Mnemo, enabling non-MCP clients to interact with the memory database. Enable it with --rest-port:

mnemo --db-path my.db --rest-port 8080

All endpoints are under /v1/.

Configuration

• CORS: controlled by MNEMO_CORS_ORIGINS environment variable. Defaults to localhost:3000 and localhost:8080. Set to * for permissive mode.
• Body limit: 2 MB maximum request body.

Endpoints

Health Check

GET /v1/health

Returns {"status": "ok"}.

Remember

POST /v1/memories
Content-Type: application/json

{
  "content": "User prefers dark mode",
  "importance": 0.8,
  "tags": ["preferences"]
}

Returns {"id": "...", "content_hash": "..."}.

Recall

GET /v1/memories?query=preferences&limit=5&strategy=hybrid&min_importance=0.3

Query parameters:

Get Memory by ID

GET /v1/memories/{id}

Forget

DELETE /v1/memories/{id}?strategy=soft_delete

Query parameters: strategy (soft_delete, hard_delete, decay, consolidate, archive), agent_id.

Share

POST /v1/memories/{id}/share
Content-Type: application/json

{
  "target_agent_id": "agent-2",
  "permission": "read",
  "expires_in_hours": 24
}

Checkpoint

POST /v1/checkpoints
Content-Type: application/json

{"label": "before-experiment"}

Branch

POST /v1/branches
Content-Type: application/json

{"checkpoint_id": "...", "branch_name": "experiment-1"}

Merge

POST /v1/merge
Content-Type: application/json

{"branch_name": "experiment-1"}

Replay

POST /v1/replay
Content-Type: application/json

{"checkpoint_id": "..."}

Verify

POST /v1/verify
Content-Type: application/json

{"agent_id": "my-agent"}

Delegate

POST /v1/delegate
Content-Type: application/json

{
  "agent_id": "my-agent",
  "delegate_id": "agent-2",
  "permission": "read",
  "memory_ids": ["uuid-1", "uuid-2"],
  "expires_in_hours": 48
}

The agent_id field identifies the caller. The server verifies the caller has Delegate permission on each memory in memory_ids before creating the delegation.

OTLP Ingest

POST /v1/ingest/otlp
Content-Type: application/json

{
  "resourceSpans": [...]
}

Accepts simplified OTLP JSON spans and converts them to agent events. Extracts GenAI semantic convention fields (gen_ai.request.model, gen_ai.usage.input_tokens, etc.).

Returns {"accepted": <count>}.

Error Handling

Errors return appropriate HTTP status codes with generic messages:

Error body: {"error": "description"}. Internal errors are logged server-side; the response contains only a generic message to prevent information leakage.

Python SDK

The Python SDK provides native access to Mnemo via PyO3 bindings, plus integrations for LangGraph, CrewAI, and OpenAI Agents SDK.

Installation

pip install mnemo-db

The PyPI distribution name is mnemo-db (not mnemo) because the unqualified name is held by an unrelated 2021 notebook project. The import path is unchanged — your code keeps saying from mnemo import MnemoClient.

With framework integrations:

pip install mnemo-db[langgraph]     # LangGraph checkpoint support
pip install mnemo-db[crewai]        # CrewAI memory integration
pip install mnemo-db[openai-agents] # OpenAI Agents SDK integration

Basic Usage

from mnemo import MnemoClient

client = MnemoClient(db_path="agent.db", agent_id="my-agent")

# Store a memory
result = client.remember("The user likes dark mode", importance=0.8)

# Recall memories
memories = client.recall("user preferences", limit=5)
for m in memories:
    print(f"{m['content']} (score: {m['score']:.2f})")

# Forget a memory
client.forget([result["id"]])

OpenAI Agents SDK

import asyncio
from agents import Agent, Runner
from mnemo.openai_agents import MnemoAgentMemory

async def main():
    async with MnemoAgentMemory(db_path="agent.db") as memory:
        agent = Agent(
            name="MemoryAgent",
            instructions="Use memory tools to remember and recall information.",
            mcp_servers=memory.mcp_servers,
        )
        result = await Runner.run(agent, "Remember that I prefer Python over JavaScript")
        print(result.final_output)

asyncio.run(main())

LangGraph Checkpointer

from mnemo import MnemoClient
from mnemo.checkpointer import ASMDCheckpointer

client = MnemoClient(db_path="agent.db")
checkpointer = ASMDCheckpointer(client)

# Use with LangGraph
from langgraph.graph import StateGraph
graph = StateGraph(...).compile(checkpointer=checkpointer)

CrewAI Memory

from mnemo.crewai_memory import ASMDMemory

memory = ASMDMemory(db_path="crew.db")
# Use with CrewAI agents

Claude Agent SDK (0.2.0+)

Connects Mnemo to the claude-agent-sdk Python package used by Claude Opus 4.7’s Auto Memory workflow. Exposes the MCP tool surface and optionally materializes memories into Markdown files that Auto Memory reads and edits directly; a watchdog observer persists those edits back into Mnemo.

import asyncio
from pathlib import Path
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from mnemo.claude_agent_sdk import MnemoClaudeMemory

async def main():
    async with MnemoClaudeMemory(
        db_path="agent.mnemo.db",
        agent_id="my-project",
        memory_dir=Path(".claude/memory"),
    ) as memory:
        memory.materialize(query="recent work", limit=25)
        memory.watch()
        options = ClaudeAgentOptions(
            mcp_servers={"mnemo": memory.mcp_server_config},
            allowed_tools=["mcp__mnemo__recall", "mcp__mnemo__remember"],
        )
        async with ClaudeSDKClient(options=options) as client:
            await client.query("Summarize yesterday's work.")

asyncio.run(main())

Install with pip install mnemo[claude].

OpenAI Agents SDK — Session store (0.2.0+)

Implements the SessionABC protocol introduced in the 2026-04-15 release, so conversation history is stored in Mnemo. Each turn becomes a session-tagged episodic memory, so a new process can resume the conversation by opening a store with the same session_id.

import asyncio
from agents import Agent, Runner
from mnemo.openai_sessions import MnemoSessionStore

async def main():
    session = MnemoSessionStore(
        db_path="agent.mnemo.db",
        agent_id="user-42",
        session_id="support-2026-04-20",
    )
    agent = Agent(name="Support")
    result = await Runner.run(agent, "I can't log in", session=session)
    print(result.final_output)

asyncio.run(main())

GDPR / DPDPA-safe erasure (0.2.0+)

Subject-scoped erasure through the engine, MCP, REST, or gRPC. Memories are matched by the tag convention subject:<subject_id>. The default redact strategy preserves the memory’s hash chain (so audit verification still succeeds) and replaces content with [REDACTED].

# REST — redact
curl -X POST -H 'content-type: application/json' \
  -d '{"subject_id":"user-42","strategy":"redact"}' \
  http://localhost:8080/v1/forget_subject

To hard-delete instead, use {"strategy": "hard_delete"}.

Ranking provenance (0.2.0+)

Pass explain=True to recall to receive a score_breakdown for each result showing the per-signal contributions (vector, BM25, graph, recency) and the final RRF rank.

result = client.recall("alpha", explain=True, strategy="hybrid")
for memory in result["memories"]:
    bd = memory.get("score_breakdown")
    if bd:
        print(memory["content"], bd)

TTL sweeper + point-in-time replay (0.2.0+)

The engine can run a background TTL sweeper that hard-deletes expired memories and emits MemoryExpired audit events. Enable it via --ttl-sweep-interval / MNEMO_TTL_SWEEP_INTERVAL.

replay accepts an as_of timestamp that synthesizes a virtual checkpoint of the agent state at that instant:

state = client.replay(
    thread_id="support-2026-04-20",
    as_of="2026-04-18T00:00:00Z",
)

TypeScript SDK

The TypeScript SDK communicates with Mnemo via MCP STDIO, spawning the mnemo binary as a child process.

Installation

npm install @mndfreek/mnemo-sdk

Usage

import { MnemoClient } from '@mndfreek/mnemo-sdk';

const client = new MnemoClient({
  dbPath: 'agent.db',
  agentId: 'my-agent',
});

await client.connect();

// Store a memory
const result = await client.remember({
  content: 'User prefers dark mode',
  importance: 0.8,
  tags: ['preferences'],
});

// Recall memories
const memories = await client.recall({
  query: 'user preferences',
  limit: 5,
});

// Share with another agent
await client.share({
  memory_id: result.id,
  target_agent_id: 'agent-2',
  permission: 'read',
});

// Verify integrity
const verification = await client.verify({
  agent_id: 'my-agent',
});
console.log(`Chain valid: ${verification.valid}`);

await client.close();

API Reference

Constructor Options

Methods

All methods return promises and correspond to MCP tools:

• remember(input) / recall(input) / forget(input)
• share(input) / checkpoint(input) / branch(input)
• merge(input) / replay(input) / verify(input) / delegate(input)

Go SDK

The Go SDK communicates with Mnemo via MCP STDIO, spawning the mnemo binary as a child process.

Installation

go get github.com/mnemo-ai/mnemo-go

Usage

package main

import (
    "fmt"
    "log"

    mnemo "github.com/mnemo-ai/mnemo-go"
)

func main() {
    client, err := mnemo.NewClient(mnemo.ClientOptions{
        DbPath:  "agent.db",
        AgentID: "my-agent",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Store a memory
    importance := float32(0.8)
    result, err := client.Remember(mnemo.RememberInput{
        Content:    "User prefers dark mode",
        Importance: &importance,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Stored: %s\n", result.ID)

    // Recall memories
    limit := 5
    memories, err := client.Recall(mnemo.RecallInput{
        Query: "user preferences",
        Limit: &limit,
    })
    if err != nil {
        log.Fatal(err)
    }
    for _, m := range memories.Memories {
        fmt.Printf("  %s (score: %.2f)\n", m.Content, m.Score)
    }
}

API Reference

ClientOptions

Methods

• Remember(RememberInput) / Recall(RecallInput) / Forget(ForgetInput)
• Share(ShareInput) / Checkpoint(CheckpointInput) / Branch(BranchInput)
• Merge(MergeInput) / Replay(ReplayInput) / Verify(VerifyInput) / Delegate(DelegateInput)

Memory tiers

Mnemo follows the Letta / MemGPT pattern of giving each memory record a tier — a coarse class that tells the engine how to treat it for expiry, decay, and consolidation. Four tiers are defined:

• Working — session-scoped. Auto-expires after engine.ttl_working_seconds (default 3600 s) when the caller doesn’t supply an explicit expires_at. Treat this as the “scratchpad” tier for within-conversation working memory.
• Procedural — system prompts, tool definitions, decision-logic snippets. Importance is clamped on write to engine.procedural_importance_floor (default 0.8) so these never decay below recall visibility.
• Semantic — facts, user preferences, long-lived knowledge. Current default behaviour; no special handling beyond the normal decay / consolidation pipeline.
• Episodic — interaction logs. Carries thread_id / session_id as the scoping identifier; the prime target for the reflection pass’s semantic dedup and stale archival phases.

Shape in the data model (honest note)

MemoryTier is a type alias for the existing MemoryType enum, not a separate schema field. v0.2.0’s initial Task-8 spec called for a new tier: MemoryTier field on MemoryRecord; we shipped the type-alias shape instead because MemoryType already had the same four variants — a redundant second column would have been churn with no runtime benefit. The practical effect is identical: callers can pass tier= (a MemoryTier value) to remember and the engine applies the per-tier behaviour based on memory_type.

#![allow(unused)]
fn main() {
use mnemo_core::model::memory::{MemoryTier, MemoryType};
// These are the same type; MemoryTier is literally `pub type MemoryTier = MemoryType;`
let t: MemoryType = MemoryTier::Working;
}

Any downstream code that was relying on a separate tier field for v0.1.1 forward compatibility will compile against memory_type.

Engine knobs

MnemoEngine exposes two builder methods for tuning tier behaviour:

#![allow(unused)]
fn main() {
let engine = MnemoEngine::new(...)
    .with_ttl_working_seconds(1800)           // 30-minute Working TTL
    .with_procedural_importance_floor(0.9);   // raise Procedural floor
}

The constants DEFAULT_TTL_WORKING_SECONDS and DEFAULT_PROCEDURAL_IMPORTANCE_FLOOR are exported from mnemo_core::query so callers can reference the shipping defaults.

Recall semantics

All four tiers participate in the same recall pipeline (auto/vector_only/hybrid_rrf/graph_boosted/lexical). Use tags=["tier:procedural"] or the existing memory_type filter to constrain to a specific tier; the engine does not currently apply a recall-time boost for Working or cap Procedural to read-only.

Out of scope

Letta’s moving-between-tiers heuristics (Working → Semantic after N accesses; Episodic → Semantic via reflection) are not implemented — the v0.3.1 reflection pass only touches Episodic consolidation. A tier-promotion pipeline is queued for v0.4.0.

Temporal edges (mnemo-graph)

The mnemo-graph crate (introduced in v0.4.0-rc1) adds a bitemporal graph layer over the existing storage backends. It’s loosely inspired by Graphiti (Zep) and the Graphiti paper: every relation carries two clocks instead of one, so historical queries can ask “what did we believe at time T?” without losing later corrections.

The two clocks

Every edge in the graph stores:

valid_from              valid_to (None = still true)
    ^                       ^
    |   fact validity       |
    +-----------------------+
    |
    +-- recorded_at (when we wrote the row)

• valid_from / valid_to describe fact validity — when the relation is true in the world.
• recorded_at describes system time — when we wrote the row. Useful for audit replay: “show me what the graph looked like at recorded_at = 2026-04-15.”

Without the second clock, there’s no way to distinguish “we always knew Priya works at Acme since 2025” from “we found out yesterday Priya works at Acme since 2025.” Both situations are common; both need different answers from a debugging session.

The TemporalEdge model

#![allow(unused)]
fn main() {
pub struct TemporalEdge {
    pub id: Uuid,
    pub src: Uuid,
    pub dst: Uuid,
    pub relation: String,
    pub valid_from: DateTime<Utc>,
    pub valid_to: Option<DateTime<Utc>>,   // None = still true
    pub confidence: f32,                   // [0.0, 1.0]
    pub recorded_at: DateTime<Utc>,
}
}

relation is a free-form string today ("works_at", "located_in", "reports_to"). We considered an enum but discarded it — codifying a relation set without real corpus data risks pinning the wrong vocabulary. The full LLM extractor that lands in v0.4.0 final will document the conventions it emits.

Storage

Two tables — DuckDB + Postgres equivalents:

CREATE TABLE graph_nodes (
    id VARCHAR PRIMARY KEY,
    label VARCHAR,
    metadata JSON,
    created_at VARCHAR NOT NULL
);

CREATE TABLE graph_edges (
    id VARCHAR PRIMARY KEY,
    src VARCHAR NOT NULL,
    dst VARCHAR NOT NULL,
    relation VARCHAR NOT NULL,
    valid_from VARCHAR NOT NULL,
    valid_to VARCHAR,
    confidence FLOAT NOT NULL DEFAULT 1.0,
    recorded_at VARCHAR NOT NULL
);
CREATE INDEX idx_graph_edges_src_validfrom ON graph_edges(src, valid_from);
CREATE INDEX idx_graph_edges_dst ON graph_edges(dst);

graph_expand — the bitemporal walk

#![allow(unused)]
fn main() {
use chrono::{TimeZone, Utc};
use mnemo_graph::{DuckGraphStore, GraphStore, TemporalEdge, graph_expand};

let store = DuckGraphStore::open_in_memory()?;

// Priya works at Acme starting 2026-01-01.
let priya = Uuid::now_v7();
let acme = Uuid::now_v7();
let acme_edge = TemporalEdge::new(
    priya, acme, "works_at",
    Utc.with_ymd_and_hms(2026, 1, 1, 0, 0, 0).unwrap(),
    None, 0.9,
);
store.insert_edge(&acme_edge).await?;

// Priya leaves Acme on 2026-04-01 and joins Globex.
let globex = Uuid::now_v7();
store.close_edge(acme_edge.id, Utc.with_ymd_and_hms(2026, 4, 1, 0, 0, 0).unwrap()).await?;
store.insert_edge(&TemporalEdge::new(
    priya, globex, "works_at",
    Utc.with_ymd_and_hms(2026, 4, 1, 0, 0, 0).unwrap(),
    None, 0.95,
)).await?;

// Walk the graph at two different points in time.
let in_feb = Utc.with_ymd_and_hms(2026, 2, 15, 0, 0, 0).unwrap();
let in_june = Utc.with_ymd_and_hms(2026, 6, 1, 0, 0, 0).unwrap();

let reachable_feb = graph_expand(&store, priya, 2, in_feb).await?;
//     ^^^ contains acme, NOT globex (relation hadn't started yet)

let reachable_june = graph_expand(&store, priya, 2, in_june).await?;
//     ^^^ contains globex, NOT acme (relation closed at 2026-04-01)
}

This is the supersession property — without it, the graph layer would be redundant with a regular non-temporal graph.

Conflict resolution

When the LLM extractor (v0.4.0 final) emits a contradicting fact with higher confidence than an existing edge, the convention is:

1. The new edge inserts with its own valid_from and recorded_at.
2. The pre-existing edge with the lower confidence has its valid_to set to the new edge’s valid_from — capping its validity window.

The result: a sceptical operator can reconstruct the historical view that contained the old answer (via recorded_at) AND the corrected view (via valid_from).

What ships in v0.4.0-rc1

There is no LLM extractor, and there is no longer a stub pretending to be one. mnemo-graph is a bitemporal storage + query layer: callers construct TemporalEdges, and this crate stores, closes and walks them.

A TemporalEdge::extract stub lived here until 2026-08-15, always returning Vec::new(). It was removed rather than left in place, because a function that always returns empty is worse than an absent one: a caller cannot tell “found no relations” from “not implemented”, so wiring it in produces silent no-ops indefinitely. It also outlived its own promise by five releases — the docstring said “lands in v0.4.0 final” while the workspace reached 0.5.23 — and its graph-extract feature flag gated nothing, since the module was compiled unconditionally. See #156.

If LLM-driven extraction is wanted later it should arrive as a designed feature with its own issue, not as a placeholder.

Sources

• Graphiti repo (Zep)
• Graphiti paper (arXiv:2501.13956)
• mnemo-graph source
• Bitemporal walk integration tests

Claude Agent SDK integration

Mnemo integrates with Anthropic’s claude-agent-sdk two ways at once:

1. MCP tool surface — every Mnemo MCP tool (remember / recall / forget / share / checkpoint / branch / merge / replay / delegate / verify / forget_subject / reflect) is exposed to the agent through the standard ClaudeAgentOptions.mcp_servers parameter.

2. Memory-file bridge — recalled memories are materialised as Markdown files on disk with YAML frontmatter. Claude Opus 4.7’s Auto Memory reads and edits those files directly; a watchdog observer picks up the edits and persists them back into Mnemo so the two views stay in sync.

Install with pip install mnemo[claude].

Minimal example

import asyncio
from pathlib import Path
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from mnemo.claude_agent_sdk import MnemoClaudeMemory

async def main():
    async with MnemoClaudeMemory(
        db_path="agent.mnemo.db",
        agent_id="my-project",
        memory_dir=Path(".claude/memory"),
    ) as memory:
        # Seed the memory directory from Mnemo so Auto Memory has context.
        memory.materialize(query="recent work", limit=25)
        # Start watching for Auto Dream / Auto Memory edits.
        memory.watch()

        options = ClaudeAgentOptions(
            mcp_servers={"mnemo": memory.mcp_server_config},
            allowed_tools=[
                "mcp__mnemo__recall",
                "mcp__mnemo__remember",
            ],
        )
        async with ClaudeSDKClient(options=options) as client:
            await client.query("Summarize what I worked on yesterday.")

asyncio.run(main())

What the bridge does to each file

• Write from Mnemo — materialize(...) writes {memory_dir}/{uuid}.md with frontmatter

  ---
  id: 0195a7e8-...
  importance: 0.7
  tags: ["decision", "roadmap"]
  expires_at: 2026-05-20T00:00:00Z
  ---
  The team agreed to ship v0.3.1 on 2026-04-22.
  

• Edit by Opus 4.7 Auto Memory / Auto Dream — the watchdog observer detects an edit, parses the (possibly rewritten) frontmatter, calls engine.remember(...) with the new content and importance, and the reflection pass (mnemo.reflect) then picks up metadata.dreamed_at markers so they don’t get double-consolidated.

Auto Dream coordination

v0.3.1 adds ReflectionMode::Coordinated which honours the same cadence Auto Dream does: skip when fewer than 5 new records have accumulated or fewer than 24 h have elapsed since the last successful pass. Run via:

# The engine is exposed indirectly through the MCP tool surface; the
# Python bridge also owns a MnemoClient instance you can drive directly:
client = memory._ensure_client()
# Coordinated is the default; pass force=True to override.
client.reflect(mode="coordinated")

Parse the Auto Dream “organization report” trailer (the markdown block with Consolidated: N / Removed: M / Reindexed: K) automatically — mnemo.reflect emits a dream_report_ingested audit event per memory containing one and marks the record so subsequent passes are no-ops.

Caveats (v0.3.1)

• Python MnemoClient currently does not attach a full-text index, so lexical and hybrid_rrf recall strategies return no results when driven from Python. Tracked; see docs/benchmarks/2026-04-21-mnemo-v0.3.0.md.
• If OPENAI_API_KEY is unset, MnemoClient falls back to NoopEmbedding. Semantic recall is then random. Set the key, or wait for the v0.3.x ONNX-embedding repair.

Anthropic memory-tool (memory_20250818)

Mnemo ships a client-side handler that satisfies Anthropic’s memory-tool spec for the memory_20250818 surface. It maps the six tool commands (view, create, str_replace, insert, delete, rename) onto Mnemo’s storage so the model gets a persistent “memory directory” that’s audited, hash-chained, and ACL-aware by default.

Install

pip install 'mnemo-db[anthropic-memory-tool]'

The extra pulls anthropic>=0.40 for SDK-driven integration. The server itself does not import Anthropic at runtime, so handlers can also be wired directly into raw API requests.

Quick start

from anthropic import Anthropic
from mnemo import MnemoClient, MnemoMemoryToolServer

# 1. Wire a Mnemo backend.
client = MnemoClient(db_path="memory.mnemo.db", agent_id="agent-1")

# 2. Construct the handler.
server = MnemoMemoryToolServer(client=client)

# 3. Register the tool with Anthropic.
anthropic = Anthropic()
extra_headers = {}
if server.beta_header():
    extra_headers["anthropic-beta"] = server.beta_header()

response = anthropic.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    tools=[server.tool_schema()],
    messages=[{"role": "user", "content": "Help me with my project."}],
    extra_headers=extra_headers or None,
)

# 4. When the model emits a `tool_use`, dispatch through the server.
for block in response.content:
    if block.type == "tool_use" and block.name == "memory":
        result = server.handle({
            "type": "tool_use",
            "id": block.id,
            "name": block.name,
            "input": block.input,
        })
        # Feed `result` back into the next `messages.create` call as a
        # `{"role": "user", "content": [{... tool_result ...}]}` block.

Storage shape

Every “file” is one Mnemo MemoryRecord with two tags:

• memorytool — flags it as belonging to this surface.
• path:/memories/... — the canonical absolute path.

Directories are implicit. They exist when at least one file lives under that prefix. view of a directory enumerates first-level children; delete of a directory recursively forgets every record under that prefix; rename re-writes every descendant under the new prefix.

This means:

• Every file write lands in Mnemo’s hash chain.
• forget propagates correctly — there is no separate file system to keep in sync.
• ACL enforcement is whatever the underlying MnemoClient is configured for. The handler doesn’t bypass scope checks.

Beta header

The basic surface needs no anthropic-beta header. When using the Managed Agents container, construct with managed_agents_beta=True:

server = MnemoMemoryToolServer(client=client, managed_agents_beta=True)
extra_headers = {"anthropic-beta": server.beta_header()}
# server.beta_header() == "managed-agents-2026-04-01"

Path-traversal safeguards

The spec calls path validation “the most important security control” for client-side handlers. MnemoMemoryToolServer enforces:

• Every path (and old_path / new_path) must start with the configured root (default /memories).
• Paths are normalised with os.path.normpath; the result must still be under the root.
• Inputs containing .. segments or URL-encoded %2e%2e / %2f sequences are rejected before normalisation.

Override the root with MnemoMemoryToolServer(client=..., root="/other") if you need a different namespace.

Return-string contract

All return values are spec-pinned. Tests in python/tests/test_anthropic_memory_tool.py assert the exact strings listed in the memory-tool spec:

• view of a directory: Here're the files and directories up to 2 levels deep in {path} ...
• view of a file: Here's the content of {path} with line numbers:\n{6-char-right-padded line no}\\t{content}
• create success: File created successfully at: {path}
• create duplicate: Error: File {path} already exists
• str_replace success: The memory file has been edited.\n{snippet with line numbers}
• str_replace no match: No replacement was performed, old_str `{old}` did not appear verbatim in {path}.
• str_replace multi: No replacement was performed. Multiple occurrences of old_str `{old}` in lines: {a, b, ...}. Please ensure it is unique
• insert success: The file {path} has been edited.
• delete success: Successfully deleted {path}
• rename success: Successfully renamed {old} to {new}

Errors are returned with is_error: true on the tool_result block so the model can react.

Sources

• Anthropic — Memory tool docs
• Anthropic — Claude Opus 4.7 release post
• Anthropic — Effective context engineering for AI agents

OpenAI Agents SDK — GA resume contract

The 2026-04-16 GA release of openai-agents generalised the preview Session protocol into three cooperating interfaces:

• SessionStore — per-turn conversation items.
• SnapshotStore — durable RunState + SandboxSessionState blobs.
• ResumeProvider — locator layer for picking a SnapshotRef to resume from.

Mnemo ships adapters for both halves.

MnemoSessionStore (chat history)

python/mnemo/openai_sessions.py. Stores each conversation turn as a session-tagged episodic memory; survives process restarts.

from mnemo.openai_sessions import MnemoSessionStore

session = MnemoSessionStore(
    db_path="agent.mnemo.db",
    agent_id="user-42",
    session_id="support-2026-04-20",
)
# Pass `session=session` to the Agents SDK `Runner`.

MnemoSnapshotStore (run state)

python/mnemo/openai_sessions_ga.py. Persists RunState + SandboxSessionState and lets the GA SDK resume crashed runs.

from mnemo.openai_sessions_ga import MnemoSnapshotStore

store = MnemoSnapshotStore(
    session_id="support-2026-04-20",
    db_path="agent.mnemo.db",
    agent_id="user-42",
    workspace_backend="local",
    workspace_root="/var/mnemo/snapshots",
)

ref = await store.save_snapshot(run_state, sandbox_state)
# ... process crashes ...
ref, run, sandbox = await store.resume(from_ref="latest")

SnapshotRef.as_uri() returns a stable snapshot://<session>/<ts> URI suitable for the forthcoming MCP resource exposure layer.

Payload storage policy

• Inline — payloads at or below inline_threshold_bytes (default 64 KiB) live in the Mnemo memory body as base64, with a SHA-256 digest.
• Offload — larger payloads go to a pluggable WorkspaceStorage. Mnemo only keeps the locator + SHA-256; the load_snapshot path verifies the digest on every read.

Workspace backends

• local — shipped. Writes under workspace_root.
• s3 / r2 / gcs / azure — stubs in v0.3.1. The WorkspaceStorage class raises NotImplementedError with a NotImplementedError("…install mnemo[openai-sandbox-<backend>] …") message. The v0.3.1 roadmap ships a real aioboto3-backed S3 backend; R2/GCS/Azure follow once the SnapshotSpec shape stabilises in the GA SDK.

Install with pip install mnemo[openai-agents].

Example (crash / resume)

See python/examples/openai_agents_snapshot_example.py for a 3-step agent that writes two snapshots, crashes before the final reply, and resumes from the latest snapshot on the second process start. The equivalent openai_agents_resume_s3_example.py ships with the v0.3.1 S3 backend.

Workspace backends (parity matrix)

The OpenAI Agents SDK GA snapshot store persists an agent’s workspace tree to object storage. Mnemo ships four backends. All four write the identical object layout and share the identical signing contract, so a snapshot is portable between providers by copying objects — nothing in the manifest is provider-specific.

<bucket-or-container>/<key_prefix>/manifest.json
<bucket-or-container>/<key_prefix>/manifest.sig
<bucket-or-container>/<key_prefix>/files/<rel_path>

The four backends

Why R2 subclasses and the other two do not

R2 speaks the S3 wire protocol, so it inherits the entire storage contract and encodes only an endpoint and a region. That makes it a one-paragraph maintenance burden.

GCS and Azure Blob are not S3-wire-compatible:

• GCS exposes an interoperability XML API that is a partial S3 emulation. It does not cover the paginated list_objects_v2 or batch delete_objects calls S3Workspace relies on, so subclassing would inherit methods that fail at runtime against a real bucket.
• Azure Blob shares no wire surface at all — different auth (shared key / SAS / Entra ID), different REST API, different pagination.

Both therefore use their provider’s native client, as a single standalone class each. There is deliberately no abstract base layer: the genuinely shared logic (manifest construction, Ed25519 signing, per-blob digest verification) already lives in mnemo.openai_sandbox.manifest, and what remains per backend is a ~5-method object-store adapter. An ABC over five methods would add a layer without removing duplication.

One spec shape, four backends

RemoteSnapshotSpec has a single bucket field. Azure calls its top-level namespace a container; that name goes in bucket anyway.

RemoteSnapshotSpec(backend="azure", bucket="<container-name>", ...)

This is intentional. A provider-specific field would push a conditional into every consumer of a spec; one field keeps MnemoSnapshotStore’s dispatch to a single spec.backend lookup.

Construction

# AWS S3 — standard credential chain
from mnemo.openai_sandbox import S3Workspace
ws = S3Workspace(bucket="agent-snapshots")

# Cloudflare R2 — account ID + access keys
from mnemo.openai_sandbox import CloudflareR2Workspace
ws = CloudflareR2Workspace(
    bucket="agent-snapshots", account_id="abc123",
    access_key_id="...", secret_access_key="...",
)

# GCS — Application Default Credentials
from mnemo.openai_sandbox import GCSWorkspace
ws = GCSWorkspace(bucket="agent-snapshots")

# Azure Blob — connection string (also works against Azurite)
from mnemo.openai_sandbox import AzureBlobWorkspace
ws = AzureBlobWorkspace.from_connection_string(
    "DefaultEndpointsProtocol=...", container="agent-snapshots",
)

Every backend then exposes the same three methods: save_workspace, load_workspace, delete_workspace.

Provider behaviour worth knowing

The Azure row is the one that bites. upload_blob defaults to raising ResourceExistsError on an existing name, so AzureBlobWorkspace passes overwrite=True — without it, re-saving a workspace to the same key_prefix would fail on the second attempt, making save_workspace non-idempotent across retries. A regression test pins this.

Integrity model (identical across backends)

1. save_workspace walks the tree, records a SHA-256 per file, builds manifest.json, and signs it with Ed25519.
2. The returned spec carries manifest_sha256.
3. load_workspace re-checks that digest against what the provider served before verifying the signature, then verifies every per-file digest while materialising the tree.

Step 2/3 is what catches tampering in the bucket even if an attacker also re-signs the manifest with a rotated key. A tampered manifest fails closed, and each backend has a test that mutates the stored manifest and asserts the load raises.

Testing

GCS has no moto equivalent and its official emulator (fake-gcs-server) is a Docker image; Azurite likewise needs Docker or npm. So those two use small in-process fakes that implement only the handful of client methods the backend actually calls — a new call reaching for an unfaked method fails loudly rather than passing against a permissive mock. The live gates are skipped by default and never run in CI.

The Azure live test works unmodified against Azurite, whose connection string is well-known — the cheapest way to exercise the real SDK path locally.

Cloudflare R2 workspace backend

Mnemo’s MnemoSnapshotStore — the OpenAI Agents SDK GA snapshot store — supports persisting workspace trees to any S3-compatible object store. v0.3.4 ships CloudflareR2Workspace as a thin subclass of S3Workspace so R2-backed snapshots inherit every feature of the AWS path unchanged: signed manifests, Ed25519 verification, per-blob digest checks, batched delete.

Install

pip install 'mnemo-db[openai-sandbox-r2]'

The extra pulls boto3>=1.34 and cryptography>=42. R2’s S3 API is wire-compatible with AWS SDK v4 signing, so no R2-specific client library is needed.

Quick start

from mnemo.openai_sandbox.r2_workspace import CloudflareR2Workspace
from mnemo.openai_sandbox.manifest import WorkspaceSigner

signer = WorkspaceSigner.generate_ephemeral()  # or load yours from KMS

ws = CloudflareR2Workspace(
    bucket="agent-snapshots",
    account_id="abc123def456",   # R2 account ID
    access_key_id="...",         # R2 access key
    secret_access_key="...",     # R2 secret access key
)

spec = ws.save_workspace(
    workspace_root="/tmp/agent-state",
    signer=signer,
    workspace_id="run-2026-04-25-1",
    created_at="2026-04-25T00:00:00Z",
    key_prefix="agents/agent-1",
)

# `spec` carries backend="r2" — MnemoSnapshotStore dispatches via
# this field to keep the load path symmetric with save.
print(spec)
# RemoteSnapshotSpec(backend='r2', bucket='agent-snapshots',
#                    key_prefix='agents/agent-1', manifest_sha256='...')

Differences from S3 in one line

CloudflareR2Workspace sets every R2-specific knob in its constructor; nothing else in the snapshot path needs to know it’s R2.

Storage layout

Same as S3Workspace. One R2 object per file in the workspace plus two top-level objects per snapshot:

<bucket>/<key_prefix>/manifest.json     # signed JSON manifest
<bucket>/<key_prefix>/manifest.sig      # detached Ed25519 signature
<bucket>/<key_prefix>/files/<rel_path>  # one per source file

Symlinks are recorded in the manifest (not as separate objects) so the load path can recreate them after every regular file is fetched

• verified. See the OpenAI Agents GA integration page for the manifest schema.

Live-credential test

The Mnemo test suite runs a moto-S3 round-trip against CloudflareR2Workspace on every CI build. To run a real R2 round-trip locally, export:

export R2_ACCOUNT_ID=<account>
export R2_ACCESS_KEY_ID=<key>
export R2_SECRET_ACCESS_KEY=<secret>
export R2_BUCKET=<bucket>

pytest python/tests/test_r2_workspace.py::test_live_r2_round_trip -v

The test creates a small workspace tree, dumps it to R2 under the mnemo-tests/live-r2/ prefix, fetches it back, asserts file contents match, and cleans up. Skipped silently when any of the four env vars are unset.

Cost note

R2’s free tier is 10 GB storage + 1M Class-A operations / month + 10M Class-B operations / month. A typical mnemo workspace snapshot is ~10 files at ~1 MB each, so a few thousand snapshots fit inside the free tier — see Cloudflare R2 pricing.

R2 also has zero egress fees, which makes it a good fit for snapshot restore traffic patterns (lots of reads on a bad day, very few on a good one).

Sources

• Cloudflare R2 — pricing & API
• OpenAI — next evolution of the Agents SDK
• r2_workspace.py source

Letta Conversations-style shared memory

Letta’s Letta-Code release (2026-04-06) introduced a Conversations API where multiple agents share a single memory stream rather than each maintaining its own.

Mnemo v0.4.0-rc1 ships MnemoLettaShared — the same shape (attach / detach / read / write / list_participants) backed by Mnemo memories rather than a remote Letta service. That keeps shared state on Mnemo’s audit log + hash chain + ACL surface even when the agents are running through Letta’s orchestration.

Install

MnemoLettaShared lives in the core mnemo package — no extra needed:

pip install mnemo-db

Quick start

from mnemo import MnemoClient
from mnemo.letta_adapter import MnemoLettaShared

client = MnemoClient(db_path="conversation.mnemo.db", agent_id="orchestrator")
shared = MnemoLettaShared(
    client=client,
    conversation_id="design-review-2026-04-25",
)

shared.attach("agent-architect")
shared.attach("agent-reviewer")

shared.write(
    "Initial proposal: split the API into v1 / v2 prefixes.",
    source_agent_id="agent-architect",
)
shared.write(
    "Concern: deprecation timeline for v1 is unclear.",
    source_agent_id="agent-reviewer",
)

for msg in shared.read():
    print(f"[{msg.source_agent_id}] {msg.content}")

Storage shape

• Each shared message is one Mnemo MemoryRecord with two tags:
  • conversation:<id> — every record in the conversation carries this.
  • participant:<source_agent_id> — the author.
• Participants list is a single Mnemo record tagged conversation:<id> + meta:participants, body = a JSON list of agent IDs. Updated on every attach / detach.

This keeps the conversation audit-log-replayable: every write is a hash-chained Mnemo memory, every participant change is a discrete write the operator can replay.

Conflict policy

The adapter does not pre-resolve conflicts at write time. When two participants write overlapping content within 60 seconds, both records land in Mnemo and the existing ResolutionStrategy::EvidenceWeighted scorer ranks them at recall time. Pre-resolving at write time would amount to silently dropping one participant’s contribution — the exact failure mode shared memory is supposed to avoid.

To inspect cross-participant overlaps for operator review:

for earlier, later in shared.overlapping_writes_within(seconds=60.0):
    print(f"{earlier.source_agent_id} → {later.source_agent_id}: "
          f"{earlier.content[:50]}... / {later.content[:50]}...")

Read semantics

# Full stream, time-ordered.
shared.read()

# Filter by author.
shared.read(from_agent="agent-reviewer")

# Forward a query through Mnemo's hybrid retrieval (vector + BM25).
shared.read(query="deprecation timeline", limit=10)

read() excludes the meta:participants metadata record automatically, so callers see only real messages.

Why a Mnemo-backed adapter rather than a Letta-API client

The blog post called for a MnemoLettaShared adapter, not a client. The shape — attach / detach / read / write — is useful by itself: any time multiple agents need a shared, audited, queryable history, this adapter does the job without needing a Letta account or API key. If you also use Letta’s orchestrator, point its agents at this adapter as their memory backend and the conversation state is portable.

Sources

• Letta-Code release (2026-04-06)
• Letta — Benchmarking AI Agent Memory
• letta_adapter.py source
• Example: examples/letta_shared_conversation.py

mnemo mcp-server — hardened MCP STDIO mode

v0.4.0-rc3, Task B2. Defends against the OX-MCP “exfiltrate-then-act” disclosure (2026-04-24) by refusing inherited secrets, JSON-injection argv, and untrusted parent processes BEFORE any engine state is constructed.

Why this exists

The default mnemo startup path is convenient: it reads OPENAI_API_KEY, MNEMO_ENCRYPTION_KEY, MNEMO_POSTGRES_URL, and a stack of CLI flags straight from the environment. That’s fine for local development. It is not fine when an attacker can spawn the binary inside someone else’s shell — the OX-MCP disclosure showed how a poisoned Claude Code session can cause the host to exec an MCP server with the attacker’s manifest attached and the user’s secrets visible.

mnemo mcp-server --manifest <path> is a hardened entry point with a narrower trust boundary:

• All privileged knobs (keystore, audit log destination, allowed tools, allowed agents, allowed parents) live in a TOML manifest the operator controls.
• Sensitive env vars are an automatic refusal.
• --config-style argv injection is an automatic refusal.
• Non-TTY parents that aren’t on the manifest’s allow-list are an automatic refusal.

The manifest

keystore_path     = "/etc/mnemo/keystore.toml"
audit_log_path    = "/var/log/mnemo/audit.jsonl"
allowed_tools     = ["mnemo.recall", "mnemo.verify"]
allowed_agents    = ["claude-prod"]
allowed_parents   = ["claude", "systemd"]

A full annotated example lives at examples/mcp-server/manifest.toml.

Keystore

The manifest’s keystore_path points at a chmod-restricted TOML file:

key_id  = "mnemo-prov-2026-04"
key_hex = "<64 hex chars / 32 bytes / openssl rand -hex 32>"

The hardened mode loads this file at startup and attaches a ProvenanceSigner (B1) to the engine. Every recall(..., with_provenance=true) returns a verifiable HMAC receipt. Rotate by writing a new file with a fresh key_id and updating the manifest.

The safe-spawn gauntlet

Before constructing any engine state, the binary runs three checks:

1. Inherited secrets. Refuses if the env carries any of: ANTHROPIC_API_KEY, OPENAI_API_KEY, HF_TOKEN, AWS_SECRET_ACCESS_KEY, GITHUB_TOKEN, MNEMO_ENCRYPTION_KEY. Run the binary through a secret-clearing wrapper (env -i, systemd Environment=). Override at your own risk: MNEMO_REJECT_INHERITED_SECRETS=0.
2. Args-based config. Refuses if argv contains --config, --config-json, --inline-config, -c, or --secret (in any =value form). All config must live in the manifest.
3. Untrusted parent. When stdin is not a TTY, the parent process basename (set via MNEMO_PARENT_BASENAME) must appear in manifest.allowed_parents. If the variable is unset the check is skipped — running interactively (TTY present) also lifts the check.

Each refusal exits non-zero with a stderr message that names the violating key/arg/parent.

Running it

# 1. Clear the env, set the parent assertion, pass the manifest.
env -i \
  PATH="$PATH" HOME="$HOME" \
  MNEMO_PARENT_BASENAME=systemd \
  mnemo mcp-server --manifest /etc/mnemo/manifest.toml

Under systemd:

[Service]
Type=simple
Environment=MNEMO_PARENT_BASENAME=systemd
ExecStart=/usr/local/bin/mnemo mcp-server --manifest /etc/mnemo/manifest.toml
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true

Verifying it

A quick “does the gauntlet actually fire” smoke test:

ANTHROPIC_API_KEY=leak mnemo mcp-server --manifest /etc/mnemo/manifest.toml
# refused to start: inherited sensitive env var "ANTHROPIC_API_KEY" ...

mnemo mcp-server --manifest /etc/mnemo/manifest.toml --config-json '{}'
# refused to start: command-line carries config-style argument ...

The full integration suite that exercises every refusal path lives in crates/mnemo-cli/tests/safe_spawn_integration.rs.

Role-aware tool filter (v0.4.2 — A1)

Mnemo’s MCP server aligns with the 2025-11-25 MCP authorization spec role-based annotations. The manifest can declare an optional [role_filter] block that gates tools/list (filters the advertised catalog) and tools/call (denies disallowed calls with a spec-compliant -32601).

[role_filter]
caller_roles = ["auditor"]
default      = "deny_all"

[role_filter.allow]
"mnemo.recall"   = ["auditor", "agent"]
"mnemo.verify"   = ["auditor"]
"mnemo.remember" = ["agent"]
"mnemo.forget"   = ["agent"]

[role_filter.deny]
"mnemo.delegate" = ["auditor"]

Rules:

• Deny always wins. A tool that appears in both allow and deny for the same role is denied.
• default = "allow_all" (the implicit default) lets any tool not named in allow/deny through. Use deny_all for a strict allow-list.
• caller_roles declares the role assignment the operator has made for the binary itself. In stdio transport this is the entire caller identity; in future HTTP transports it composes with roles inferred from the Authorization header.
• Every denied call emits an McpRoleDenied { caller_id, tool_name, attempted_at, reason } row to audit_log_path.
• Omitting the block keeps pre-v0.4.2 behaviour byte-for-byte. Every advertised tool stays reachable and no audit events are emitted.

The filter contract (RoleFilter trait + ManifestRoleFilter impl) is public, so a custom filter can replace the manifest-driven default at test time. See crates/mnemo-mcp/src/role_filter.rs and the three integration tests under crates/mnemo-mcp/tests/ (role_filter_allow_deny.rs, role_filter_audit_event.rs, role_filter_no_block_when_unset.rs).

What this does NOT cover

• Capability-leased reads (the old B2 follow-up) are not shipped: the never-wired lease store was removed as dead code. The design — per-read lease tokens gating forget_subject — is captured in #126 for a future authenticated, multi-caller transport where a lease has real cross-caller value (on stdio the operator is the only caller).
• The DPDPA consent-token-per-write path (B4).
• The Letta-protocol-compat surface (B5).
• Per-tool-method enforcement of the role filter at tools/call dispatch — the manifest schema, the filter trait/impl, and the audit emission are shipped in v0.4.2; threading the filter through every MnemoServer tool method body is still pending. The mnemo-envelope OTel exporter kind that a later step depends on is not built — see docs/roadmap/planned-crates.md.

For the threat model and the full design notes, see the rationale at the top of crates/mnemo-cli/src/safe_spawn.rs.

Compatibility note (v0.4.3 — U1)

The MCP wire-protocol version mnemo’s server speaks (2024-11-05, with the 2025-11-25 authorization spec layered on top) is independent of the client SDK version your agent uses. SDK refreshes are common and don’t require a mnemo-side rev unless the spec itself moves.

The current version-skew matrix tracks tested combinations of the four official client SDKs:

• mcp-python (refreshed 2026-05-01)
• mcp-go (refreshed 2026-05-01)
• mcp-ruby (refreshed 2026-05-02)
• mcp-csharp (refreshed 2026-05-02)

If your agent hits an SDK-side incompatibility, consult the matrix first — most issues land on a row that documents which mnemo cut shipped against that SDK pair. The matrix is enforced in CI by crates/mnemo-mcp/tests/sdk_matrix_doc_present.rs, so the doc itself cannot silently disappear ahead of an SDK-bump release.

MCP 2026 Roadmap alignment (v0.4.4 — U1)

Superseded as a statement of current direction. This section maps mnemo against the March 2026 roadmap. The 2026-07-28 spec release came after it. For what mnemo actually implements today, revision by revision, see MCP 2026-07-28 conformance. The mapping below is kept as history.

The MCP 2026 Roadmap (published 2026-03-09 by lead maintainer David Soria Parra) reorganises the protocol’s direction around four priority areas. The honest mnemo stance against each is below — spec-context anchor, not compliance claim.

The honest framing: mnemo claims alignment-by-design with one of four priorities, not roadmap compliance. The other three priorities are spec-evolution work where mnemo follows rmcp’s implementation of the SEPs as they’re written. Buyers reading the roadmap should hear “mnemo’s existing audit story already serves the Enterprise Readiness ask,” not “mnemo is MCP-2026-ready.”

AMP / memorywire conformance (v0.4.13)

Alongside the MCP STDIO surface, mnemo ships an AMP / memorywire interop adapter in the mnemo-amp crate. AMP models memory as 5 operations (remember / recall / forget / merge / expire) over 4 memory types (episodic / semantic / procedural / working), carried in a self-describing JSON envelope validated against a JSON-Schema 2020-12 document (mnemo_amp::schema()).

The adapter is a MemoryStore-conformant surface over a real MnemoEngine. Two ops are deliberately thin compositions over existing primitives rather than assumed engine methods:

• merge folds N records into one consolidated record (remember with SourceType::Consolidation) and retires the originals (forget with the Consolidate strategy). It is not mnemo’s engine.merge, which is a branch-timeline merge.
• expire sets expires_at and runs the existing run_ttl_sweep lifecycle path (there is no engine.expire).

A fan-out AmpRouter broadcasts writes to several backends and fuses multi-adapter recall with Reciprocal Rank Fusion. An optional HITL diff-and-approve hook gates long-term (semantic / procedural) writes and records each approval as a Decision event in mnemo’s hash-chained audit log, so the approve trail is tamper-evident and replayable.

Conformance mirrors the cross-adapter suite: recall@5 on a small labelled corpus end-to-end against the embedded DuckDB backend, and RRF-holds-under-rank-0-injection vs max-fusion (RRF keeps a genuinely-relevant item on top; max-fusion is fooled by an adversarial rank-0 injection). Run the end-to-end smoke binary with cargo run --release --bin amp_conformance -p mnemo-amp.

Honest scope: the crate provides the wire format, the schema document, and the engine-backed surface. AMP transport framing (HTTP / stdio, .well-known schema discovery) is left to the embedding application.

MCP 2026-07-28 conformance

State of mnemo against the 2026-07-28 MCP specification revision, row by row. Anchored at commit aec648f against rmcp 3.1.3 (what the workspace rmcp = "3.0" requirement resolves to).

This page exists because mnemo’s posture is to follow rmcp’s implementation rather than race the spec, and that posture is only defensible if there is a document saying which parts are and are not done. Without one, “we follow rmcp” is indistinguishable from “we have not looked”.

What the statuses mean

The headline

mnemo negotiates 2025-11-25, not 2026-07-28.

rmcp 3.1.3 knows the newer revision - it carries ProtocolVersion::V_2026_07_28, the CacheScope type, the SEP-2243 header constants and the MRTR result types - but its ProtocolVersion::LATEST is still V_2025_11_25, so that is what an initialize handshake settles on. Most of what follows falls out of that one fact.

The revisions mnemo advertises, which crates/mnemo-mcp/tests/mcp_2026_07_28_conformance.rs asserts against the running server:

• 2024-11-05
• 2025-03-26
• 2025-06-18
• 2025-11-25

2026-07-28 is deliberately not in that list, and goes back in when mnemo implements it, not when rmcp does.

Lifecycle and transport

Headers and caching

Why cacheScope is private and must stay that way. Both of mnemo’s listings are scoped to the caller’s per-request identity (ADR 0002): two callers presenting different capabilities see different tool catalogs, and resources/list returns one agent’s memory records. A public scope would permit a shared intermediary to serve one caller’s catalog, or one agent’s memories, to a different caller. CacheScope::default() is Public, so leaving the field unset is not the safe option it appears to be once anything downstream begins reading it. per_caller_listings_are_never_publicly_cacheable in crates/mnemo-mcp/tests/mcp_2026_07_28_conformance.rs asserts this on both surfaces, and was verified by mutation.

These fields belong to 2026-07-28 while mnemo negotiates 2025-11-25, so no client is currently promised them. They are emitted regardless: a client that does not know the field ignores it, while an intermediary that does understand cacheScope is told the truth now rather than after the eventual revision bump.

Why the error-code row stays open on purpose. mnemo emits -32002 because that is what 2025-11-25 - the revision it actually negotiates - specifies. Changing it to -32602 now would make mnemo non-conformant with the version it speaks in order to match a version it does not. The row closes when mnemo adopts 2026-07-28, not before.

Results

Authorization (RFC 9728, RFC 8707)

This section exists because its absence was the most likely thing to be mistaken for conformance. The rows above are about the wire protocol; nothing in them says whether mnemo does OAuth. It does not.

mnemo implements no OAuth authorization. There is no /.well-known/oauth-protected-resource document, no WWW-Authenticate challenge, no authorization-server discovery and no bearer-token audience validation. Authentication is an HMAC capability presented per request (ADR 0002), which is a different mechanism, not a partial implementation of this one.

That is a conformant position rather than a gap, and the spec says so in the paragraph that governs the whole authorization document:

Authorization is OPTIONAL for MCP implementations. When supported: Implementations using an HTTP-based transport SHOULD conform to this specification. Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.

mnemo’s default transport is stdio and it takes its capability key from the environment (MNEMO_CAPABILITY_KEY), which is the behaviour that paragraph prescribes.

Why this is worth stating rather than leaving blank

Serving RFC 9728 discovery is close to unheard of in practice: the scanning work in this project’s sibling reports 0 of 2,303 public MCP server configurations serving it. That figure is reported rather than reproduced here, and it is context, not an excuse. The useful thing is not that mnemo is normal, it is that a reader can find out in one place instead of inferring from silence.

An operator putting mnemo behind an OAuth-protected gateway should terminate authorization at that gateway and pass a capability inward. mnemo will not participate in the OAuth flow, will not advertise an authorization server, and will not accept the gateway’s access token in place of a capability.

Deprecations

None of these require work: mnemo never adopted any of them.

The explicit-handle pattern, and the audit behind it

SEP-2567 states the replacement for sessions directly:

Servers that need cross-call state use explicit, server-minted handles passed as ordinary tool arguments.

mnemo already worked this way. Under 2025-11-25 that was one valid option among several; under 2026-07-28 it is the sanctioned one. Being on the right side of a change by accident is not the same as being on it on purpose, so the property is now tested rather than assumed (crates/mnemo-mcp/tests/explicit_handle_roundtrip.rs).

Two handles carry every piece of cross-call state mnemo has:

The LeaseStore is server-side state, but it is not a session: it is the bookkeeping behind a server-minted handle that the caller threads back through a tool argument, which is precisely the shape the SEP prescribes. A lease is bound to the principal that minted it and expires, so it is narrower than a session, not a rebranding of one.

Audit: what depends on identity that is not an argument

Every tool in crates/mnemo-mcp/src/tools/ was checked for behaviour that depends on connection-scoped identity rather than on a value in the request.

• 19 of 23 tools take Parameters<T> and nothing else. Their signatures admit no context at all, so connection-scoped state is not merely unused, it is unrepresentable.
• 4 tools take Extension<CallerContext>: mnemo.recall, mnemo.forget_subject, mnemo.delegate, mnemo.trajectory_audit. This is not connection state. The CallerContext is resolved per request by identity.rs from that request’s own _meta (ADR 0002), and call_tool inserts it immediately before dispatch. Two calls on one connection carrying two different capabilities produce two different callers. _meta remains a per-request carrier under 2026-07-28, which puts protocol version and client capabilities there too, so this shape survives the revision unchanged.

The one deliberate deviation

When a request presents no capability at all, resolve_caller falls back to a boot-derived identity: the agent_id fixed when the server process started. That value is process-scoped, so this is a genuine departure from “everything arrives in the request”, and it is kept on purpose.

The reason is that on stdio one process is one peer, and the operator who started the server genuinely is the caller. Requiring a capability there would break every existing stdio deployment on upgrade to buy no security, because there is no second caller to distinguish from.

The deviation is bounded rather than open-ended:

• It applies only where no capability was presented. A capability that is present but unverifiable is an error, never a downgrade to the boot identity, since silently downgrading would hand a forged token the operator’s authority.
• On the network-facing http-transport, the fallback does not apply at all: an unauthenticated request gets AnonymousOnAuthenticatedTransport, because there the fallback would let anyone who can reach the port act as the operator.

See crates/mnemo-mcp/src/identity.rs for the full resolution table.

The defect this page found

Writing the table surfaced one live defect rather than only recording known ones.

mnemo did not override supported_protocol_versions(), so it took rmcp’s default of ProtocolVersion::KNOWN_VERSIONS. rmcp derives server/discover from that list. The result, confirmed against a running server:

advertised protocol_version  = 2025-11-25
supported_protocol_versions  = [2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25, 2026-07-28]

mnemo was telling any discovering client that it speaks 2026-07-28 while answering initialize with 2025-11-25 and implementing none of the newer revision’s server-side requirements. A client entitled to believe that advertisement would have sent 2026-07-28 requests to a server that still expects the handshake that revision removes, and would have received list results with neither ttlMs nor cacheScope.

That is a machine-readable claim that was not true - the same claimed-but-not-wired shape this repo has repaired before (role_filter #124, tool-catalog attestation v0.5.20, LeaseStore under ADR 0001).

The fix is to narrow the list to what mnemo serves. This is rmcp’s own supported mechanism rather than a workaround: its negotiate_protocol_version documents that “a server that narrows that list is never made to answer initialize with a version it cannot serve”, and a client asking for an unlisted revision negotiates down to the server fallback instead of failing. No client breaks.

What is still open, and what would close it

Four rows are not CONFORMS. None of the four is closable by mnemo alone today, which is the reason each carries a caller-assumption sentence in the table above rather than a promise.

All four collapse into one event: rmcp flips LATEST, mnemo adds V_2026_07_28 to supported_protocol_versions(), and this page is rewritten rather than amended. The error-code row is listed as a GAP rather than UPSTREAM-BLOCKED because mnemo could emit -32602 today; it does not, because -32002 is what the revision it actually speaks specifies, and changing it early would trade real conformance for imaginary conformance.

Separately, the authorization rows are not on this list. They are not open work: mnemo implements no OAuth and, on stdio, the spec says it should not. See the section above for what a caller should assume instead.

The two rows that were mnemo’s to close, ttlMs and cacheScope, are closed as of 0.5.26.

Deployment

Mnemo can be deployed in several configurations:

Environment Variables

Docker Deployment

Quick Start

docker run -d \
  --name mnemo \
  -v mnemo-data:/data \
  -e MNEMO_DB_PATH=/data/mnemo.db \
  -e OPENAI_API_KEY=sk-... \
  ghcr.io/mnemo-ai/mnemo:latest

Docker Compose

docker-compose up -d

The included docker-compose.yml starts Mnemo with PostgreSQL:

services:
  mnemo:
    build: .
    environment:
      MNEMO_POSTGRES_URL: postgres://mnemo:${POSTGRES_PASSWORD}@postgres/mnemo
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      MNEMO_REST_PORT: "8080"
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: mnemo
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set a strong POSTGRES_PASSWORD}
      POSTGRES_DB: mnemo
    volumes:
      - pg-data:/var/lib/postgresql/data

Building the Image

docker build -t mnemo .

The Dockerfile uses a multi-stage build for minimal image size.

Kubernetes Deployment

Helm Chart

Install Mnemo on Kubernetes using the Helm chart:

helm install mnemo deploy/helm/mnemo/ \
  --set postgres.url="postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/mnemo" \
  --set openaiApiKey="${OPENAI_API_KEY}"

Configuration

Key values.yaml options:

Scaling

For production with PostgreSQL:

helm upgrade mnemo deploy/helm/mnemo/ --set replicaCount=3

Multiple replicas share the same PostgreSQL database, each handling MCP or REST connections independently.

PostgreSQL Mode

PostgreSQL mode enables distributed, multi-instance Mnemo deployments with pgvector for vector search.

Setup

1. PostgreSQL with pgvector

docker run -d \
  --name mnemo-pg \
  -e POSTGRES_USER=mnemo \
  -e POSTGRES_PASSWORD=changeme_use_strong_password \
  -e POSTGRES_DB=mnemo \
  -p 5432:5432 \
  pgvector/pgvector:pg16

2. Start Mnemo with PostgreSQL

mnemo --postgres-url "postgres://mnemo:$POSTGRES_PASSWORD@localhost/mnemo"

Or build with the postgres feature:

cargo build --release --features postgres

Schema

Mnemo automatically creates all required tables on first connection:

• memories with pgvector vector(N) column and HNSW index
• acls, delegations, relations, agent_events
• checkpoints, agent_profiles

Differences from DuckDB Mode

Security

Encryption

Mnemo supports AES-256-GCM at-rest encryption for memory content. Enable it by setting:

export MNEMO_ENCRYPTION_KEY=$(openssl rand -hex 32)
mnemo --encryption-key "$MNEMO_ENCRYPTION_KEY" --db-path my.db

Content is encrypted before storage and decrypted on recall. The encryption key must be 64 hex characters (32 bytes).

Access Control Model

Mnemo implements a three-tier access control model:

1. Owner Access

The agent that created a memory has full access (read, write, delete, share, delegate).

2. ACL-Based Sharing

Explicit access grants via the share tool. Each ACL entry specifies:

• Target agent ID
• Permission level (read, write, delete, share, delegate)
• Optional expiration time

3. Delegation

Agents can delegate their permissions to others with:

• Scoping (all memories, by ID, or by tag)
• Maximum transitive depth
• Time bounds
• Automatic revocation on expiry

The REST /v1/delegate endpoint verifies the caller has Delegate permission on each target memory before creating the delegation.

Hash Chain Integrity

Every memory record includes a SHA-256 hash chain:

• content_hash = SHA256(content + agent_id + timestamp)
• prev_hash links to the previous record’s hash via SHA256(content_hash + prev_content_hash)
• The verify tool checks the entire chain for tampering
• Hash comparisons use constant-time operations (subtle::ConstantTimeEq) to prevent timing side-channels

Memory Poisoning Detection

Mnemo monitors agent behavior profiles and flags anomalous memory creation:

• Rapid creation rate (burst detection)
• Content length deviation from agent baseline
• Importance score anomalies
• Prompt injection patterns — 11 common patterns detected (e.g. “ignore all previous instructions”, “override system prompt”)

Flagged memories are quarantined and excluded from recall results. The anomaly score threshold is 0.5; prompt injection detection alone scores +0.5.

Input Validation

• agent_id: validated for length (max 256 characters) and allowed characters (alphanumeric, hyphens, underscores, dots)
• content: must be non-empty
• importance: must be between 0.0 and 1.0

REST API Security

• CORS: configurable origin allowlist via MNEMO_CORS_ORIGINS environment variable. Defaults to localhost only (localhost:3000, localhost:8080). Set to * to allow all origins.
• Body limits: 2 MB maximum request body size to prevent denial-of-service
• Error handling: internal errors are logged server-side; clients receive generic “internal server error” messages

pgwire Security

• Authentication: optional cleartext password authentication (configure via PgWireConfig.password)
• Binding: defaults to 127.0.0.1:5433 (localhost only)
• For production, deploy behind a TLS-terminating proxy

Environment Variables

Best Practices

1. Always set secrets via environment variables, not CLI args
2. Use time-bounded delegations with minimum required permissions
3. Regularly run verify to check hash chain integrity
4. Monitor quarantine events for potential poisoning attempts
5. Use PostgreSQL mode with TLS for production deployments
6. Enable encryption for sensitive data with MNEMO_ENCRYPTION_KEY
7. Configure MNEMO_CORS_ORIGINS explicitly in production

Compliance Overview

Mnemo is an MCP-native memory database for AI agents. This section documents how Mnemo’s architecture and feature set align with industry compliance frameworks, specifically SOC 2 Type II and HIPAA. The goal is to provide operators, auditors, and prospective customers with a clear mapping between regulatory requirements and the technical controls that Mnemo implements.

Compliance Posture Summary

Mnemo was designed with security and auditability as first-class concerns. The following capabilities form the foundation of its compliance story:

Documents in This Section

• SOC 2 Controls – Maps each SOC 2 Trust Service Criteria category (CC1 through CC9) to specific Mnemo features, implementation modules, and current status.

• HIPAA Safeguards – Maps HIPAA Administrative, Physical, and Technical Safeguards to Mnemo capabilities, identifies gaps, and provides recommendations for covered-entity deployments.

How to Use This Documentation

For auditors: Each control mapping includes the control identifier, a description of the requirement, the specific Mnemo module or feature that addresses it, the current implementation status, and any known gaps with recommended mitigations.

For operators: Use this documentation to understand which compliance controls Mnemo provides out of the box and which require additional operational procedures, infrastructure configuration, or third-party tooling.

For developers: The module references in each control mapping point directly to source files in crates/mnemo-core/src/. Consult those files for implementation details when extending or auditing controls.

Implementation Status Legend

Throughout the compliance documents, the following status labels are used:

Versioning

This compliance documentation reflects the current compliance posture of Mnemo (23 registered MCP tools; see the tools reference). It should be updated whenever security-relevant features are added or modified.

SOC 2 Trust Service Criteria – Control Mapping

This document maps the AICPA SOC 2 Trust Service Criteria (2017 revision) to Mnemo’s security architecture. Each section covers one Common Criteria (CC) category, lists the relevant controls, describes how Mnemo addresses them, and identifies any gaps or recommendations.

For background on Mnemo’s security features, see the Security page and the Compliance Overview.

CC1 – Control Environment

The control environment sets the tone for the organization, influencing the control consciousness of its people. It is the foundation for all other components of internal control.

CC1.1 – Commitment to Integrity and Ethical Values

CC1.2 – Board Oversight

CC1.3 – Management Structure and Authority

CC1.4 – Competence Commitment

CC1.5 – Accountability

CC2 – Communication and Information

The entity uses relevant, quality information to support the functioning of internal control and communicates information internally and externally.

CC2.1 – Information Quality

CC2.2 – Internal Communication

CC2.3 – External Communication

CC3 – Risk Assessment

The entity identifies and assesses risks to the achievement of its objectives, including risks related to fraud.

CC3.1 – Objective Specification

CC3.2 – Risk Identification and Analysis

CC3.3 – Fraud Risk Assessment

CC3.4 – Change-Related Risk Assessment

CC5 – Control Activities

The entity selects and develops control activities that contribute to the mitigation of risks to the achievement of objectives to acceptable levels.

CC5.1 – Selection of Control Activities

CC5.2 – Technology-Based Control Activities

CC5.3 – Deployment of Control Activities Through Policies

CC6 – Logical and Physical Access Controls

The entity implements logical access security software, infrastructure, and architectures over protected information assets.

CC6.1 – Logical Access Security

CC6.2 – Authentication and Authorization

CC6.3 – Data Encryption

CC6.4 – Restriction of Physical Access

CC6.5 – Disposal of Information Assets

CC6.6 – Protection Against External Threats

CC7 – System Operations

The entity uses detection and monitoring procedures to identify changes to configurations and system components that may indicate an attack.

CC7.1 – Detection of System Changes

CC7.2 – Monitoring for Anomalies

CC7.3 – Evaluation and Response

CC7.4 – Incident Response

CC8 – Change Management

The entity authorizes, designs, develops, configures, documents, tests, approves, and implements changes to infrastructure and software.

CC8.1 – Change Authorization

CC8.2 – Testing of Changes

CC8.3 – Change Documentation

CC9 – Risk Mitigation

The entity identifies, selects, and develops risk mitigation activities.

CC9.1 – Risk Mitigation Selection

CC9.2 – Vendor and Business Partner Risk

Summary Matrix

Priority Gaps

The following items represent the highest-priority gaps for achieving full SOC 2 compliance. They are listed in recommended order of implementation:

1. Upgrade encryption to production-grade AES-256-GCM (CC6.3) – Replace the simplified XOR cipher with the aes-gcm crate. This is the most critical gap.

2. Implement formal authentication (CC6.2) – Add agent registration, API key management, and external identity provider integration.

3. Add automated hash chain verification (CC7.1) – Schedule periodic verification runs with alerting on failures.

4. Implement incident response tooling (CC7.4) – Build forensic export, bulk quarantine, and bulk revocation capabilities.

5. Add compliance reporting endpoints (CC2.3) – Export audit data in standard formats for external consumption.

HIPAA Safeguards – Control Mapping

This document maps the HIPAA Security Rule safeguards (45 CFR Part 164, Subpart C) to Mnemo’s security architecture. It is intended for organizations that deploy Mnemo in environments where Protected Health Information (PHI) may be stored as agent memories.

HIPAA compliance is a shared responsibility between Mnemo (as the software component) and the deploying organization (as the covered entity or business associate). This document identifies which safeguards Mnemo addresses through its architecture and which require operational controls from the deploying organization.

For background on Mnemo’s security features, see the Security page and the Compliance Overview.

Administrative Safeguards (Section 164.308)

Administrative safeguards are administrative actions, policies, and procedures to manage the selection, development, implementation, and maintenance of security measures to protect ePHI.

164.308(a)(1) – Security Management Process

Requirement: Implement policies and procedures to prevent, detect, contain, and correct security violations.

(i) Risk Analysis (Required)

(ii) Risk Management (Required)

(iii) Sanction Policy (Required)

(iv) Information System Activity Review (Required)

164.308(a)(2) – Assigned Security Responsibility

164.308(a)(3) – Workforce Security

Requirement: Implement policies and procedures to ensure that all members of the workforce have appropriate access to ePHI.

(i) Authorization and/or Supervision (Addressable)

(ii) Workforce Clearance Procedure (Addressable)

(iii) Termination Procedures (Addressable)

164.308(a)(4) – Information Access Management

Requirement: Implement policies and procedures for authorizing access to ePHI.

(i) Isolating Health Care Clearinghouse Functions (Required)

(ii) Access Authorization (Addressable)

(iii) Access Establishment and Modification (Addressable)

164.308(a)(5) – Security Awareness and Training

Requirement: Implement a security awareness and training program for all members of the workforce.

164.308(a)(6) – Security Incident Procedures

Requirement: Implement policies and procedures to address security incidents.

164.308(a)(7) – Contingency Plan

Requirement: Establish policies and procedures for responding to an emergency or other occurrence that damages systems containing ePHI.

(i) Data Backup Plan (Required)

(ii) Disaster Recovery Plan (Required)

(iii) Emergency Mode Operation Plan (Required)

164.308(a)(8) – Evaluation

Physical Safeguards (Section 164.310)

Physical safeguards are physical measures, policies, and procedures to protect electronic information systems and related buildings and equipment from natural and environmental hazards and unauthorized intrusion.

164.310(a)(1) – Facility Access Controls

164.310(b) – Workstation Use

164.310(c) – Workstation Security

164.310(d)(1) – Device and Media Controls

Requirement: Implement policies and procedures that govern the receipt and removal of hardware and electronic media containing ePHI.

(i) Disposal (Required)

(ii) Media Re-use (Required)

Technical Safeguards (Section 164.312)

Technical safeguards are the technology, and the policy and procedures for its use, that protect ePHI and control access to it.

164.312(a)(1) – Access Control

Requirement: Implement technical policies and procedures for electronic information systems that maintain ePHI to allow access only to those persons or software programs that have been granted access rights.

(i) Unique User Identification (Required)

(ii) Emergency Access Procedure (Required)

(iii) Automatic Logoff (Addressable)

(iv) Encryption and Decryption (Addressable)

164.312(b) – Audit Controls

164.312(c)(1) – Integrity

Requirement: Implement policies and procedures to protect ePHI from improper alteration or destruction.

(i) Mechanism to Authenticate ePHI (Addressable)

164.312(d) – Person or Entity Authentication

164.312(e)(1) – Transmission Security

Requirement: Implement technical security measures to guard against unauthorized access to ePHI that is being transmitted over an electronic communications network.

(i) Integrity Controls (Addressable)

(ii) Encryption (Addressable)

Summary Matrix

Priority Gaps for HIPAA Compliance

The following items represent the highest-priority gaps for organizations deploying Mnemo in HIPAA-regulated environments. They are listed in recommended order of implementation:

1. Upgrade encryption to production-grade AES-256-GCM (164.312(a)(2)(iv)) – Replace the simplified XOR cipher with the aes-gcm crate. This is the single most critical gap for HIPAA compliance.

2. Implement cryptographic authentication (164.312(d)) – Add API key management, mTLS, or JWT-based authentication. Agent identity must be cryptographically verified, not just asserted.

3. Enforce TLS for all network transports (164.312(e)(2)(ii)) – Reject non-TLS connections in network deployment modes. Implement certificate validation.

4. Add key rotation and management (164.312(a)(2)(iv)) – Implement encryption key rotation without downtime. Add envelope encryption for per-record key management.

5. Implement automated backup and recovery (164.308(a)(7)) – Add scheduled checkpoint creation, backup verification, and documented recovery procedures with defined RTO/RPO.

6. Add session timeout (164.312(a)(2)(iii)) – Implement configurable inactivity timeout for REST API and MCP sessions.

7. Implement tenant isolation (164.308(a)(4)) – Enforce strict data separation by org_id at the database query level to prevent cross-tenant data leakage.

8. Implement break-glass access (164.312(a)(2)(ii)) – Add an emergency access mechanism with enhanced audit logging for HIPAA-mandated emergency access procedures.

Deployment Recommendations for Covered Entities

Organizations subject to HIPAA that deploy Mnemo should implement the following operational controls in addition to Mnemo’s built-in safeguards:

Infrastructure

• Deploy Mnemo behind a TLS-terminating reverse proxy (e.g., nginx, Envoy).
• Use PostgreSQL mode with TLS-encrypted connections for production.
• Store the encryption key (MNEMO_ENCRYPTION_KEY) in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager), not in environment files.
• Run Mnemo containers with read-only root filesystems and non-root users.
• Implement network policies restricting Mnemo’s inbound and outbound traffic.

Operations

• Assign a security official responsible for Mnemo deployment and configuration.
• Conduct a risk assessment specific to your PHI data flows through Mnemo.
• Establish backup schedules using the checkpoint system with offsite replication.
• Document and test disaster recovery procedures quarterly.
• Implement log forwarding from Mnemo’s event log to your SIEM system.
• Schedule periodic hash chain verification using the mnemo.verify tool.

Access Management

• Map organizational roles to Mnemo’s permission hierarchy.
• Use time-bounded delegations with the minimum required permission level.
• Review active ACLs and delegations quarterly.
• Implement agent deprovisioning procedures that revoke all permissions.
• Maintain an access authorization matrix mapping agents to data categories.

Incident Response

• Define incident severity levels for Mnemo security events.
• Establish escalation procedures for quarantine events and verification failures.
• Document breach notification procedures per HIPAA requirements (60-day notification timeline).
• Conduct tabletop exercises simulating data integrity incidents.

Training

• Train operators on Mnemo’s security features and compliance controls.
• Include Mnemo-specific content in HIPAA security awareness training.
• Document procedures for handling PHI within agent memory workflows.

DPDPA — Digital Personal Data Protection Act (India)

Enforceable from 13 November 2026, the DPDPA requires Indian data fiduciaries to consult a DPB-registered Consent Manager before processing personal data and to honour consent withdrawal as an erasure right.

Mnemo’s mnemo-compliance crate provides two primitives to help with this; both are behind the compliance feature flag so v0.1.1 callers stay compiling.

ConsentSource trait

crates/mnemo-compliance/src/consent.rs. A pluggable interface that looks up the current consent state for a subject.

#![allow(unused)]
fn main() {
use mnemo_compliance::{ConsentSource, ConsentState, HttpConsentManager};

let cm = HttpConsentManager::new("https://consent.example.com/v1")
    .with_bearer(std::env::var("CONSENT_TOKEN")?);
let state: ConsentState = cm.fetch_consent("user-42").await?;
if state.has_scope("remember") && state.is_active() {
    // proceed with writing personal data
}
}

Available implementations

• HttpConsentManager — generic HTTP binding. Expects GET {base_url}/consent/{subject_id} to return a body matching [ConsentState]. Optional bearer-token auth.
• StaticConsentSource — in-memory map, for tests and single-tenant self-hosting.

ConsentState shape

#![allow(unused)]
fn main() {
pub struct ConsentState {
    pub subject_id: String,
    pub scopes: Vec<String>,          // granted purposes
    pub expires_at: Option<String>,   // optional wall-clock expiry
    pub token_hash: String,           // SHA-256 of the signed token
}
}

Missing scopes are treated as denied. Expired states are rejected by is_active() and by HttpConsentManager::fetch_consent.

Integration point: write-path consent check

Operators should call fetch_consent before every engine.remember that touches personal data, and map a missing scope to ComplianceError::ConsentDenied { subject_id, scope }. A reference middleware is sketched in the compliance feature’s docs but not yet wired into the core remember pipeline — doing so is part of the v0.3.2 roadmap (requires a PolicyHook surface on MnemoEngine).

Consent withdrawal

Wire the consent manager’s withdrawal webhook to [engine.forget_subject(subject_id, ForgetStrategy::Redact)] (which ships since v0.2.0). Redact preserves content_hash + prev_hash so the audit trail stays verifiable even after the content is erased; alternatively use HardDelete if you have no retention obligation.

Audit trail

Every forget_subject emits a MemoryRedact audit event with a hash-chain link to the prior event. Combine with the EU AI Act export surface for a single signed trail.

EU AI Act — audit log export

The EU AI Act (enforceable from 2 August 2026 for GPAI providers) requires retention of event logs with integrity controls and a path to export records for AI Office document requests. Mnemo’s mnemo-compliance crate ships a matching surface.

export_audit_log

#![allow(unused)]
fn main() {
use mnemo_compliance::{
    AuditFormat, AuditSigner, export_audit_log, verify_ndjson_signed,
};

let events = engine.storage.list_events("agent-id", 10_000, 0).await?;
let signer = AuditSigner::from_secret_bytes(&ed25519_secret);

// NDJSON with detached Ed25519 signature chain
let bundle = export_audit_log(
    &events,
    AuditFormat::NdjsonSigned,
    Some(&signer),
)?;
std::fs::write("audit.ndjson", bundle.bytes)?;

// Reverse: verify
let verified = verify_ndjson_signed(
    &std::fs::read("audit.ndjson")?,
    bundle.verifying_key_hex.as_ref().unwrap(),
)?;
}

Supported formats

• AuditFormat::NdjsonSigned — one JSON line per event plus a detached Ed25519 signature that covers SHA256(index ∥ prev_hash ∥ event_json). Canonicalises through serde_json::Value so the signer and verifier agree on bytes regardless of struct field ordering. Tampering breaks the chain at the first mutated byte and verify_ndjson_signed returns ComplianceError::ChainBroken { index, reason }.
• AuditFormat::EuAiOfficeCsv — the columnar template the AI Office consumes for GPAI document requests. RFC4180-escaped; header row first. Columns: event_id, timestamp, agent_id, event_type, model, thread_id, tokens_input, tokens_output, content_hash.

Key management

AuditSigner never generates or stores keys on its own. Operators are expected to keep the 32-byte Ed25519 secret behind an HSM or KMS and pass it through AuditSigner::from_secret_bytes. generate_ephemeral exists purely for tests.

Integration with forget_subject

When a DPDPA consent withdrawal triggers forget_subject, the emitted MemoryRedact events land in the audit trail with a proper prev_hash link. A later export_audit_log call signs the chain end-to-end, giving regulators a single artefact that covers both the original write and its regulated erasure.

What’s NOT in v0.3.1

• No encryption-key rotation story (deferred to v0.4.0).
• No streaming export from the REST / gRPC surfaces — today the export function is synchronous against an in-memory event list. For very long audit windows, callers should batch via storage.list_events(agent_id, limit, offset) and feed slices into export_audit_log.
• No retention-policy enforcement. The trail retains whatever the storage backend retains.

Performance

Benchmarks

Every published headline number — retrieval quality, poisoning resistance, audit tamper-evidence — with its exact reproduction command and raw-results file lives in one place: the benchmark index. Start there; each row also says what the number does not show.

Mnemo includes Criterion benchmarks in benches/engine_bench.rs:

cargo bench -p mnemo-core

Retrieval Strategies

Storage Backend Comparison

Optimization Tips

1. Use noop embeddings during development (faster, no API calls)
2. Set appropriate limits in recall to avoid over-fetching
3. Use tags and filters to narrow search space before semantic search
4. Use exact strategy when you know the filtering criteria
5. Run decay passes periodically to clean up low-importance memories