Skip to content

Architecture

memd is a single Rust binary that owns local storage, hybrid retrieval, and a shared operation surface used by the direct CLI commands, memd call, and the warm/batch execution modes.

Experience cases use the same canonical task-artifact store. The CLI captures execution context before warm dispatch, so records identify the requesting session. Explicit checks run in that CLI process; the worker receives only their receipts. Lesson recall reads canonical cases and applies exact environment conditions and lexical symptom matching. It is separate from hybrid chunk ranking. See Experience memory.

memd layers: callers, the CLI, retrieval and the store, and the files. Callers coding agents (Claude Code, Codex) · AI scientists · people, scripts memd CLI one binary; a warm worker keeps the indexes loaded search · agent-context add · experience note · find reads open the store read-only; writes go through one writer ranked search records and cases Hybrid retrieval BM25 sparse index HNSW dense index, local embeddings fusion, reranking, hot cache Store SQLite: metadata, tasks, experience cases append-only segments per tenant write-ahead log per tenant On disk ~/.memd/data/ metadata.db · sparse_index/ · tenants/<id>/{wal.log, segments/, warm_index/}
Callers use the memd CLI. Ranked searches go through hybrid retrieval. Writes and experience cases use the store directly. Both keep their files under the data directory.

The runtime stack is designed so direct CLI commands and local operation calls share the same storage, retrieval, and artifact machinery. SQLite is accessed through a bounded connection pool under WAL-mode locking, and HNSW rebuilds swap atomically without blocking readers.

Layers

Clients

One trusted machine; multiple agent processes. Coding agents (Claude Code, Codex, others) and AI-scientist workflows speak to memd through ordinary shell commands. Humans and scripts use the same CLI. No special transport is required: the binary is the API.

CLI surface and operations

Two surfaces, one shared dispatcher.

  • Entry commands. memd agent-context builds a bounded pre-work context file with a JSON audit log; memd search and memd add are the workhorse retrieve/write pair; memd warm start|status|stop manages the worker that keeps the store and indexes hot across calls; memd batch --jsonl streams structured operations through a single loaded process. memd doctor diagnoses host wiring (binary/worker version skew, the resolved data dir, agent-rule and hook installation).
  • Retrieval observability. memd search and memd agent-context attach a scope_status block to every result payload: the effective tenant/project, the retrieval_mode (hybrid for fused or BM25-only retrieval, dense for dense-only retrieval, or text_fallback when neither index is available), a warning when the requested tenant has no stored memory, and a wider_scope_hits hint when a project-scoped query comes up short but the tenant holds matching memory one scope wider. This keeps "no memory exists" distinguishable from "scoped past it" and surfaces degraded retrieval in-band instead of only in logs.
  • Operation surface. memd call <op> --json '{...}' and the typed CLI subcommands dispatch to the same handlers: memory, task, artifact, and context. memory.* is intentionally flexible (chunks, code, docs, traces); task.* and artifact.* are stricter and preserve the recoverable structure of work.

Hybrid retrieval

Lane Role Notes
Dense (HNSW) semantic recall mapping.bin (bincode-packed), graph dump optional
Sparse (BM25) lexical recall tantivy index, open_or_create
Optional reranker precision lift feature-based by default; ONNX cross-encoder and MemReranker-4B opt-in

Hybrid queries retrieve dense candidates, then sparse candidates; the hybrid searcher fuses their results. When sparse retrieval returns no hits, dense scores pass through directly. The built-in feature reranker handles ordinary agent traffic. See Optional rerankers for the cross-encoder and MemReranker-4B paths.

When dense initialization fails, an available BM25 index serves queries across the indexed corpus. Context packing skips candidates that exceed the remaining token budget and continues with smaller candidates.

Persistent store

BM25 splits code identifiers, then lowercases and stems every token with the same analyzer for indexing and querying. <data_dir>/sparse_revision records the analyzer revision. A writer rebuilds an older sparse index from segment payloads before serving requests, then commits the index and marks it current. An interrupted rebuild starts again at the next writable open. Read-only opens do not rebuild or change the marker.

