Architecture

mnesio has one organizing idea: the event log is the single system of record, and everything else is a materialized view of it. Get that, and the rest of the system follows.

The event log (system of record)

Every write is an immutable, append-only Event on a fjall-backed log (FjallEventLog). Memories, evolutions, invalidations, link updates, outcomes, learning-curve points — all of it is events. The log is never mutated and never overwritten; a “change” is a new event that supersedes an old one.

Why this matters

Because the log is append-only and complete, every index is rebuildable by replaying it. That single property is what makes the frontier features possible: counterfactual replay (Phase 10), time-travel provenance (Phase 15), and KV cartridges as just-another-view (Phase 12).

Materialized views

A view is anything that folds the event tail into a queryable structure. Each implements the MaterializedView trait (apply(&entry)), so it can be driven off the live tail or rebuilt from scratch by replay:

Vector view

hnsw_rs ANN index over embeddings (mock 32-d for tests, fastembed 384-d for real). Adaptive over-fetch + soft-delete tombstones; multi-tenant partitioning available.

BM25 view

tantivy lexical index with stemming + stop-words and a 4-tier fallback (strict-AND → strict-OR → fuzzy-AND → fuzzy-OR) for typos and locale variants.

Graph view

Bi-temporal property graph on fjall — nodes, edges, time-travel queries, BFS/shortest-path with bounds. Source nodes render distinctly.

Procedural / KV / others

The procedural artifact store, KV cartridges, probe/causal/exchange state — all materialized views derived from the same log.

Hybrid retrieval

HybridRetriever fuses the vector and BM25 signals with Reciprocal Rank Fusion, down-weighting a mock vector signal so lexical results dominate when embeddings are stand-ins. Each Hit carries an explainable breakdown so you can see why it ranked where it did. A reranker stage and graph-proximity + recency/importance signals fold into the fusion.

The seams (swappable providers)

Every external dependency lives behind a trait, so providers are swappable without touching the core:

• LlmClient — the model (FakeLlmClient, OllamaLlmClient, …)
• Embedder — embeddings (MockEmbedder, FastEmbedEmbedder)
• EventLog — the log (FjallEventLog)
• MaterializedView — any index
• Retriever — retrieval strategy
• Cipher / Signer — crypto (chacha20poly1305 AEAD, ed25519)
• KvBackend — the KV tensor backend (fake, GPT-2, candle/Metal GPU)

Crate map

mnesio-core        types + traits, no I/O — the shared vocabulary
mnesio-store       fjall-backed event log + view plumbing
mnesio-index       hnsw_rs vector + tantivy BM25 + hybrid retriever
mnesio-evolve      A-MEM-style bounded evolution worker
mnesio-procedural  the procedural-memory compiler (the wedge)
mnesio-graph       bi-temporal property graph view
mnesio-extract     ingestion: extract + consolidate facts
mnesio-causal      counterfactual contribution scoring + GC
mnesio-probe       acceptance probes + falsification
mnesio-kv          gated KV cartridges (KV cache as a view)
mnesio-exchange    certified skill import/export
mnesio-dream       negative memory + offline consolidation
mnesio-provenance  time-travel snapshots + provenance chains
mnesio-mcp         MCP server (stdio JSON-RPC)
mnesio-py          pyo3 Python bindings
mnesio-bench       eval-as-product harness
mnesio-server      host process; HTTP API + dashboard

Start reading the source at mnesio-core — event.rs (system of record) and traits.rs (the seams) define everything else.

Next: the seven hard rules that the whole design defends.