convez.ai
MCP ServerDados & AnalyticsAvançado
sattyamjjain

Mnemo — Banco de Memória para Agentes IA

sattyamjjain/mnemo

Memória persistente semântica para agentes IA com criptografia end-to-end

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP nativo que fornece um banco de dados embarcado de memória para agentes de IA, com primitivas REMEMBER, RECALL, FORGET e SHARE. Oferece busca híbrida com vetores, criptografia AES-256-GCM, suporte a DuckDB/PostgreSQL e múltiplos protocolos de acesso (MCP, REST, gRPC, pgwire).

Instalação

$npx convez-ai sattyamjjain/mnemo

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
1
Acompanhando
1
Saúde
57%
Último commit
há 5 dias
Versão
v0.5.29
Issues abertas
4
Contribuidores
3

Casos de uso

  • Persistência de memória entre sessões de agentes IA
  • Busca semântica híbrida de informações armazenadas
  • Compartilhamento seguro de memória entre múltiplos agentes
  • Checkpoints e branches para experimentação com rollback
  • Auditoria com verificação de integridade via hash chain

Veredito

Mnemo é uma solução robusta e bem-projetada para um problema real: agentes IA carecem de memória persistente confiável. A implementação em Rust, suporte a múltiplos protocolos e primitivas bem definidas (REMEMBER/RECALL/FORGET/SHARE) demonstram maturidade técnica, embora exija familiaridade com sistemas distribuídos para aproveitar ao máximo.

README

A tradução para o português deste README ainda está na fila.

Mnemo

CI License: Apache-2.0 Rust

MCP-native memory database for AI agents.

Mnemo (from Greek mneme — memory) is an embedded database whose primitives are REMEMBER, RECALL, FORGET, and SHARE — exposed as MCP tools that any AI agent can connect to directly.

Quickstart

1. Build

cargo build --release

2. Configure your AI agent

