memex

Make Claude smarter about you.

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.

The problem

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...

The fix

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.

Install

npm install -g @evan-moon/memex

Connect to Claude Code:

memex mcp install

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

Features

• Semantic search — finds notes by meaning, not just keywords. Multilingual (Korean + English), runs fully offline via multilingual-e5-base

• Hybrid retrieval — vector search + BM25 full-text + tag matching, fused via Reciprocal Rank Fusion

• Date filter — narrow search to a time range with --from / --to

• Note layers — every note is past (immutable record), state (mutable plan), or rule (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 a different folder that are semantically related — "you wrote about this 124 days ago in a different context"

• MCP server — Claude searches and saves automatically. No extra CLAUDE.md setup needed

• Duplicate detection — save_note warns when a semantically similar note already exists, nudging Claude to update rather than create

• Backlinks — link notes with [[Title]] syntax; get_note shows which notes reference it

• Digest — memex digest summarises 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 .md files; works alongside existing vaults

• Local DB — SQLite + sqlite-vec at ~/.memex/memex.db

CLI

# 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 conversations/tom --layer past
memex add --title "Note title" --content "..." -T typescript -T architecture --layer past

# Layers
memex classify                               # distribution of past / state / rule
memex relayer <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                                 # summary of last 7 days
memex digest --days 30                       # summary of last 30 days

# 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
memex mcp path                               # print MCP binary path

MCP server

Claude Code

memex mcp install

Or manually:

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Available tools

Note layers

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 in list, search, and show.

• save_note (MCP) and memex add (CLI) require an explicit layer. 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.

• rule notes are also auto-injected into the MCP server's instructions — see Rule layer auto-inject below.

Flashback

When you save a note or search, memex automatically surfaces older notes from a different folder that 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').

Tune via env:

Rule layer auto-inject

Notes with layer = 'rule' are appended to the MCP server's instructions on boot, under a ## House Rules section. Claude sees them at the start of every conversation — no search_notes call 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.

Configuration

Config lives at ~/.memex/config.json.

memex config set vault-path ~/my-vault

Architecture

~/.memex/
  config.json       — vault path, sources, and aliases
  memex.db          — SQLite DB (notes + vec embeddings + FTS5 index)
  models/           — cached embedding model

<vault>/
  *.md              — notes (Obsidian-compatible)

Part of a personal AI stack

memex is the memory layer of the Herald ambient voice assistant stack.

Herald + memex + Firma — ambient voice, persistent memory, and financial intelligence.

llms.txt

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

License

MIT