Storage Engine
MuninnDB's storage layer is purpose-built for cognitive memory. It sits on top of Pebble (CockroachDB's embedded KV) but the key schema, binary encoding, and access patterns are all custom-designed for engram storage.
Pebble KV
Pebble is a pure-Go LSM (Log-Structured Merge Tree) embedded KV store. It provides crash safety via WAL, MVCC for concurrent reads, and efficient range iteration.
MuninnDB uses Pebble merge operators for atomic FTS stats updates — avoiding read-modify-write cycles that would add latency to the write path.
Engram Record Format (ERF v1)
ERF v1 is MuninnDB's binary encoding for engrams. The format has a fixed 152-byte header at known offsets for fast metadata filtering, followed by variable-length content and optional embedding data.
| Section | Size | Contents |
|---|---|---|
| Magic + Version | 4 bytes | 0x4D554E4E (MUNN) + version byte |
| Fixed metadata | 100 bytes | ID, confidence, relevance, stability, access_count, state, timestamps |
| Variable header | ~52 bytes avg | concept, tag digests (msgpack), association count |
| Content | 0–16KB | zstd-compressed if >512 bytes |
| Associations | 40 bytes × N | fixed-width: target_id + weight + type |
| Embedding | optional, ~768 bytes | 768 int8 (4× quantized from float32) |
| Checksum | 8 bytes | xxHash64 of all preceding bytes |
Key Schema
Keys are prefixed to enable efficient targeted scans:
0x01 + vault + id— Full engram record0x02 + vault + id— Metadata-only record (100 bytes). Used by decay worker to avoid reading full engrams.0x03 + vault + index_type + token— Index entries (FTS, adjacency)
L1 Cache
Hot engrams are kept in an in-memory LRU cache (default 10,000 entries). Point reads by ID serve from cache if present. Cache is populated on read, evicted on LRU basis. Cache max size is configurable.