Expand description
§Mnemo
Mnemo is an encrypted, single-file, portable agent-memory engine.
A whole memory store — vectors, content, metadata, and the multi-signal recall machinery an agent needs — lives in one file you can copy, back up, or hand to another process. The file is encrypted at rest with a two-tier key hierarchy: an Argon2id key-encryption key (KEK) derived from a passphrase wraps a random data-encryption key (DEK), and the DEK encrypts every page with AES-256-GCM.
§Quick start
use mnemo_engine::{Mnemo, MnemoConfig, Memory, MemoryType, RecallRequest};
let cfg = MnemoConfig { dimensions: 3, ..Default::default() };
let mut db = Mnemo::create("agent.mnemo", "correct horse battery", cfg)?;
db.remember(
Memory::new("the user prefers dark mode", MemoryType::Semantic, vec![0.1, 0.2, 0.9])
.with_agent("assistant-1")
.with_importance(0.8),
)?;
db.flush()?;
let hits = db.recall(&RecallRequest::new(vec![0.1, 0.2, 0.9]).top_k(5))?;
for h in hits {
println!("{:.3} {}", h.score, h.memory.content);
}§What is and is not built
This crate implements a real, tested core: the encrypted single-file
storage engine, the crypto layer, the agent-memory model, multi-signal
recall, an IVF+PQ approximate-nearest-neighbour index, a write-ahead log,
snapshot-based point-in-time recovery, a bounded LRU page cache, and the
Session conversation wrapper. Exact brute-force search remains
available as the ground-truth baseline; a built index makes
Mnemo::recall sub-linear. Each Mnemo::flush is one atomic,
WAL-committed transaction and a restorable snapshot — Mnemo::restore_to
rewinds the database to any past transaction. Python and TypeScript
language bindings are the one documented roadmap item — see the README.
Modules§
- delivery
- 13a (13.1): messages between agents. 13a (13.1b): the delivery states, in order.
- essence_
status - Status values the essence section supports (Phase 12.7b). More
kinds (tasks:
queued → active → ready → done | blocked; findings:open → accepted | deferred | rejected | needs-user → verified) ship with Phase 13 reusing the same status-record core; the transition tables for those are declared as constants in this crate but currently unused. - finding_
status - v0.18.0 (13a step 8b): review findings. v0.18.0: the finding statuses.
- guide
- GUIDE-1 (12.2): the guide for agents, compiled into the binary
(
docs/design/12.2-onboard.md, section 6). - keys
- 12.3: keys (
docs/design/12.3-keys.md). - mcp
- Hand-rolled Model Context Protocol (MCP) stdio server for MNemo.
- redact
- 12.2 step 4: redacting known secret shapes from text before it’s stored
(
docs/design/12.2-onboard.md, section 5). The hooks’ transcript ingest always runs it;mnemo thread ingest --redactturns it on for a direct call. - sidecar_
notes - 13a: the hooks’ small notes in a brain’s sidecar directory (the
per-session stamps): names start with
hook.and are 1 to 80 ofa-z0-9.-, so they never collide with the lock files. - stale_
after - 13a (13.5, 13.6): visibility and freshness. 13a (13.6): the per-kind freshness defaults, in seconds.
- task_
status - 13a (13.1): tasks. 13a (13.1): the task statuses.
Structs§
- Build
Info - Build-time cryptographic backend information.
- Cache
Budget - Per-namespace eviction budget.
cache_putenforces both caps: on insert, the LRU is evicted until both live-entry count and live byte total fit under the caps. - Cache
PutOpts - Options accepted by
Mnemo::cache_put. Defaults describe an untyped, never-expiring, non-cost-hinted entry. - Cache
Stats - Summary statistics for a namespace (or the whole cache).
- Cached
Value - A returned cache hit.
accessed_at/access_countare updated on the directory before this is constructed, so the values here reflect the post-touch state (mirroring the recall-time convention). - Cancel
Token - Cancels a shared-mode call that is waiting for the file’s lock, from
another thread: an iOS background activity’s expiry handler, say. The
call releases every lock it holds and returns
MnemoError::Cancelled. - Claim
- 13a (13.3): a live claim, as
Mnemo::claimslists it (no token). - Close
Error - The error from
Mnemo::try_close: the final flush failed, and the handle comes back with it, still open and still holding every write that wasn’t flushed. - Commit
Batch - Atomic write batch for
crate::Mnemo::commit_deltas(Phase 12.7c). The planner’s “one call that composes facts + essence + turns” shape: everything validates up front, then every write runs under a singleflush(). - Commit
Report - Result of
crate::Mnemo::commit_deltas(Phase 12.7c). - Compact
Report - Result of a
Mnemo::compact_filerun. - Embed
Cmd - Persistent-child-process adapter for a user-supplied embedder command. See the module docs for the protocol.
- Embedder
Identity - Describe an embedder’s observable identity. Used both in-memory on
an open [
Mnemo] handle and persisted atmetadata.embedderon the scaffold manifest so that reopening with a different embedder is caught atset_embeddertime instead of silently polluting the index. - Essence
Op - One essence op inside a
CommitBatch(Phase 12.7c). Validation (missing/extra fields per kind) runs up front incrate::Mnemo::commit_deltas— a single bad op aborts the whole batch before any write lands. - Exported
Turn - One turn of a thread’s archive in the ingest shape (Phase 12.7d),
as returned by
crate::Mnemo::thread_export_turnsand by Pythondb.thread_export, MCPthread_exportandmnemo thread export. - Filter
- Pre-scoring filter applied by
crate::Mnemo::recall(Phase 12.6). - Finding
- v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: one finding.
- Finding
Filter - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0: which findings
Mnemo::findingslists; each field left out matches every finding. - Finding
Spec - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0: a finding to add (
Mnemo::finding_add). - Index
Config - Tuning knobs for building and querying an [
IvfPqIndex]. - Index
Info - A read-only snapshot of an index’s shape, surfaced via
Mnemo::stats. - Ingest
Report - Result of one
crate::Mnemo::ingest_threadcall (Phase 12.7a). - KdfParams
- Argon2id cost parameters. Stored (unencrypted) in the file header so the KEK can be re-derived on open.
- Keyed
Memory - One keyed fact inside a
CommitBatch(Phase 12.7c). - Keyword
Index - An in-memory keyword index over a set of texts, with the tokenizer and
BM25 scoring (k1 1.2, b 0.75) of v9’s keyword recall, for tools that
search what they’ve already read, without the file open (
mnemo inspect). It needs no embedder and works on texts from any format. It uses tokenizer 2 (TOK-1), so a part of a dotted name matches. - Kind
Counts - 13a (ABOUT-COUNT): the live records by what they are.
- Memory
- A single memory entry.
- Memory
Patch - Patch body for
crate::Mnemo::update(Phase 12.1): every field is optional, and only theSome(...)fields overwrite the corresponding field on the target memory. All fields can be set independently. - Message
- 13a (13.1): one message between agents, as
Mnemo::inboxreturns it. - Mnemo
- An encrypted, single-file agent memory database.
- Mnemo
Config - Configuration for creating a new database.
- NewWork
- 13a (13.1b): what’s new for an agent since it was last shown
(
Mnemo::new_work), for the per-turn hook. - Presence
- 13a (13.3): one agent, as
Mnemo::wholists it. - Recall
Request - A retrieval request for
Mnemo::recall. - Recall
Response - Phase 12.8 budgeted-recall envelope returned by
Mnemo::recall_budgeted. Wraps theVec<RecallResult>the legacyMnemo::recallreturns so callers can tell whetherRecallRequest::max_bytescut anything. - Recall
Result - One scored result from
Mnemo::recall. - Reembed
Report - What
Mnemo::reembed_filedid (12.3 step 4, v0.15). - Score
Weights - Weights for the multi-signal recall score (scoring v2, shipped in v0.7.0).
- Semantic
Cache PutOpts - Options for
crate::Mnemo::cache_put_semantic. Same asCachePutOptsplus a requiredmodelstring — a hit from a different embedding model’s cache is a semantics bug, not a win, so the engine forces callers to declare the model and matches it on lookup. - Session
- A scoped conversation session over a
Mnemodatabase. - Shared
Mnemo - A brain opened in shared mode (12.4): see
Mnemo::open_shared. - Shared
Options - Options for a shared-mode handle (12.4).
- Snapshot
Info - A restorable point in a database’s history — see
Mnemo::snapshots. - Stale
- 13a (13.6): one stale record (
Mnemo::stale). - Stats
- Summary statistics for a database.
- Stats
Summary Mnemo::stats_summary: the cheap statistics, read from the catalog and the header (v0.12.2, RB-002.3).- Task
- 13a (13.1): one task.
- Task
Claim - 13a (13.1): the claim an owner holds after a
Mnemo::task_update(RB-012.1), so it always has the current token. - Task
Spec - 13a (13.1): a task to add (
Mnemo::task_add). - Task
Taken - 13a (13.1): a task
Mnemo::task_nexttook, with its claim’s token. - Thread
Turn - One turn fed into
crate::Mnemo::ingest_thread(Phase 12.7a). - Transcript
Options - How
read_transcript_withreads. - Turn
- One conversation turn, written to working memory by
Session::add_turn. - Ulid
- Re-export of
ulid::Ulid, the identifier type used for memories. A Ulid is a unique 128-bit lexicographically sortable identifier - Verify
Report - What
Mnemo::verify_reportchecked. - Visibility
Set - 13a (13.5, 13.6): visibility and freshness. 13a (13.5, 13.6): visibility and freshness. 13a (13.5, 13.6): visibility and freshness. 13a (13.5): which visibility levels a read shows. By default public and team; private only when asked.
Enums§
- Alive
- 13a (13.3): whether an agent’s process is running, by its presence lock.
- Cache
Flush Policy - Per-handle flush policy for cache writes. Memory writes ignore this
and always behave as
Strict. - Claim
Outcome - 13a (13.3): what
Mnemo::claimgot. - Claim
Status - 13a (13.3): what
renew,releaseandcheck_claimfound. - Essence
OpKind - Which op a
EssenceOpcarries. Mirrors the per-methodMnemo::essence_*surface so one batch can mix section + timeline edits in one call. - Essence
Scope - Scope selector for an essence item (Phase 12.7b). Thread-scoped
items belong to one
_mnemo.thread; project-scoped items are shared across every thread in the file. - Essence
Section - Which essence section an item belongs to.
- Filter
Term - One AND-ed condition applied to a candidate memory’s metadata during
filtered recall (Phase 12.6). Terms are combined conjunctively — a
memory passes the filter only if every term evaluates true against
its
metadatamap. SeeFilterfor the surface API. - KeyScope
- Scope selector for a keyed slot (Phase 12.1.1). A keyed
remember’s slot is always identified by(scope_owner, key):Private(agent_id)slots are per-agent,Sharedslots are per-file.history_in(key, scope)uses the same selector so the lookup matches the write exactly. - Keyword
Tokenizer - TOK-1: the state of a file’s keyword index, as
infoandverifyshow it. - Memory
Type - The four kinds of agent memory.
- Metric
- Distance/similarity metric for vector comparison.
- Mnemo
Error - All errors the Mnemo engine can produce.
- Recall
Mode - MOBILE-2d: how recall scores vectors, from
Mnemo::stats. - Role
- Who produced a conversation turn.
- Scope
- Visibility of a memory across agents sharing one
.mnemofile. - Secret
Kind - 12.3: what kind of secret a caller handed the engine. A passphrase is a person’s; a key is a uniformly random 256-bit value a machine made.
- Task
Lost - 13a (13.1): why a
Mnemo::task_updatechanged nothing. - Task
Outcome - 13a (13.1): what
Mnemo::task_updatedid. - Tool
Results - What a Claude Code transcript’s tool results keep (12.2 step 4).
- Transcript
Format - The supported transcript shapes for
read_transcript/mnemo thread ingest --format …. - Turn
Policy - What
crate::Mnemo::commit_deltasdoes with theturnscarried in the batch (Phase 12.7c). - Wake
- 13a (13.1b): what
Mnemo::wakedecided. - Write
Outcome - Outcome of a 12.1 write operation (
rememberwithkey, orupdate).
Constants§
- CALLER_
KEYS - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the reserved keys a caller may set on a write (visibility and
freshness), each checked by
check_caller_key. Every other_mnemo.*key stays the engine’s. - CLAIM_
LAPSE_ GRACE_ SECS - 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): how long a holder must be seen not alive, twice, before its claim lapses early.
- CLAIM_
TOPIC_ MAX - 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): a topic’s limit, in bytes (one line).
- CLAIM_
TTL_ DEFAULT - 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): a claim’s default lease (15 minutes).
- CLAIM_
TTL_ MAX - 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): a claim’s longest lease (24 hours).
- CLAIM_
TTL_ MIN - 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): claims and presence. 13a (13.3): a claim’s shortest lease.
- CONTINUATION_
TIMELINE_ ENTRIES - How many timeline entries from the predecessor thread the continuation render pulls in (Phase 12.7c). Small enough to keep the render under the default 6 KB budget, large enough to carry a handful of milestones.
- COORDINATION_
KINDS - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds. Each is an ordinary record in the shared
scope with the sentinel vector, never embedded, and never a hit in
recall, the keyword index, the ANN orabout: each is read through its own API (docs/design/13a-coordination.md, section 1). - DEFAULT_
BATCH_ MAX_ AGE - Default
max_ageforCacheFlushPolicy::Batched. - DEFAULT_
BATCH_ MAX_ DIRTY - Default
max_dirtyforCacheFlushPolicy::Batched. - DEFAULT_
EMBED_ TIMEOUT - Default per-request timeout. Set generously because a cold-start
sentence-transformerscall can genuinely take a few seconds the first time; configurable viaEmbedCmd::with_timeout(Rust API) or the--embed-timeoutCLI flag. - DEFAULT_
KEYWORD_ WEIGHT - FMT-9d: default weight ε of the normalised BM25 score in hybrid recall
(
relevance = similarity + ε · bm25 / max bm25). - DEFAULT_
MAX_ BYTES - Default per-namespace byte budget (values + directory overhead).
Once exceeded,
cache_putevicts LRU until the total falls back under the cap. - DEFAULT_
MAX_ ENTRIES - Default per-namespace entry-count budget. Once a namespace holds this
many live entries,
cache_putevicts the LRU entry before inserting. - DEFAULT_
SEMANTIC_ THRESHOLD - Default similarity threshold for
crate::Mnemo::cache_get_semantic. Lookups below this are treated as misses. Chosen conservatively to avoid false hits on subtly-different prompts; callers can override per-lookup. Model-dependent — text-embedding-ada-002 and BGE at this threshold rarely surface unrelated content, but if you’re working with a lossier embedder consider raising it. - DEFAULT_
TEXT_ KEYWORD_ WEIGHT - 12.3 step 4 (v0.15): default weight of the BM25 score when it comes from
a recall’s own text (hybrid by default, no keywords given). Lower than
DEFAULT_KEYWORD_WEIGHTbecause a question’s common words (“how”, “the”) match unrelated memories: on this project’s brain at 0.5 a memory with similarity 0.18 came second on “how releases are approved”; at 0.25 the right fact led all three DOGFOOD-0 questions with no such intruder (docs/design/12.3-retrieval.md, section 5). - DEFAULT_
TURN_ COMPRESS_ AFTER_ SECS - FMT-9e: by default a thread turn is written plain and compressed once
it’s a week old (by its
created_at), so a live session’s recent turns read at full speed and archived history is small. - DEFAULT_
VECTOR_ CACHE_ BUDGET - FMT-9b: default
Mnemo::set_vector_cache_budget: the fp16 vector column stays resident while it fits (100K × 384 dims is about 77 MB) and is read through the page cache above it. PLANNER-A, 2026-11-07. - ESSENCE_
DEFAULT_ RENDER_ BYTES - Default byte budget for
crate::Mnemo::essencerendering (Phase 12.7b). Matches the planner’s “max_bytes = 6144” spec, which sits comfortably below a 4K-token context window. - ESSENCE_
SECTION_ MAX_ BYTES - Maximum content length for a section item (Phase 12.7b). intent / conventions / decisions / state / open / next / lessons all share the same single-line cap. Items over this are rejected.
- ESSENCE_
TIMELINE_ MAX_ BYTES - Maximum content length for a timeline entry (Phase 12.7b). Entries over this are rejected, not truncated — the planner’s spec is explicit about this because truncation would lose the narrative, and splitting across records would lose ordering.
- ESSENCE_
TRANSITIONS - Essence transition table for Phase 12.7b. Only
open → resolvedis allowed. Timeline entries don’t use this (they’re append-only and have no status). - FINDING_
BODY_ MAX - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: a finding’s body, at most this many bytes.
- FINDING_
CATEGORIES - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: a finding’s categories.
- FINDING_
PRIORITIES - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: a finding’s priorities.
- FINDING_
TITLE_ MAX - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: a finding’s title, at most this many bytes (one line).
- FINDING_
TRANSITIONS - Finding transition table (v0.18.0,
Mnemo::finding_triageandMnemo::finding_verify):open → {accepted | deferred | rejected | needs-user} → verified, the user’s way out ofneeds-user(toaccepted,deferredorrejected), and a deferral taken up later (deferred → accepted). - HOP_CAP
- 13a (13.1b): the wake-up guardrails. 13a (13.1b): the wake-up guardrails. 13a (13.1b): the wake-up guardrails. 13a (13.1b): an explicit reply whose hop count passes this wakes nobody.
- INDEX_
PERSIST_ EVERY_ CHANGES - PERF-1: …or once this many vectors were added, changed or removed since the last persist. Records written after the persisted index are re-assigned when the index is next loaded, so this bounds that work.
- INDEX_
PERSIST_ EVERY_ COMMITS - PERF-1: the ANN index is derived data, so
flushpersists it only every this many commits that changed it (or seeINDEX_PERSIST_EVERY_CHANGES,Mnemo::flush_index,Mnemo::close). Between persists, only the catalog is rewritten. - MESSAGE_
ACKED - 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a: a message’s status once acked.
- MESSAGE_
ACKED_ KEEP_ SECS - 13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a: acked messages older than this are dropped by
compactandprune_messages(30 days). - MESSAGE_
BODY_ MAX - 13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a: a message body’s limit, in bytes; a bigger one belongs in a fact,
named in
refs. - MESSAGE_
PAIR_ CARRY_ SECS - 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a: a new message between the same two parties within this many seconds carries their last hop count on (the pair carry).
- MESSAGE_
SUBJECT_ MAX - 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a: a subject’s limit, in bytes (one line).
- MESSAGE_
UNREAD - 13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a: a message’s status:
unreaduntil acked. - MNEMO_
META_ ACKED_ AT - 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a: when a message was acked, in unix seconds (for pruning).
- MNEMO_
META_ AFTER - 13a (13.1): tasks. 13a (13.1): tasks. 13a (13.1): tasks. 13a (13.1): the slugs of the tasks a task waits for.
- MNEMO_
META_ AS_ OF - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a (13.6): when the content was true, in unix seconds. A caller may
set it; absent, it’s the record’s
created_at(or_mnemo.updated_at). - MNEMO_
META_ AUTHOR - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: who wrote a record, the writing handle’s author
(
crate::Mnemo::set_author, fromMNEMO_AGENTin the CLI, the MCP server and the hooks). Stamped by the engine on new records, never set by a caller, and unproven until 13.4 signs it. - MNEMO_
META_ BATCH - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0: a finding’s batch, its id’s prefix (
RB-014). - MNEMO_
META_ CATEGORY - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0: a finding’s category (
FINDING_CATEGORIES). - MNEMO_
META_ CONTINUES - Reserved
_mnemo.continueskey (Phase 12.7c). Set on a thread-start marker record to point at the previous thread whose context the new thread continues from. Value: the prior thread id (string). Rendering a continued thread pulls the prior thread’s open items,nextand last-N timeline entries ahead of the new thread’s own essence. - MNEMO_
META_ CONVERSATION - 13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): the conversation a message belongs to, so replies share its
hop count. Not
_mnemo.thread, which names a thread archive. - MNEMO_
META_ CREATOR - 13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): the agent that added a task;
ready → doneis its call. - MNEMO_
META_ DEFAULT_ AGENT - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a (AGENT-DEFAULT): on the manifest, the agent a write that names none
is made for, in place of
default. Set withcrate::Mnemo::set_default_agent; a new brain’s manifest has none. - MNEMO_
META_ DELIVERY - 13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1b):
sent,delivered,seenordone. - MNEMO_
META_ FINDING_ ID - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0: a finding’s id (
RB-014.1), its locator. - MNEMO_
META_ FROM - 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1): a message’s sender, as it said (unproven until 13b).
- MNEMO_
META_ HOPS - 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1): messages between agents. 13a (13.1b): a message’s hop count within its conversation (and its pair, for 10 minutes), for the wake-up hop cap.
- MNEMO_
META_ INVALID_ AT - Set on the earlier record when superseded. Value: unix seconds (i64).
Not interpreted by the engine’s scorer — purely for audit /
history. - MNEMO_
META_ KEY - Upsert slot name on a
remember(…, key = K)write (12.1). Combined with the memory’sscope(andagent_idforPrivatescope) to identify a single live memory per slot: a newerremember(key=K)supersedes the prior one. - MNEMO_
META_ KIND - Record kind for thread-archive turns (Phase 12.7a). Value:
"turn". - MNEMO_
META_ KIND_ CLAIM - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a:
_mnemo.kindof a claim on a topic (13.3). - MNEMO_
META_ KIND_ ESSENCE - Marker value for
_mnemo.kindon essence records (Phase 12.7b). - MNEMO_
META_ KIND_ FINDING - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b):
_mnemo.kindof a review finding. - MNEMO_
META_ KIND_ MESSAGE - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a:
_mnemo.kindof a message between agents (13.1). - MNEMO_
META_ KIND_ PRESENCE - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a:
_mnemo.kindof an agent’s presence record (13.3). - MNEMO_
META_ KIND_ TASK - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a:
_mnemo.kindof a task in the queue (13.1). - MNEMO_
META_ KIND_ THREAD_ LINK - Marker value for
_mnemo.kindon a thread-start record (one perthread_start(new, --from old)call, carrying the link in_mnemo.continues). - MNEMO_
META_ KIND_ TURN - Marker value for
_mnemo.kindon thread-turn records. - MNEMO_
META_ LENGTH - Byte length of the original tool-result content (Phase 12.7a). Set
alongside
_mnemo.sha256when truncation happened; absent otherwise. - MNEMO_
META_ MARKERS_ ONLY - v0.16.1:
trueon a turn whose content is only the markers a transcript reader makes for blocks it doesn’t keep ([thinking],[tool_use name=…],[tool_result ok, N bytes],[image]). Such a turn is kept in the thread, sothread exportshows the whole flow, but it isn’t embedded (it carries the sentinel vector) andrecallnever returns it, since it would match any query weakly.recallleaves out a marker-only turn written before v0.16.1 too, by its content. - MNEMO_
META_ NS - Namespace prefix used for every v0.8.0+ reserved metadata key (R-001.10). Keys outside this namespace are untouched user metadata.
- MNEMO_
META_ OWNER - 13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): the agent that took a task (
Mnemo::task_next). - MNEMO_
META_ PART - Zero-based part number for a turn that was chunked at the 8 KB boundary during ingest (Phase 12.7a). Absent → the turn fits in a single record.
- MNEMO_
META_ PRE_ APPROVED - 13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): the owner may go from
readytodonewithout a sign-off. - MNEMO_
META_ PRIORITY - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0: a finding’s priority (
FINDING_PRIORITIES). - MNEMO_
META_ REFS - Reserved
_mnemo.refskey — optional array of free-form reference strings (turn ids, memory ids, commits, paths) attached to an essence record (Phase 12.7b). - MNEMO_
META_ REVIEW_ BY - 13a: the coordination kinds and the reserved keys a caller may set. 13a: the coordination kinds and the reserved keys a caller may set. 13a: the coordination kinds and the reserved keys a caller may set. 13a (13.6): when someone should look at the record again, in unix seconds. A caller may set it.
- MNEMO_
META_ ROLE - Role of the turn’s author (Phase 12.7a). Value:
"user","assistant","system","tool", or any other string the source transcript used. - MNEMO_
META_ SECTION - Reserved
_mnemo.sectionkey — which essence section an item belongs to (Phase 12.7b). Values:"timeline","intent","conventions","decisions","state","open","next","lessons". Timeline entries are append-only. - MNEMO_
META_ SEQ - Monotonically increasing sequence number within the thread
(Phase 12.7a). Value: unsigned integer, 0-based. Lets
thread exportreconstruct the transcript in order. - MNEMO_
META_ SHA256 - Hex-encoded SHA-256 of the original tool-result content (Phase 12.7a). Set when the content exceeded the 16 KB truncation cap during ingest; absent otherwise.
- MNEMO_
META_ SLUG - 13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): a task’s slug, its name (
step-4-tasks). - MNEMO_
META_ STATUS - Reserved
_mnemo.statuskey — current status of a status-record. Values are per-kind (Phase 12.7b: essence uses"open"and"resolved"). Timeline entries never carry this. - MNEMO_
META_ STATUS_ HISTORY - Reserved
_mnemo.status_historykey — array of status transitions, each{"status": <str>, "at": <unix_secs>}. Append-only — the first entry records creation, each later entry records a transition. - MNEMO_
META_ SUPERSEDED_ BY - Set on the earlier record when a newer
remember(key=K)has replaced it. Value: the new record’s ULID string. Together with_mnemo.invalid_atthis marks the record as “superseded, not current” — defaultrecall,aboutand the key index skip it;history(key)walks the chain. - MNEMO_
META_ SUPERSEDES - Set on the newly-inserted record when a
remember(key=K)supersedes an earlier record. Value: the superseded record’s ULID string. - MNEMO_
META_ THREAD - Thread identifier the record belongs to (Phase 12.7a). Value: a caller-supplied string, typically the Claude Code session uuid or the planner-chosen thread slug.
- MNEMO_
META_ TO - 13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): messages between agents.
13a (13.1): a message’s recipient: an agent id,
role:<role>, orall. - MNEMO_
META_ TRIAGE - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: a finding’s triage text, and who wrote it.
- MNEMO_
META_ TRIAGED_ BY - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: who triaged a finding last.
- MNEMO_
META_ TURN_ ID - Opaque per-turn identifier from the source transcript
(Phase 12.7a). Value: typically a uuid4. Used for idempotence —
ingest_threadskips any turn whoseturn_idalready exists on a record in the target thread. - MNEMO_
META_ UPDATED_ AT - Set on a record each time
Mnemo::updatesucceeds. Value: unix seconds. Lets callers distinguish an unchanged-since-creation record from one that has been edited in place. Not interpreted by the scorer. - MNEMO_
META_ VERIFIED_ BY - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: who verified a finding.
- MNEMO_
META_ VERIFIED_ REF - v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0 (13a step 8b): review findings. v0.18.0: what verified a finding (a commit, a tag, a PR).
- MNEMO_
META_ VISIBILITY - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a (13.5):
public,team(the default when absent) orprivate. A filter, not a security boundary, until 13b. A caller may set it. - MNEMO_
META_ WAKE_ PAUSED - 13a (13.1b): the wake-up guardrails.
13a (13.1b): the wake-up guardrails.
13a (13.1b): the wake-up guardrails.
13a (13.1b): the kill switch, on the manifest:
{"by", "at"}while wake-ups are paused. - PAIR_
BURST - 13a (13.1b): the wake-up guardrails.
13a (13.1b): the wake-up guardrails.
13a (13.1b): the wake-up guardrails.
13a (13.1b): a message wakes nobody when its two agents have exchanged
this many messages, either way, in the last
PAIR_BURST_SECS. - PAIR_
BURST_ SECS - 13a (13.1b): the wake-up guardrails. 13a (13.1b): the wake-up guardrails. 13a (13.1b): the wake-up guardrails. 13a (13.1b): the pair burst’s window (10 minutes).
- PRESENCE_
EVERY_ SECS - 13a (13.3): claims and presence.
13a (13.3): claims and presence.
13a (13.3): claims and presence.
13a (13.3): the most often
last_activeis written. - TASK_
CLAIM_ TTL - 13a (13.1): tasks. 13a (13.1): tasks. 13a (13.1): tasks. 13a (13.1): a task’s claim lease (2 hours), renewed by its owner’s updates.
- TASK_
CLAIM_ WARN_ SECS - 13a (13.1): tasks. 13a (13.1): tasks. 13a (13.1): tasks. 13a: the brief warns about an own task’s claim that lapses within this.
- TASK_
DONE_ EXPORT_ KEEP_ SECS - 13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): tasks.
13a:
export --gitleaves out tasks done more than this ago (30 days). - TASK_
SLUG_ MAX - 13a (13.1): tasks.
13a (13.1): tasks.
13a (13.1): tasks.
13a: a slug’s limit (it’s 1 to 64 of
a-z,0-9,.,_,-). - TASK_
TRANSITIONS - Task transition table (13a step 4,
Mnemo::task_update).queued → active → ready → done, oractive → blocked; the back edges areblocked → activeand (R-010.7, RB-012.3)active → queuedandblocked → queued, for an owner handing a task back or anyone requeueing an abandoned one.queued → activehappens only throughMnemo::task_next. - THREAD_
TOOL_ RESULT_ TRUNCATE_ BYTES - Maximum content size for a tool-result turn before truncation
(Phase 12.7a). Tool results frequently run tens of kilobytes;
stored truncated with
_mnemo.sha256+_mnemo.lengthso the original can be recovered (or verified) out-of-band. - THREAD_
TURN_ CHUNK_ BYTES - Maximum content size for a single turn record before chunking kicks in (Phase 12.7a). 8 KB per chunk keeps each record small enough that the per-record page cost dominates — and so that a thread of mostly short messages ingests as one record each.
- V9_
ANN_ MIN_ FACTS - FMT-9b: below this many facts a v9 file has no ANN index: an exact fp16 scan of 20K × 384 dims is about a millisecond, and the IVF+PQ codebook alone would cost more disk than it saves time.
- V9_
RERANK_ PER_ HIT - FMT-9f (PLANNER-A, 2026-11-08): on v9 an unpinned recall reranks at
least this many candidates per requested hit (500 for
top_k10), or the index’s own auto depth when that’s deeper (above 100K). The v9 index is trained on fp16-rounded vectors, and at 20K–50K the auto depth (×10–×25) lost up to 0.03 recall@10 against v8; ×50 is within 0.005 at every measured tier. v8 is unchanged. - VISIBILITY_
LEVELS - 13a: the coordination kinds and the reserved keys a caller may set. 13a: the coordination kinds and the reserved keys a caller may set. 13a: the coordination kinds and the reserved keys a caller may set. The visibility levels (13.5).
- WAKE_
COOLDOWN_ SECS - 13a (13.1b): the wake-up guardrails. 13a (13.1b): the wake-up guardrails. 13a (13.1b): the wake-up guardrails. 13a (13.1b): a recipient’s cooldown between wake-ups, in seconds.
- WAKE_
PER_ HOUR - 13a (13.1b): the wake-up guardrails.
13a (13.1b): the wake-up guardrails.
13a (13.1b): the wake-up guardrails.
13a (13.1b): the wake-up guardrails. At most this many wake-ups per
recipient per hour; past it, items stay
sentand are seen at the next turn or session start.
Traits§
- Embedder
- Minimal trait any embedder implementation must satisfy. Returns
vectors in the same order as the input
texts.
Functions§
- build_
info - Report this build’s cryptographic backend configuration.
- check_
caller_ key - 13a: the coordination kinds and the reserved keys a caller may set. 13a: the coordination kinds and the reserved keys a caller may set. 13a: the coordination kinds and the reserved keys a caller may set. Check a caller-settable reserved key’s value: a visibility level, or a whole number of unix seconds that isn’t negative.
- date_of
- 13a (13.5, 13.6): visibility and freshness.
13a (13.5, 13.6): visibility and freshness.
13a (13.5, 13.6): visibility and freshness.
13a:
YYYY-MM-DD(UTC) for unix seconds. - is_
caller_ key - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
Whether
keyis one ofCALLER_KEYS. - is_
coordination - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
Whether a record is one of the coordination kinds (
COORDINATION_KINDS). - read_
transcript - Read a transcript from any
Readin the given format and return the turns in file order. Non-matching / unrecognized line types are skipped silently (Claude Code adds newtypevalues over time). - read_
transcript_ with read_transcriptwithTranscriptOptions.- slug_of
- The slug a title gives: lower case, runs of anything but
a-z0-9as one-, at mostTASK_SLUG_MAXbytes. - stale_
since - 13a (13.5, 13.6): visibility and freshness.
13a (13.5, 13.6): visibility and freshness.
13a (13.5, 13.6): visibility and freshness.
13a (13.6): when a record went stale at
now, if it has: past its_mnemo.review_by(which, when set, decides alone), or older than its kind’s default (stale_after) measured from_mnemo.as_of, else its last edit, elsecreated_at. A fact with noreview_by, a claim, a presence record and a resolved or superseded item are never stale. - valid_
agent_ id - 13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: the coordination kinds and the reserved keys a caller may set.
13a: an agent id (
MNEMO_AGENT,_mnemo.default_agent, a message’sto): 1 to 64 of[A-Za-z0-9._-]. A role (MNEMO_ROLE) follows the same rule. - valid_
finding_ id - v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0 (13a step 8b): review findings.
v0.18.0: whether
idis a finding’s id:^[A-Z]+-[0-9]+\.[0-9]+$, at most 64 bytes. - visibility_
of - 13a (13.5, 13.6): visibility and freshness.
13a (13.5, 13.6): visibility and freshness.
13a (13.5, 13.6): visibility and freshness.
13a (13.5): a record’s visibility level:
_mnemo.visibility, orteamwhen it has none. A filter, not a security boundary: everyone holding the key reads every record.
Type Aliases§
- Result
- Convenience result alias used throughout the crate.