memex: Instructions file for Claude Code

Memex

Evan's memory engine — semantic search over personal notes, powered by SQLite + vector embeddings.

Architecture

apps/
├── cli/   # memex CLI — the safety net (see surface policy below)
├── docs/  # memex.sh — the marketing and documentation site (Next.js)
└── mcp/   # MCP server — exposes memex tools to Claude
packages/
├── core/   # Note service shared by cli/mcp (save/edit/search/delete)
├── db/     # SQLite client, schema, repository (drizzle + sqlite-vec)
├── embed/  # Embedding model wrapper (@huggingface/transformers)
├── llm/    # Provider layer for the CLI-backed models (claude-code, codex)
├── rerank/ # Cross-encoder reranker, opt-in via MEMEX_RERANK=1
└── utils/  # Config loader, path helpers, formatters, note chunker

DB lives at ~/.memex/memex.db. Model cache at ~/.memex/models/.

openDb snapshots the database to memex.db.bak-<YYYYMMDD-HHMMSS> whenever a schema migration is pending and the vault is not empty, then keeps the newest three. It uses VACUUM INTO rather than copying the file, because the MCP server and the CLI are both attached in WAL mode and a filesystem copy can be torn mid-transaction — if you ever copy the DB by hand, take -wal with it. A snapshot that fails does not stop the database from opening; memex stats prints how many backups are kept and when the newest was taken.

What memex is

memex defines memory explicitly so it can be retrieved correctly without anyone reading or maintaining it.

There is no window, no editor, and no screen. The reader is always a model, reaching memex through MCP. That is the constraint every design decision answers to:

• A note's layer and sections are declared at write time, because that is the only moment the writer knows how long the thing stays true. Nothing downstream has to guess.
• A correction states what it corrects (amends / amends_kind / invalidates), so every surface that returns the old note carries the fix. Nobody has to notice and clean up.
• A state note names its evidence (derives_from), so it can be rechecked by comparison rather than by someone rereading the vault.
• Signals and inferences are deterministic. They are not a backlog for a person to clear; they are material the retrieval path uses.