Add to your MCP client configuration (e.g. Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "mnemo": {
      "command": "./target/release/mnemo",
      "args": ["--db-path", "./agent.mnemo.db"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

3. Use it

Your AI agent now has persistent memory with 12 MCP tools:

ToolDescription
mnemo.rememberStore a new memory with semantic embeddings
mnemo.recallSearch memories by semantic similarity, keywords, or hybrid
mnemo.forgetDelete memories (soft delete, hard delete, decay, consolidate, archive)
mnemo.shareShare a memory with another agent
mnemo.checkpointSnapshot the current agent memory state
mnemo.branchCreate a branch from a checkpoint for experimentation
mnemo.mergeMerge a branch back into the main state
mnemo.replayReplay events from a checkpoint
mnemo.delegateDelegate scoped, time-bounded permissions to another agent
mnemo.verifyVerify SHA-256 hash chain integrity
mnemo.attention_state.putv0.4.5 — Store an opaque attention-state blob keyed by (agent_id, prefix_hash) (anchored on arXiv:2605.18226; only registered when the server is built with MnemoServer::with_attention_state(...))
mnemo.attention_state.getv0.4.5 — Look up an attention-state blob by (agent_id, prefix_hash); returns null on miss

Access Protocols

ProtocolCrateUse Case
MCP (stdio)mnemo-mcpAI agent integration via rmcp 1.3
REST (HTTP)mnemo-restWeb clients, dashboards, OTLP ingest
gRPCmnemo-grpcHigh-performance service-to-service (11 RPCs)
pgwiremnemo-pgwireConnect with any PostgreSQL client (psql)
AMP (memorywire)mnemo-ampAMP-conformant adapter: 5 ops × 4 memory types over a JSON-Schema 2020-12 envelope

Attention-state-memory substrate (v0.4.5)

mnemo v0.4.5 ships an attention-state-memory substrate anchored on arXiv:2605.18226 (Context Memorization). Two new MCP tools — mnemo.attention_state.put and mnemo.attention_state.get — store and retrieve opaque attention-state blobs keyed by (agent_id, prefix_hash). The substrate is implemented in crates/mnemo-attention-state with a typed AttentionStateStore trait + an InMemoryAttentionStateStore reference impl.

Honest scope: mnemo ships the store. The producer (inference runtime that extracts prefix states) and the consumer (re-injection on the next generation) are out of scope; the substrate's blob format, model compatibility, and quantization sensitivity are the producer's responsibility. Tools are registered only when MnemoServer::with_attention_state(...) is configured at startup; unconfigured calls return a spec-shaped error result, not a panic. See the research anchor for the operator recipe + the explicit non-overclaim disclaimers.

Memory under interference — current-fact resolver (v0.4.7)

arXiv:2605.18565 (MINTEval) measures how often memory systems return a superseded value of a fact after the same fact has been revised K times. mnemo v0.4.7 ships an opt-in current-fact resolver that post-processes the standard recall result set: candidates sharing the same value under a caller-chosen fact_key (typical convention: "fact_id") are grouped, and only the most-recent write per group is kept. When include_supersession_chain = true, older fact-versions are returned in the response's new superseded field for audit.

Enable via the MCP recall tool param current_fact_resolver: { fact_key, include_supersession_chain }, the REST ?current_fact_key=…&current_fact_include_chain=true query params, or the Rust RecallRequest.current_fact_resolver = Some(...) field directly. The default read path is unchanged — the resolver is purely additive and opt-in. The MINTEval-shaped bench at bench/locomo/src/bin/interference.rs compares default vs resolver arms across K ∈ {1, 3, 5, 10} revisions; see the resolver module doc at crates/mnemo-core/src/query/current_fact_resolver.rs for the contract + the explicit "not a contradiction detector / not a write-side guard" disclaimers.

Repeated-context recall — orientation cache (v0.4.8)

arXiv:2605.19932 (PEEK — Prefix-Encoded Episodic Knowledge) shows that a small, token-budgeted "orientation map" maintained alongside an agent's retrieval surface (key entities, UPPER_SNAKE constants, fenced schema fragments that have been useful) lets agents re-enter long-running contexts with a fraction of the recall payload. mnemo v0.4.8 ships an opt-in orientation cache that post-processes the standard recall result set: a heuristic Distiller extracts transferable knowledge from each hit and a priority Evictor enforces a fixed token budget (default 512). The recall response carries the bounded rendered map alongside top-k so the caller has both what is in scope and what is relevant right now in one payload.

Enable via the MCP recall tool param orientation_cache: { namespace?, token_budget?, include_in_response?, distill? }, the REST ?orientation_cache=true&orientation_namespace=…&orientation_token_budget=… query params, the gRPC OrientationCacheRequest message, the pgwire /*+ orientation_cache */ SQL hint comment, or the Rust RecallRequest.orientation_cache = Some(OrientationCacheConfig::new()) field directly. The store is in-process, namespace-scoped ((org_id, agent_id) by default), and lost on restart — persistence is a v0.5.x knob. The default read path is unchanged and orientation rendering only fires when both the caller passes a config AND the engine has an OrientationCacheStore attached via MnemoEngine::with_orientation_cache_store(). See the PEEK-anchored bench at bench/locomo/src/bin/orientation.rs for the repeated-context scenario (K ∈ {3, 6, 10, 15} calls per trial) and the module doc at crates/mnemo-core/src/query/orientation_cache.rs for the contract + the explicit "not a learned summariser / not a context-window extender / not persisted" disclaimers.

Cost-aware, answer-impact-scored recall — evidence budget (v0.4.12)

The default recall path front-loads: it returns the top-limit records by fused score, and an LLM caller pays context tokens for every chunk whether or not it changes the answer. mnemo v0.4.12 ships an opt-in cost-aware evidence budget that runs over the already-ranked candidate set and returns the smallest prefix that clears a configurable sufficiency bar, capped by an optional max_evidence. It is purely subtractive — it only ever returns a prefix of the ranked list, so it can never reorder or silently lower the retrieval's top-k cosine ordering (enforced by a property test).

Relevance is computed through a pluggable EvidenceScorer trait so callers can swap the signal used to decide sufficiency: CosineScorer (default — cosine of candidate vs query embedding, falling back to the fused retrieval score when embeddings are absent/degenerate) and DeltaScorer — an answer-impact scorer that rates a chunk by whether adding it to the evidence already selected would change a downstream answer. The "would the answer change?" judgement is an injectable closure (DeltaScorer::new(|ctx| …)) so the engine core stays model-agnostic; DeltaScorer::stub() ships a deterministic marginal-novelty heuristic for tests and offline use.

Enable via the Rust RecallRequest.evidence_budget = Some(EvidenceBudget { max_evidence, stop_when_sufficient, sufficiency_threshold, scorer }) field. Attach a custom answer-impact scorer with MnemoEngine::with_evidence_scorer(Arc<dyn EvidenceScorer>); when the budget selects ScorerKind::Delta but no scorer is attached, the path falls back to cosine rather than erroring. The recall response carries an evidence_selection diagnostics block (scorer name, examined vs returned counts, cumulative score, early-stop / capped flags). The default read path is unchanged — no evidence_budget means the legacy front-loaded top-limit. See the module doc + property test at crates/mnemo-core/src/query/evidence.rs and the end-to-end integration test at crates/mnemo-core/tests/cost_aware_recall.rs.

Budgeted evidence retention — EMBER-style capsules (arXiv:2606.05894)

Where the v0.4.12 evidence budget caps how many records come back, an agent that must keep evidence resident in a bounded context window has a different problem: raw chunk dumps burn the window fast — a handful of full records and it's full, even though most of each record is filler around one salient fact. EMBER (arXiv:2606.05894) frames this as a writer problem: under a fixed retained-token budget, keep compact, recoverable evidence rather than raw text.

mnemo extends the verified recall surface with an opt-in RecallRequest.retained_token_budget: Option<usize>. When set, the engine packs the recalled hits into at most budget tokens as verbatim evidence capsules — a short verbatim excerpt plus a retrieval key (the record id, so the caller re-fetches the full chunk on demand) — ranked by a v0 recoverability heuristic (recency × retrieval-hit-rate) standing in for EMBER's learned writer. It is purely additive: the memories list is unchanged, and the capsule view rides in RecallResponse.retained_evidence. No new enum, no protocol change — just the one parameter on the existing surface.

The eval at crates/mnemo-core/tests/budgeted_evidence_retention.rs measures the knob's value on a LongMemEval-style fixture (60 gold facts, each behind a noisy chunk) at a fixed 8192-token budget — budgeted capsules vs naive truncation:

| arm               | covered | recall@budget | retained tokens |
|-------------------|--------:|--------------:|----------------:|
| naive truncation  |      45 |         0.750 |             n/a |
| budgeted capsules |      60 |         1.000 |            4380 |

Because each capsule costs a fraction of a raw chunk, every gold fact survives the budget (recall 1.000 vs 0.750) using barely half the tokens. See the module doc + tests at crates/mnemo-core/src/query/retained.rs for the cost model + the full "what this is NOT" block (v0 heuristic, not EMBER's learned writer; read-side projection, nothing mutated).

Offline consolidation — Auto-Dreamer-shaped active-bank shrink (v0.4.8)

Anthropic's Auto-Dreamer consolidation runs offline, away from the agent's interactive loop, and produces a smaller active bank of semantic summaries that should serve subsequent recall at least as well as the raw episodic trace it replaced. mnemo's existing run_decay_pass + run_consolidation path (crates/mnemo-core/src/query/lifecycle.rs, plus the reflection module at crates/mnemo-core/src/query/reflection.rs that mirrors the same offline-housekeeping shape) is the engine-side equivalent: the decay pass marks low effective-importance records as Archived / Forgotten, the consolidation pass replaces tag-overlap clusters of episodic memories with structured [Consolidated from N memories] … semantic bundles, and the originals are flipped to Consolidated rather than deleted (so the chain stays auditable). The new Auto-Dreamer-shaped scenario at bench/locomo/src/bin/auto_dreamer_consolidation.rs exercises both passes end-to-end on a synthetic multi-session trajectory and reports the two axes Auto-Dreamer headlines as its claim: active_bank_ratio = post / pre (expects < 1.0) and held-out recall_post >= recall_pre. A JSON summary lands beside the Markdown report so the headline number is citable here.

Run via cargo run --release --bin auto_dreamer_consolidation -p mnemo-locomo-bench — defaults to 8 sessions × 25 facts × 5 trials with archive/forget thresholds of 0.40 / 0.10 and min_cluster_size = 3; all tunable via CLI flags. The default read path is unchanged — the bench only consumes existing mnemo_core::query::lifecycle::* APIs and adds no public surface. See the bin module rustdoc for the full "what this bin is NOT" block (not a faithful Auto-Dreamer reproduction; not the criterion crate; NoopEmbedding makes the vector lane degenerate by design; single-agent, single-scope).

Embedding-backend selection — SLA-aware recommender (v0.4.9)

arXiv:2605.23618 (GE2 vs local encoders — quality + latency) motivates choosing an embedding backend by measured quality and tail-latency on the operator's workload, not by reputation. mnemo v0.4.9 ships bench/embeddings, a criterion-driven bench + SLA-aware recommender that runs each configured backend (Noop and a bench-local hashing baseline always; OpenAiEmbedding when OPENAI_API_KEY is set; OnnxEmbedding when MNEMO_ONNX_MODEL_PATH is set and mnemo-core was built with the onnx feature) against a 50-document / 10-query labeled fixture and reports nDCG@10, recall@10, p50/p95 single-vector embed latency, and throughput at batch sizes 1/8/32. The recommender then picks the highest-nDCG backend whose p95 ≤ the SLO and reports the explicit nDCG gap vs the absolute best-quality backend (so the operator sees "you give up 0.003 nDCG for 7x lower p95 latency" rather than a black-box choice).

Run via mnemo bench embeddings --slo-ms <N> (built into the mnemo binary) or cargo bench -p mnemo-embeddings-bench (criterion HTML reports at target/criterion/embed_single/). The default read path is unchanged — no retrieval defaults, no RRF weights, no EmbeddingProvider impls are touched. The embedded-first wedge stays: default builds run without OPENAI_API_KEY and the recommender picks a local backend. See bench/embeddings/README.md for the full "what this bench is NOT" block (not a faithful arXiv:2605.23618 reproduction; not a managed-cloud default; hashing-baseline is a bench-local lexical sanity floor, not a production backend).

mnemo as a golem:vector provider (v0.4.6)

mnemo v0.4.6 ships a vertical-slice WASM-component implementation of the golem:vector@1.0.0 WIT interface — three load-bearing functions (upsert-vector / search-vectors / delete-vectors) — split across two crates: crates/mnemo-golem-wit (the WASM component, compiled to wasm32-wasip2 via cargo component build) and crates/mnemo-golem-host (the Rust host that owns an Arc<MnemoEngine> and supplies the WIT host imports). The two-crate split is forced by mnemo-core's C++ deps (DuckDB + USearch) which cannot compile to WASM — see docs/research/golem-vector-wit-provider.md for the layering rationale, the per-function gap list (27 of 30 deferred to v0.5.x), and the wasmtime-component-loader wiring step explicitly deferred. The vertical-slice integration is functionally complete as a Rust trait surface today (MnemoGolemProvider + MnemoGolemHost) with 5 integration tests + an end-to-end example showing REMEMBER → RECALL → DELETE through a real MnemoEngine.

mnemo and the MCP 2026 Roadmap

The MCP 2026 Roadmap (published 2026-03-09 by lead maintainer David Soria Parra) reorganises the protocol's direction around four priority areas: Transport Evolution and Scalability, Agent Communication, Governance Maturation, and Enterprise Readiness. mnemo's existing surfaces — operator-held HMAC keystore, AES-256-GCM at-rest content encryption, dual DuckDB / PostgreSQL backends, and the mnemo-compliance crate — sit under the Enterprise Readiness priority area as an attestable memory layer regulated-workflow buyers can defend today.

This is a spec-context anchor, not a compliance claim. The roadmap's Transport Evolution work (stateless Streamable HTTP + .well-known server discovery) is upstream of mnemo and tracked via the rmcp = "1.3" workspace dep — mnemo follows rmcp's SEP implementation as it lands rather than racing the spec. See docs/src/integrations/mcp-server.md §"MCP 2026 Roadmap alignment" for the four-priority-area mapping table.

SDKs

Python

pip install mnemo-db

Why mnemo-db and not mnemo? A 2021 notebook project (last release 2021-07-06, unrelated) holds the unqualified mnemo name on PyPI. Our distribution publishes as mnemo-db; the import path stays from mnemo import … so existing code is unaffected.

from mnemo import MnemoClient

client = MnemoClient(db_path="agent.mnemo.db")
result = client.remember("The user prefers dark mode", tags=["preference"])
memories = client.recall("user preferences", limit=5)
client.forget([result["id"]])

# Mem0-compatible aliases also available:
# client.add(), client.search(), client.delete()

Framework Integrations

Mnemo provides native integration modules for 15 agent frameworks:

FrameworkIntegration ClassConnection
OpenAI Agents SDKMnemoAgentMemoryMCP stdio
LangGraphMnemoLangGraphToolsMCP stdio
CrewAIASMDMemoryDirect PyO3
Google ADKMnemoADKToolsetMCP stdio
AgnoMnemoAgnoToolsMCP stdio
Pydantic AIMnemoPydanticToolsetMCP stdio
AutoGenMnemoAutoGenWorkbenchMCP stdio
SmolagentsMnemoSmolagentsToolsMCP stdio
Strands AgentsMnemoStrandsClientMCP stdio
Semantic KernelMnemoSKPluginMCP stdio
Llama Stackregister_mnemo_toolgroupREST API
DSPycreate_mnemo_toolsDirect PyO3
CAMEL AIcreate_mnemo_camel_toolsDirect PyO3
Mem0 (compat)Mem0CompatDirect PyO3
LangGraph CheckpointerASMDCheckpointerDirect PyO3

All integrations are auto-imported via from mnemo import <ClassName> — dependencies fail gracefully if not installed.

Memory-tool servers and shared-memory adapters (v0.3.4 → v0.4.1)

SurfaceClassWhat it does
Anthropic memory tool memory_20250818MnemoMemoryToolServerClient-side handler for the 6-op view/create/str_replace/insert/delete/rename surface — every "file" lands as a Mnemo memory with hash-chain + ACL coverage. pip install 'mnemo-db[anthropic-memory-tool]'.
Letta Conversations-style shared memoryMnemoLettaSharedMultiple agents sharing a single audit-replayable memory stream. attach/detach/read/write/list_participants over Mnemo memories tagged conversation:<id> + participant:<agent_id>.
Cloudflare R2 workspaceCloudflareR2WorkspaceDrop-in R2 backend for MnemoSnapshotStore — same signed-manifest contract as the AWS S3 path; pip install 'mnemo-db[openai-sandbox-r2]'.
Letta-protocol-compat REST surface (mnemo-letta crate)mnemo_letta::router(engine)POST /v1/agents, POST /v1/agents/{id}/messages, GET /v1/agents/{id}/memory — drop in front of any MnemoEngine so a Letta-Code-shaped benchmark or notebook can talk to Mnemo without code changes. New in v0.4.0-rc3 (B5).
AMP / memorywire wire format (mnemo-amp crate)mnemo_amp::MnemoAmpStore + AmpRouterAMP-conformant MemoryStore surface: 5 ops (remember/recall/forget/merge/expire) × 4 memory types over a JSON-Schema 2020-12 envelope. merge/expire are thin compositions over the real primitives (no fictitious engine method); a fan-out router fuses multi-adapter recall with RRF; an optional HITL diff-and-approve hook gates long-term writes and records approvals in the hash-chained audit log. Conformance: recall@5 + RRF-holds-under-rank-0-injection vs max-fusion. New in v0.4.13.
Mannsetu DPDPA consent manager (mnemo-compliance crate)MannsetuConsentSource + ConsentTokenGuardDPB-registered consent-manager binding plus a per-write guard with expiry / scope / revocation checks. Refuses any remember whose consent token is missing, expired, wrong-scope, or revoked. New in v0.4.0-rc3 (B4).
DPDPA "data passport" PDFmnemo.dpdpa_passport.build_passport_pdfOne-page PDF showing every personal data point Mnemo holds for a subject, suitable for Section 11 / 12 access requests. Hand-rolled PDF — zero third-party deps, byte-for-byte reproducible. New in v0.4.0-rc3 (Q3).
Provenance SDKmnemo.provenance.verify_read_provenancePure-Python verifier for the HMAC-SHA256 receipts that Mnemo returns alongside recall(..., with_provenance=True). Auditors verify offline without compiling Rust. New in v0.4.0-rc3 (Q1).
Claude Code installerpython -m mnemo install claude-code [--hardened <manifest>]Idempotently registers Mnemo as an MCP server in ~/.claude.json. The --hardened flag switches the registered launcher to the v0.4.0-rc3 hardened mode. New in v0.4.0-rc3 (Q2).
Anthropic CMA-Memory compat shim (mnemo-cma crate)CmaTreeRoot + import_cma_tree + audit_bridgeDrop-in for the Anthropic Context-Managed Agent Memory beta announced 2026-04-23. Mounts an existing CMA .memory/ tree, mirrors writes through to mnemo's HMAC chain, and exports back byte-identical so users can leave cleanly. New in v0.4.1 (P0-2).
Agent behavioural-baseline exporter (mnemo-baseline crate)AgentBaseline + JsonExporter (OTel + OCSF)Per-agent rolling profile (recall/write rates, namespace fanout, tool mix, HMAC continuity) emitted to OpenTelemetry semconv 1.31 + OCSF 1.4 Application-Activity envelopes with z-score+EWMA drift detection. Anti-leak invariant: emitted payloads never carry memory contents. Plugs into the agentic-SOC telemetry gap RSAC 2026 flagged. New in v0.4.1 (P0-3).
1M-context recall budget planner (mnemo-core::budget)ContextBudget::for_model + plan_recallFirst OSS memory store with an explicit per-model ContextBudget → RecallPlan planner. Per-model table covers deepseek-v4-1m, claude-3.7-sonnet-1m, gpt-5.1-400k, gemini-2.5-pro-2m plus their smaller siblings. Typed FallbackStrategy (TruncateOldest / SummarizeOldestK / DropDuplicates / None). Property test: never overflows total context. New in v0.4.1 (P1-4).
Project-Deal counterparty discovery + reputation (mnemo-deal::discovery + ::reputation)AgentAdvertisement + compute_reputation/.well-known/mnemo-deal-agent.json advertisement (Ed25519-keyed, capability-tagged) plus an advisory reputation score with 90-day half-life decay and per-dispute 10% penalty. mnemo becomes not just the deal ledger but the directory of the agent-deal substrate. Advisory only — see docs/deal-reputation-threats.md. New in v0.4.1 (P1-5).

TypeScript

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

const client = new MnemoClient({ dbPath: "agent.mnemo.db" });
await client.connect();

const { id } = await client.remember({ content: "User prefers dark mode" });
const { memories } = await client.recall({ query: "user preferences" });
await client.share({ memory_id: id, target_agent_id: "auditor-agent" });

await client.close();

Go

import "github.com/sattyamjjain/mnemo/sdks/go"

client, err := mnemo.NewClient(mnemo.ClientOptions{DbPath: "agent.mnemo.db"})
defer client.Close()

result, _ := client.Remember(mnemo.RememberInput{Content: "User prefers dark mode"})
memories, _ := client.Recall(mnemo.RecallInput{Query: "user preferences"})
_, _ = client.Share(mnemo.ShareInput{MemoryID: result.ID, TargetAgentID: "auditor-agent"})

Storage Backends

BackendBest For
DuckDB (default)Single-agent, embedded, zero-config
PostgreSQL + pgvectorMulti-agent, distributed, production

Key Features

  • Hybrid retrieval — Reciprocal Rank Fusion combining semantic vectors (USearch/pgvector), BM25 keywords (Tantivy), knowledge graph signals, and recency scoring with configurable weights
  • Bitemporal graph layer (mnemo-graph) — Graphiti-inspired temporal edges with valid_from / valid_to (fact validity) plus recorded_at (system clock). graph_expand(seed, depth, as_of) walks the graph at any point in time without losing later corrections. New in v0.4.0-rc1.
  • AES-256-GCM encryption — at-rest content encryption via MNEMO_ENCRYPTION_KEY
  • Hash chain integrity — SHA-256 content hashes with chain linking and verify tool
  • Memory poisoning detection — anomaly scoring with prompt injection pattern detection; quarantine for flagged content
  • Cognitive forgetting — five strategies: soft delete, hard delete, decay, consolidation, archive
  • Feedback-driven consolidation trigger — opt-in ConsolidationPolicy::MaturityDriven gates run_consolidation on a per-cluster maturity score (recency × hit-success × edge-degree × redundancy) instead of firing on a fixed schedule. Inherited by forget and checkpoint automatically across MCP / REST / gRPC / pgwire; the default FixedSize policy preserves the v0.4.x behaviour byte-for-byte. New in v0.4.10.
  • Branching and replay — checkpoint, branch, merge, and replay agent memory timelines
  • Point-in-time queries — recall memories as they existed at any timestamp with as_of
  • Causal debugging — trace event causality chains up/down with type filtering
  • RBAC + delegation — ACL-based permissions with scoped, depth-limited transitive delegation
  • Permission-safe ANN — iterative oversampling with post-filtering for ACL compliance
  • ONNX local embeddings — run embeddings locally without API calls via MNEMO_ONNX_MODEL_PATH
  • S3 cold storage — archive old memories to S3-compatible storage (feature-gated)
  • LRU cache — in-memory caching layer for frequently accessed memories
  • Scale-to-zero — auto-shutdown after configurable idle timeout with checkpoint-on-shutdown
  • OTLP observability — ingest OpenTelemetry GenAI spans as agent events
  • Append-only audit log — immutable event log with database-enforced triggers (PostgreSQL)
  • GEM trajectory-correctness audit — mnemo-compliance::trajectory_audit replays the hash-chained event log and reports four trajectory-level signals: (a) unregulated-growth (active-bank vs ceiling), (b) missing-semantic-revision (facts superseded but never revised), (c) capacity-driven-forgetting (deletes outside the 5 named strategies), (d) read-only-retrieval (scopes that only RECALL). Surfaced via mnemo.trajectory_audit (MCP), POST /v1/compliance/trajectory_audit (REST), and the TrajectoryAudit gRPC RPC — same (agent_id, thread_id) shape as mnemo.verify, on the orthogonal trajectory axis.
  • MemFail per-operation fault-isolation suite — mnemo_core::eval::memfail decomposes each end-to-end recall into the three operation seams mnemo exposes (remember = store, run_consolidation = summarize, recall = retrieve) and ships three adversarial probe sets plus a canonical stale-context fixture that attributes a stale-recall failure to retrieve when store + summarize check out. Designed for cargo test and as a reusable library for downstream eval harnesses. New in v0.4.11.
  • Evidence-weighted conflict resolution — resolve multi-agent conflicts using source reliability scoring
  • Memory-provenance signing on reads — every recall(..., with_provenance=True) returns an HMAC-SHA256 receipt binding the cited records to a server-side key; supports key rotation. Verify offline from Python via mnemo.provenance.verify_read_provenance. New in v0.4.0-rc3.
  • Hardened MCP launcher — mnemo mcp-server --manifest <path> runs a safe-spawn gauntlet (refuse inherited secrets, refuse --config argv injection, refuse untrusted parents) BEFORE engine state is constructed. Direct response to the OX-MCP "exfiltrate-then-act" disclosure (2026-04-24). All privileged knobs come from a chmod-restricted TOML manifest. New in v0.4.0-rc3.
  • DPDPA consent-token-per-write — Mannsetu adapter + ConsentTokenGuard (expiry / scope / revocation) refuses every remember that is not authorized by a fresh consent token. Per-subject "data passport" PDF for Section 11 / 12 access requests. New in v0.4.0-rc3.
  • MCP tool-catalog attestation — mnemo mcp-server pins the advertised MCP tool list, refuses to start when the catalog gains an unauthorized tool or any tool's inputSchema mutates, and emits MNEMO_MCP_TOOL_DRIFT audit rows. Direct response to arXiv 2604.20994 (function-hijacking via tool-list poisoning). New in v0.4.0.
  • Cloudflare Mesh runtime adapter — SPIFFE-style MeshIdentity + per-namespace MemOp ACL + MeshAuditEnvelope chained into the existing HMAC ledger. First OSS embedded memory DB to speak Cloudflare Mesh attestation natively. New in v0.4.0.
  • Code-mode WIT recall — mnemo:memory@0.4 WIT world plus a wasmtime-friendly host runner. Agents call recall as a sandboxed WASM function instead of a JSON tool envelope, dropping per-turn token cost ~96% on 200-turn LongMemEval_S samples. New in v0.4.0.
  • Decay-curve score lane — DecayLane (Ebbinghaus + reinforcement) fuses with vector + BM25 + recency in the default recall path. letta_mode flag bypasses it for parity with Letta's published numbers. New in v0.4.0.
  • Agent-Deal ledger — mnemo-deal crate ships a chained-HMAC DealEnvelope log with verify_chain → DisputeReport. v0.4.1 adds advertisement (/.well-known/mnemo-deal-agent.json) + advisory reputation (90-day half-life, per-dispute 10% penalty).
  • Markdown+Git working-set adapter — mnemo-md-sync parses YAML-style frontmatter (mnemo_id, tags, expires_at) and provides MdSyncSpec + SyncFlushPolicy (PreferEngine / PreferDisk / NewerWins). New in v0.4.0.
  • Anthropic CMA-Memory compat shim — mnemo-cma crate mounts, mirrors, and exports the Anthropic CMA-Memory beta filesystem (announced 2026-04-23). Every CMA write is bridged into the mnemo HMAC chain via CmaSource::CmaBeta markers. New in v0.4.1.
  • Agent behavioural-baseline exporter — mnemo-baseline crate emits per-agent profiles in OpenTelemetry semconv 1.31 + OCSF 1.4 Application-Activity formats with z-score+EWMA drift detection; anti-leak regex test ensures payloads never carry memory contents. Plugs into the RSAC 2026 SOC telemetry gap. New in v0.4.1.
  • 1M-context recall budget planner — mnemo-core::budget adds ContextBudget::for_model + plan_recall covering deepseek-v4-1m, claude-3.7-sonnet-1m, gpt-5.1-400k, gemini-2.5-pro-2m; typed FallbackStrategy; property test asserts no model overflows. New in v0.4.1.
  • mnemo doctor + Grafana dashboard — typed DoctorReport + DoctorFix recommendations and a committed dashboards/mnemo-grafana.json (schemaVersion 39) covering recall p50/p99, tool-catalog drift, HMAC continuity, code-mode token reduction. New in v0.4.1.
  • MCP role-aware tool filter — manifest [role_filter] block with caller_roles, default = "allow_all" | "deny_all", per-tool allow / deny maps (deny wins), and an McpRoleDenied audit row on every blocked call. Aligned with the 2025-11-25 MCP authorization spec. Omitting the block keeps pre-v0.4.2 behaviour byte-for-byte. New in v0.4.2.

Memory curation interop (Dreams, Routines, and substrate primitives)

Anthropic's Dreams Research Preview (surfaced 2026-05-06 at Code w/ Claude SF) is a managed-agent feature that "lets Claude reflect on past sessions to curate an agent's memory and surface new insights." Its companion Routines doc describes the long-horizon agents that consume curated memory. mnemo's REMEMBER / RECALL / FORGET / SHARE primitives, envelope provenance, and AES-256-GCM at-rest encryption are the substrate any such curator reads from and writes through — Dreams owns what to curate, mnemo owns how to durably store with audit trail. The two surfaces are complementary, not substitute.

Honest framing: the Dreams API itself is a Research Preview behind a Request-access form, and mnemo does NOT today ship an Anthropic-API adapter. Today's anchor is substrate-level interop documentation, not integration. A mnemo-dreams adapter crate is plausible if/when the API exits Research Preview, but is explicitly NOT in scope for v0.4.x. See docs/comparisons/anthropic-dreams.md for the curator-action ↔ mnemo-primitive layering table.

Why mnemo when Cloudflare Agent Memory exists?

Cloudflare announced Agent Memory GA during Agents Week (2026-04-30), followed by Workers AI inference, Email Service beta, and an Agents SDK preview. It is the closest hosted competitor to mnemo.

mnemo is an embedded, cryptographically-audited, replayable memory the regulator can inspect offline. Cloudflare optimises recall throughput on the edge runtime; mnemo optimises a memory whose every write is HMAC-chained, every read is provenance-signed, and whose storage layer survives outside any cloud's audit boundary.

Honest concession: on per-recall p50 against the Workers KV+Vectorize backend, edge-recall throughput likely favours Cloudflare. mnemo's axis is provenance, chain replay, point-in-time as_of, evidence- weighted conflict resolution, DPDPA / GDPR subject erasure with audit preservation, and the v0.4.2 MCP role-aware tool filter — surfaces that matter when an auditor or regulator must reconstruct exactly what an agent saw and decided, three months later, without depending on a cloud account staying live.

The full bench harness against Cloudflare Agent Memory ships in v0.4.3 as a mnemo-bench-cf crate. Until then, docs/comparisons/cloudflare-agent-memory.md documents the differentiation scenario list with empty-bench placeholders so the comparison's contract is explicit before the numbers land.

Retrieval-strategy framing matters here too: arXiv 2605.15184 (Sen et al., May 2026) measured BM25 keyword retrieval outperforming pure vector retrieval on its experiment-1 corpus inside an agent harness. mnemo's documented default — hybrid RRF over BM25 + vector

  • graph + recency — is already hedged against the vector-first default the paper questioned. v0.4.4 adds a typed RetrievalMode::HarnessAware { harness, format } variant that lets the response envelope be reshaped per agent harness (Claude Code, Codex, Gemini CLI, Chronos, generic) without changing which records the substrate retrieves. See docs/research/grep-vs-vector-2605.15184.md for the composition anchor + the explicit non-overclaim disclaimer.

Outcome diffing — reconstructing the artifact's full provenance from append-only events — is the third trust wall in production agent systems (alongside aligned-by-training intent and policy-mediated action). The DELEGATE-52 delegation-corruption result (arXiv 2604.15597, surfaced on Hacker News 2026-05-09) puts a 25% baseline on the corruption rate this layer needs to detect. mnemo's append-only event log + snapshot substrate is the layer that lets a downstream auditor reconstruct any artifact's full plan / input / trace / output tetrad and diff against what the primary agent's plan asked for — see docs/research/delegate52-2604.15597.md for the operator recipe and the explicit non-overlap callout.

Project Think — loop vs. ledger

Cloudflare extended this story on 2026-05-04 with Project Think, a runtime story for AI agents built on Workers

  • DO Facets — the durable agentic loop itself. Project Think is upstream of mnemo's surface: it owns where the agent runs and how the loop survives a Worker restart. mnemo owns whether the writes that loop emits are cryptographically chained, replayable months later, and inspectable without a Cloudflare account.

These are complementary, not substitute, surfaces. An operator can run their durable loop on Project Think + DO Facets and chain every memory write into mnemo's HMAC ledger; the bench crate that compares Cloudflare Agent Memory vs mnemo as a memory store does not redo itself for Project Think as a runtime vs mnemo as a memory ledger — the latter is a layering question, not a benchmark. See docs/comparisons/cloudflare-project-think.md for the full layering table and where each side wins.

Examples

The examples/ directory contains working integration examples for all major agent frameworks:

ExampleFrameworkLanguage
openai_agents_example.pyOpenAI Agents SDKPython
langgraph_mcp_example.pyLangGraph + MCPPython
crewai_mcp_example.pyCrewAI + MCPPython
google_adk_example.pyGoogle ADKPython
agno_example.pyAgnoPython
pydantic_ai_example.pyPydantic AIPython
autogen_example.pyAutoGenPython
smolagents_example.pyHuggingFace SmolagentsPython
strands_agents_example.pyAWS Strands AgentsPython
semantic_kernel_example.pyMicrosoft Semantic KernelPython
llama_stack_example.pyMeta Llama StackPython
dspy_example.pyDSPyPython
camel_ai_example.pyCAMEL AIPython
browser_use_example.pyBrowser UsePython
basic_memory.pyDirect PyO3Python
mastra_example.tsMastraTypeScript
vercel_ai_sdk_example.tsVercel AI SDKTypeScript

CLI Options

mnemo [OPTIONS] [COMMAND]

Options:
  --db-path <PATH>              Database file path [default: mnemo.db] [env: MNEMO_DB_PATH]
  --openai-api-key <KEY>        OpenAI API key [env: OPENAI_API_KEY]
  --embedding-model <MODEL>     Embedding model [default: text-embedding-3-small] [env: MNEMO_EMBEDDING_MODEL]
  --dimensions <DIM>            Embedding dimensions [default: 1536] [env: MNEMO_DIMENSIONS]
  --agent-id <ID>               Default agent ID [default: default] [env: MNEMO_AGENT_ID]
  --org-id <ID>                 Organization ID [env: MNEMO_ORG_ID]
  --onnx-model-path <PATH>      ONNX embedding model path (local inference) [env: MNEMO_ONNX_MODEL_PATH]
  --rest-port <PORT>            Enable REST API on this port [env: MNEMO_REST_PORT]
  --postgres-url <URL>          Use PostgreSQL backend [env: MNEMO_POSTGRES_URL]
  --encryption-key <HEX>        AES-256-GCM encryption key (64 hex chars) [env: MNEMO_ENCRYPTION_KEY]
  --idle-timeout-seconds <SECS> Auto-shutdown after idle period (0 = disabled) [default: 0] [env: MNEMO_IDLE_TIMEOUT]

Commands:
  baseline    Train the per-agent embedding-space baseline used by the z-score
              outlier detector (v0.3.3, Task A).
  mcp-server  Start the MCP STDIO server in hardened mode using a TOML manifest
              (v0.4.0-rc3, Task B2). Refuses inherited secrets / argv injection /
              untrusted parents BEFORE engine state is constructed. Privileged
              knobs come from the manifest; key material reaches the binary via
              a chmod-restricted keystore file. See
              `examples/mcp-server/manifest.toml` for an annotated reference.
  eval        Replay a JSONL dataset of {query, expected} rows against an
              in-memory engine and emit a per-row latency / top-k JSONL report
              (v0.4.0-rc3, Task B6). Defaults to the bundled LongMemEval_M
              sample under `crates/mnemo-core/benches/data/longmemeval_m.jsonl`.
              Pass `--with-provenance` + `--provenance-key-hex <hex>` to also
              measure the HMAC-receipt overhead.

Architecture

┌──────────┐  ┌───────────┐  ┌──────────┐  ┌──────────┐
│MCP Client│  │REST Client│  │  gRPC    │  │  psql    │
│ (stdio)  │  │  (HTTP)   │  │          │  │ (pgwire) │
└────┬─────┘  └─────┬─────┘  └────┬─────┘  └────┬─────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
┌────────────────────────────────────────────────────────┐
│                    MnemoEngine                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ Remember │ │  Recall  │ │ Forget/  │ │Checkpoint│ │
│  │ Pipeline │ │ Pipeline │ │Share/... │ │/Branch/  │ │
│  │          │ │  (RRF)   │ │          │ │Merge     │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│       └─────────────┴────────────┴────────────┘       │
│                         │                              │
│  ┌──────────────────────▼──────────────────────────┐  │
│  │          StorageBackend (trait)                   │  │
│  │   ┌──────────┐              ┌─────────────┐     │  │
│  │   │  DuckDB   │              │  PostgreSQL  │     │  │
│  │   └──────────┘              └─────────────┘     │  │
│  └──────────────────────────────────────────────────┘  │
│                                                         │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │VectorIndex │ │FullText  │ │Embeddings│ │Encrypt │ │
│  │USearch/PG  │ │ Tantivy  │ │OpenAI/   │ │AES-256 │ │
│  │            │ │          │ │ONNX/Noop │ │GCM     │ │
│  └────────────┘ └──────────┘ └──────────┘ └────────┘ │
└─────────────────────────────────────────────────────────┘

Deployment

Docker

docker build -t mnemo .
docker run -p 8080:8080 -e OPENAI_API_KEY=sk-... mnemo --rest-port 8080

Kubernetes (Helm)

helm install mnemo deploy/helm/mnemo \
  --set env.OPENAI_API_KEY=sk-... \
  --set env.MNEMO_REST_PORT=8080

The Helm chart includes: Deployment, Service, ConfigMap, Secret, PVC, HPA, and Ingress templates.

Cloudflare Workers deploy template (design anchor)

Status: design anchor, not a shipped template. The deploy/cloudflare/ scaffold is parked for v0.4.3 follow-up. This section documents the contract that scaffold will produce against — see docs/src/integrations/cloudflare-workers-deploy.md for the full design note.

Cloudflare Durable Object Facets (open beta, 2026-04-30) lets a single Worker dynamically load Durable Object classes, each with its own SQLite database. That's the per-tenant embedded-substrate shape mnemo already runs on DuckDB-per-agent — making Workers the natural managed runtime for an mnemo MCP server when you don't want to operate the box yourself.

The intended layout (single Worker, one DO Facet per tenant, mnemo as the MCP-over-HTTP entrypoint):

# wrangler.toml (sketch — not yet shipped under deploy/cloudflare/)
name = "mnemo-mcp-worker"
main = "dist/worker.js"

[[durable_objects.bindings]]
name = "MNEMO_TENANT"
class_name = "MnemoTenantFacet"
# DO Facet — each instance gets its own SQLite-backed storage
# matching mnemo's embedded DuckDB-per-agent contract.

What stays Rust-native vs. crosses the JS boundary, the file-format compatibility story (mnemo writes DuckDB; the Workers Facet exposes SQLite — the bench crate quantifies the gap), and which mnemo surfaces require the operator-held HMAC keystore vs. which can run inside the Worker — all in docs/src/integrations/cloudflare-workers-deploy.md. The bench numbers land with the v0.4.3 mnemo-bench-cf crate.

Development

# Run all tests (376 tests at v0.4.5: unit + integration + MCP + pgwire + REST + admin + gRPC + doctests)
cargo test --all

# Run tests for a specific crate
cargo test -p mnemo-core
cargo test -p mnemo-mcp

# Run integration tests only
cargo test -p mnemo-core --test integration_test

# Lint and format
cargo clippy --all-targets --all-features
cargo fmt --all

# Run benchmarks
cargo bench -p mnemo-core

# Build with optional features
cargo build -p mnemo-core --features onnx     # ONNX local embeddings
cargo build -p mnemo-core --features s3        # S3 cold storage
cargo build -p mnemo-cli --features postgres   # PostgreSQL backend

# Build Python SDK (requires maturin, NOT cargo build)
cd python && maturin develop

# TypeScript SDK
cd sdks/typescript && npm install && npm test

# Go SDK
cd sdks/go && go test ./...

Benchmarks

We run LoCoMo-MC10 and LongMemEval on every release. The canonical results page is docs/benchmarks/2026-04-25-mnemo-v0.3.4.md — it carries reference rows for Hindsight (91.4% LongMemEval / 89.61% LoCoMo, source) and Letta-Filesystem (74.0%) plus the four mnemo retrieval strategies side-by-side. The mnemo rows populate from the first authenticated nightly run — ungated CI forks read the empty rows and the workflow's first-run exception keeps the regression gate honest. Earlier reports under docs/benchmarks/ carry the v0.3.0 / v0.3.1 floor numbers from before the v0.3.3 Tantivy-default + LLM-judge fixes.

Phase-aware cost attribution + agent-memory characterization scorecard (bench-only). Anchored on arXiv:2606.06448 (Agent Memory: Characterization and System Implications of Stateful Long-Horizon Workloads). The new phase_cost bin splits every benchmark scenario's cost into the paper's three phases — construction (remember-path: embedding calls, prefill tokens, write latency), retrieval (recall-path: ANN + BM25 + graph + RRF latency, query tokens), and generation (downstream, estimated — mnemo does not generate) — and emits a per-phase table (tokens, wall-ms, $-estimate at configurable per-1K rates) per scenario. The --scorecard-2606-06448 flag instead renders mnemo's PASS / PARTIAL / FAIL position against the paper's 10 §5 recommendations (quoted verbatim) as a 10-row table; mnemo currently scores 5 PASS · 5 PARTIAL · 0 FAIL (PASS on the latency / feasibility / compaction recommendations R5/R7/R8/R9/R10; PARTIAL on the operator-side lifecycle-policy ones R1–R4/R6). Run via cargo run --release --bin phase_cost -p mnemo-locomo-bench (add -- --scorecard-2606-06448 for the scorecard). This is bench-only — no access protocol (MCP / REST / gRPC / pgwire) and no retrieval default is touched; token counts are ceil(chars/4) estimates and the generation phase is never an LLM call. Sample per-phase table (default rates, 64 records / 16 queries, NoopEmbedding):

### Scenario `long-context` (64 records, 16 queries)

| Phase | Tokens | Wall-ms | $-estimate |
|---|---:|---:|---:|
| construction | 15360 | 1551.42 | 0.001306 |
| retrieval    |    96 |  157.76 | 0.000002 |
| generation   | 13792 |     n/a | 0.003912 |
| **total**    | 29248 |       — | 0.005220 |

Construction and generation dominate; retrieval is near-free — exactly the lifecycle-cost picture the paper insists operators measure (Recommendation 2). See bench/locomo/src/phase_cost.rs for the cost model + the full "what this is NOT" block.

Embedding-backend selection bench + SLA-aware recommender (v0.4.9). Anchored on arXiv:2605.23618 (GE2 vs local encoders — quality + latency). New crate bench/embeddings measures every configured backend (Noop + bench-local hashing baseline always; OpenAI when keyed; ONNX when configured + feature-gated) for nDCG@10, recall@10, p50/p95 embed latency, and throughput at batch 1/8/32 on a 50-doc / 10-query labeled fixture; the recommender picks the highest-nDCG backend whose p95 ≤ the SLO and reports the nDCG gap vs the best-quality backend. Run with mnemo bench embeddings --slo-ms <N> or cargo bench -p mnemo-embeddings-bench. See bench/embeddings/README.md for the full "what this bench is NOT" block.

First public LoCoMo number (v0.4.1, P0-1) — full report at docs/benchmarks/locomo-2026-04-28.md. mnemo joins the public LoCoMo board alongside MemMachine (84.87%, 2026-04-24) and Memori (81.95%, 2026-04-24); the harness ships at bench/locomo with a dual-judge variance gate (GPT-5.1 + Claude-3.7 Sonnet) and runs nightly via .github/workflows/locomo-nightly.yml. mnemo trades raw overall score for temporal-slice strength + ~96% per-turn token cost — see the report for the honest pitch.

Auto-Dreamer-shaped offline consolidation bench (v0.4.8). Added 2026-05-25 at bench/locomo/src/bin/auto_dreamer_consolidation.rs. Mirrors Auto-Dreamer's "smaller active bank, equal-or-better recall" axis against mnemo's existing run_decay_pass + run_consolidation path. Emits a Markdown report + a JSON summary (active_bank_ratio, recall_pre, recall_post) so the headline is citable. Defaults: 8 sessions × 25 facts × 5 trials. Run via cargo run --release --bin auto_dreamer_consolidation -p mnemo-locomo-bench. See bench/locomo/README.md for the full "what this bin is NOT" block.

LongMemEval_M provenance overhead bench (v0.4.0-rc3, B3). A self-contained 45-record synthesized dataset ships at crates/mnemo-core/benches/data/longmemeval_m.jsonl (override with MNEMO_LONGMEMEVAL_PATH=<path> for the published gated dataset). The longmemeval_bench criterion target runs two arms — recall_no_provenance and recall_with_provenance — so the per-recall HMAC-receipt overhead is measurable in CI:

cargo bench -p mnemo-core --bench longmemeval_bench

Documentation

  • mdBook: docs/ directory — run mdbook serve docs for local browsing
  • Compliance: SOC 2 controls mapping and HIPAA safeguards at docs/src/compliance/
  • REST API: docs/src/rest-api.md
  • Tool reference: docs/src/tools/ (one page per MCP tool)
  • Hardened MCP launcher: docs/src/integrations/mcp-server.md — manifest schema, threat model, systemd unit example
  • Time-travel debugger: examples/time-travel-debugger/index.html — vanilla-JS UI that diffs recall results between two as_of timestamps; serve any way you like (python3 -m http.server)
  • LoCoMo report: docs/benchmarks/locomo-2026-04-28.md — first public mnemo number alongside MemMachine + Memori with the honest temporal-slice + per-turn-token pitch
  • Grafana dashboard: dashboards/mnemo-grafana.json — schemaVersion 39, drop straight into Grafana 11.5; covers recall p50/p99, tool-catalog drift, HMAC continuity, code-mode token reduction, baseline anomalies
  • Benchmarks: docs/benchmarks/

License

Apache-2.0

Ver o original no GitHub

Bom para

Relacionados