Missing or undecodable payloads are reported and skipped. A completed pass over the readable payloads marks the index current. Read or commit failures leave the rebuild pending. WAL recovery queues new and physically repaired chunks for indexing; repeated indexing replaces that chunk's sparse documents.

  • SQLite metadata under WAL-mode locking with a bounded connection pool (MEMD_SQLITE_POOL_MAX). Pooled WAL gives concurrent readers without starving writers.
  • Immutable segments per tenant. Append-only payload files; deletion is logical (tombstones) until writer open or maintenance reclaims the bytes.
  • Per-tenant WAL (wal.log) fsynced before commit. Crash recovery replays missing payloads into segments, preserves lifecycle metadata, queues indexing, and reports bad records while continuing with later records. Deleted chunks stay deleted. Shutdown finalizes every nonempty segment, including small segments. Writer open packs small sealed segments in size tiers: two segments in the same power-of-two tier combine until they reach half the configured segment capacity. Each copied chunk advances at least one tier; healthy segments at or above half capacity are left alone. With no deletes, there is at most one small segment per tier after open, plus the segment sealed by the next short write. For 300 one-chunk lifetimes at the default capacity, at most 10 directories remain after shutdown.

Segment packing copies live payload bytes without changing index state or lifecycle metadata. It syncs the replacement and its parent directory, commits and checkpoints the new SQLite locations, then removes the source directories. If the checkpoint is blocked, both copies remain. The next writer removes unreferenced directories and reclaims deleted or purged payload bytes. A read-only open never packs or removes segments.

A WAL with corrupt or failed records is retained for repair. Other records and tenants still load. Purge refuses to discard that tenant's WAL while those records remain unresolved.

Digest identities include their tenant. Replacing a digest and updating its projection links affect only that tenant's artifact. Legacy digest rows remain stored; refreshing a digest writes its tenant-scoped identity and does not delete the old row.

Outcome ranking reads only matching candidate chunks from episodes created within the last 90 days and excludes expired episodes. Retrieval episodes normally expire after 90 days; applied purge removes expired episodes, their items, and their outcome events within the selected tenant and project.

Concurrency and the warm worker

One trusted machine runs one writer, many readers. The warm worker is the normal writer: it holds an exclusive flock on <data_dir>/.writer.lock and records its pid and memd version there. Reads open the store read-only, take no lock, and never mutate indexes. Direct writes (--warm off, or the cold fallback when no worker is reachable) take the same lock with a bounded retry budget, so two processes never corrupt the store.

The worker's control socket lives at a stable path derived only from the data directory, so a freshly upgraded binary can reach, ping, and replace a worker left running by the previous version instead of stranding it. An idle worker exits on its own after MEMD_WARM_IDLE_TIMEOUT_SECS (default 30 minutes), releasing the lock — an orphaned daemon cannot block writes indefinitely. See Shared topology for the single-writer contract in full.

On-disk layout

See Data layout for the full tree. The short version:

~/.memd/data/
├── metadata.db
├── sparse_index/
└── tenants/<tenant_id>/
    ├── wal.log
    ├── segments/
    └── warm_index/

Trust boundary

Search and digest helpers return candidates. Canonical non-digest task and artifact records are the trust anchor. Persisted digests (project briefs, failure/decision/evidence libraries) are compiled hints, not authority. Promotion to verified_record requires an independent reviewer with a distinct agent_id submitting a verification — single-writer self-promotion is rejected. See Trust boundary for the rules and Comparison with other memory tools for how this contrasts with implicit-trust designs.

Why this shape

Three design choices fall out of the layers above.

  1. No LLM in the write path. memory.add stores chunks and structured records directly; task.* and artifact.* capture the lifecycle without running an extractor. The LLM, if any, is in the agent loop, not in the store. This keeps seed cost low and decouples write quality from extractor-model quality.
  2. Hybrid retrieval, not vector-only. Dense alone misses identifiers, error strings, paths, and ticket IDs. Sparse alone misses paraphrase. Both lanes run; results are fused.
  3. Trust is a first-class object. Most memory systems return what they retrieve and trust the caller to decide. memd separates retrieval candidates from canonical artifacts, marks digests as compiled hints, and requires distinct-writer verification before anything is labelled verified. The compiled wiki and digest libraries are useful precisely because they cannot become ungrounded authority.