memex

Local-first second brain that connects to Claude via MCP. Notes are stored as plain Markdown and indexed with a local ML model, fully offline, no API keys, nothing leaves your machine.

Claude is only as smart as what's in the conversation. Your decisions, your context, your thinking, invisible unless you paste them in every time.

You: What did we decide about the auth approach last sprint? Claude: I don't have context from previous conversations...

You: What did we decide about the auth approach last sprint? Claude: [memex · search_notes · "auth approach decision"] Found 2 notes: Auth Architecture Decision Apr 14 #auth #backend ───────────────────────────────────────────────────── Chose JWT + refresh tokens over sessions. Rationale: stateless design fits horizontal scaling plan. Based on your April 14th note: you went with JWT + refresh tokens. Tom also flagged keeping auth decoupled from payment logic, separate bounded contexts.

Claude searches your notes before answering and saves insights at the end of every conversation, automatically, without being asked.

This registers memex with both Claude Code and Codex. Restart the clients after installation. To register either client manually:

claude mcp add memex -- node "$(memex mcp path)" codex mcp add memex -- node "$(memex mcp path)"

That's it. On first run, the embedding model (~450MB) downloads once to~/.memex/models/.

Turns retrieval from something Claude has todecideto do into something that just happens. Every prompt you type is semantically searched against your notes, and the top 3 titles are injected as context before Claude answers — the same way native memory works. Claude then pulls full notes withget_notewhen a title looks relevant.

A background daemon keeps the embedding model warm (~/.memex/recall.sock), so a lookup costs ~30ms instead of the ~1.5s a cold CLI search spends loading the model. It idles out after 2 hours.

Cost: ~200MB resident while warm, plus up to 3 note titles of context per prompt. Remove withmemex recall uninstall.

- Semantic search, finds notes by meaning, not just keywords. Multilingual (Korean + English), runs fully offline viamultilingual-e5-base
- Hybrid retrieval, vector search + BM25 full-text + tag matching, fused via Reciprocal Rank Fusion
- Chunk-level embeddings, long notes are split into ~340-token passages and embedded individually, so an answer buried on page three is as findable as one in the opening paragraph. Search returns the passage that matched, not the note's first lines
- Cross-encoder reranking(opt-in,MEMEX_RERANK=1), retrieves twice as many candidates and reorders them withbge-reranker-v2-m3. Worth ~+20pp hit@1 on the golden set, at ~1.8s per search — off by default because auto-recall and the CLI are built around instant lookups
- Date filter, narrow search to a time range with--from/--to
- Note layers, every note ispast(immutable record),state(mutable plan), orrule(Claude behaviour guide). Past notes refuse updates; rule notes auto-inject into Claude's system prompt
- Flashback, save and search automatically surface older notes from adifferent folderthat are semantically related, "you wrote about this 124 days ago in a different context"
- Inference engine, deterministicsignalssurface un-synthesized patterns (cross-year arcs, stale state notes, tag revivals); you promote good ones intoinferences(hypotheses with provenance) that auto-invalidate when their source notes change. No LLM in the core
- MCP server, Claude searches and saves automatically. No extra CLAUDE.md setup needed
- Auto-recall, opt-in hook that searches your notes on every prompt and injects the hits before Claude answers, so recall never depends on Claude remembering to look
- Duplicate detection,save_notewarns when a semantically similar note already exists, nudging Claude to update rather than create
- Backlinks, link notes with[[Title]]syntax;get_noteshows which notes reference it
- Series collapse, a dated work log ("… 2026-07-20", "… 2026-07-23") takes at most two slots on a result page, and search reports how many more it held back
- Amendments, a correction records what it corrects (amends), so search flags the superseded note and points at the newest fix instead of returning a claim you already know is wrong
- Digest,memex digestsummarises notes saved in the last N days, grouped by folder
- CLI, add, search, tag, browse, and index notes from the terminal
- Obsidian-compatible, notes saved as.mdfiles; works alongside existing vaults
- Local DB, SQLite +sqlite-vecat~/.memex/memex.db

