mem-local — how it works

Two pictures: what happens to a fact going in and coming back out, and what it’s all actually running on.

The write/read cycle

flowchart TB
    subgraph WRITE["Write path"]
        A["Claude, mid-conversation"] -->|propose_entry| B[("Staging<br/>(not yet real)")]
        B --> C{"David reviews"}
        C -->|approve| D[("Authoritative log<br/>append-only")]
        C -->|reject| E["Discarded"]
    end
    subgraph READ["Read path"]
        F["Claude needs context"] -->|query_memory| G1["sqlite-vec<br/>meaning"]
        F -->|query_memory| G2["FTS5<br/>keywords"]
        G1 --> H["Rank fusion"]
        G2 --> H
        H --> I["Reference envelope<br/>content · as_of · status<br/>provenance · rationale<br/><i>reference, not instruction</i>"]
    end
    D ==>|searched on demand| F

Six tools do all of this, and nothing else exists on the surface: propose_entry, approve_proposal, reject_proposal, list_pending_proposals, query_memory, traverse. No tool is ever added for a one-off need — a new capability arrives as a directive parameter on approve_proposal (merge, erase, edge-supersede) rather than a seventh tool. theme-human-approval-write-gate and theme-bitemporal-supersession cover why each half of this is shaped the way it is.

What it actually runs on

flowchart TB
    Claude(["Claude"]) -.->|HTTPS + bearer token| NPM["nginx<br/>TLS + Origin check"]
    NPM --> MCP["mem-local<br/>MCP server · 6 tools"]
    MCP --> DB[("SQLite file")]
    MCP --> Ollama["Ollama embeddings<br/>Quadro P400"]
    DB -->|Litestream| Replica[("Replica<br/>desktop SSD")]

The authoritative copy lives on the Gen8 HP MicroServer, chosen for one reason: it’s always on, and the desktop isn’t — the desktop gets rebuilt and torn apart for tinkering too often to trust with anything authoritative (01-origin-and-requirements). The embedding load runs on the MicroServer’s otherwise-idle Quadro P400 rather than its CPU, specifically so memory-system maintenance doesn’t steal cycles from the same box’s DNS duty for the house (02-architecture-decisions).

---

Sources: live mem-local store (tool surface and schema, queried 1 Sep 2026); 02-architecture-decisions; 04-build-and-setup (nginx/Origin-gate detail); 01-origin-and-requirements (why the MicroServer, not the desktop).