# Add notes memex add # interactive prompt (asks for layer) memex add --title "Note title" --content "..." --layer past memex add --title "Note title" --file ./note.md --layer state memex add --title "Note title" --content "..." --folder work/people/tom --layer past memex add --title "Note title" --content "..." -T typescript -T architecture --layer past # Layers memex layer # distribution of past / state / rule memex layer <id> state # move a note to a different layer # Search memex search "semantic search query" # multilingual memex search "knowledge management" --limit 10 # multilingual: matches Korean/Japanese notes too memex search "query" --tag typescript # filter by tag memex search "query" --from 2026-04-01 # notes since a date memex search "query" --from 2026-04-01 --to 2026-04-30 # Browse memex list # recent 10 notes memex list --limit 20 memex show <id> memex tags # all tags with counts memex related <id> # semantically related notes memex digest # last 7 days + signals + inferences memex digest --days 30 # summary of last 30 days # Insights (inference engine) memex signals # detect un-synthesized patterns memex signals --type hidden_arc # one type only memex signals dismiss <id> # triage (also: snooze) memex signals mint <signalId> # print evidence bundle to synthesize memex signals mint <signalId> --title "..." --summary "..." --confidence 0.7 memex inferences # list inferences (auto-flags stale) memex schedule # print cron/launchd snippet (no daemon) # Edit / delete memex edit <id> memex delete <id> memex delete --yes <id> # skip confirmation # Index external directories memex source add ~/Documents/My\ Notes # register a vault memex source list memex source remove ~/Documents/My\ Notes memex index # scan vault + all sources memex index --force # re-index everything memex reembed # re-embed with current model # Config memex config show memex config set vault-path ~/Documents/Second\ Brain # MCP memex mcp install # register with Claude Code and Codex # Auto-recall memex recall install # search notes on every prompt, inject hits memex recall uninstall # remove the hook memex mcp path # print MCP binary path

claude mcp add memex -- node "$(memex mcp path)"

codex mcp add memex -- node "$(memex mcp path)"

{ "mcpServers": { "memex": { "command": "node", "args": ["<path from memex mcp path>"] } } }

Inferences are kept separate from notes (excluded from search) and are cited as hypotheses, never facts. Detection stays deterministic; the only LLM step is synthesizing an inference's summary, which Claude does, never memex.

Every note is classified into one of three layers based on mutability:

The CLI prints a colour-coded[past]/[state]/[rule]badge next to each note inlist,search, andshow.

- save_note(MCP) andmemex add(CLI) require an explicitlayer. The classification rules are documented in the tool description so Claude picks correctly.
- On first run, existing notes get a folder-based backfill:projects/dev/herald→state,coding→rule, everything else →past. Migration is idempotent.
- rulenotes are also auto-injected into the MCP server's instructions, seeRule layer auto-injectbelow.

When you save a note or search, memex automatically surfaces older notes from adifferent folderthat are semantically similar, "you wrote about this 124 days ago in a different context." Stored as system-generated backlinks (note_links.source = 'flashback'), separate from your[[wikilinks]](source = 'wiki').

Notes withlayer = 'rule'are appended to the MCP server's instructions on boot, under a## House Rulessection. Claude sees them at the start of every conversation, nosearch_notescall required. This is the right home for coding style guides or other behavioural guidance.

Updates to rule notes are picked up on the next Claude Desktop / Claude Code restart.

~/.memex/ config.json, vault path, sources, and aliases memex.db, SQLite DB (notes + note/chunk vec embeddings + FTS5 index) models/, cached embedding model <vault>/ *.md, notes (Obsidian-compatible)

memexis one of three local-first tools that share one principle,your data stays on your machine, and the AI comes to it.They interoperate through any MCP client, and none depends on the others.

flowchart TB U([You]) subgraph I["Interfaces, talk to your tools"] direction LR CD[Claude Desktop] CC[Claude Code] H["Herald · voice"] end subgraph T["Local-first tools, each owns its data, on your machine"] direction LR F["firma · money<br/>~/.firma"] M["memex · memory<br/>~/.memex"] S["skope · news<br/>~/.skope"] end U --> I I -- MCP --> F & M & S F <-. never call each other .-> M M <-.-> S

- firma· money, portfolio, net worth, cash flow
- memex· memory, notes and the context behind them, across sessions
- skope· news, a personalized lens on the world

You reach them through Claude Desktop, Claude Code, Cursor, orHerald, a voice interface. The tools compose through the model, never by calling each other.

llms.txtis a machine-readable summary of this project for LLM agents, concise description with documentation links, following thellms.txt standard.

Source-grounded MCP, A2A, and x402 metadata for verified knowledge commerce.