{
  "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/evan-moon/memex/main/assets/og-image.png\" alt=\"memex\" width=\"560\" />\n</p>\n\n<h1 align=\"center\">memex</h1>\n\n<p align=\"center\">\n  <strong>Make Claude smarter about you.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@evan-moon/memex\"><img src=\"https://img.shields.io/npm/v/@evan-moon/memex?style=flat&color=black&label=npm\" alt=\"npm version\"></a>\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/github/license/evan-moon/memex?style=flat&color=black\" alt=\"License\"></a>\n  <a href=\"https://nodejs.org\"><img src=\"https://img.shields.io/node/v/@evan-moon/memex?style=flat&color=black\" alt=\"Node version\"></a>\n</p>\n\n<p align=\"center\">\n  <code>npm install -g @evan-moon/memex</code>\n</p>\n\n> Make Claude smarter about you.\n\nLocal-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.\n\n---\n\n## The problem\n\nClaude is only as smart as what's in the conversation. Your decisions, your context, your thinking, invisible unless you paste them in every time.\n\n```\nYou:    What did we decide about the auth approach last sprint?\nClaude: I don't have context from previous conversations...\n```\n\n## The fix\n\n```\nYou:    What did we decide about the auth approach last sprint?\n\nClaude: [memex · search_notes · \"auth approach decision\"]\n\n        Found 2 notes:\n\n        Auth Architecture Decision  Apr 14  #auth #backend\n        ─────────────────────────────────────────────────────\n        Chose JWT + refresh tokens over sessions. Rationale:\n        stateless design fits horizontal scaling plan.\n\n        Based on your April 14th note: you went with JWT +\n        refresh tokens. Tom also flagged keeping auth decoupled\n        from payment logic, separate bounded contexts.\n```\n\nClaude searches your notes before answering and saves insights at the end of every conversation, automatically, without being asked.\n\n---\n\n## Install\n\n```bash\nnpm install -g @evan-moon/memex\n```\n\nConnect your apps:\n\n```bash\nmemex mcp install\n```\n\nThis registers memex with every MCP client on this machine — Claude, Claude Code, Codex, Cursor — by writing each one's own config file. Restart the clients afterwards. The same thing is one button in the app: run `memex ui` and open **Connect**, which also shows which apps can already reach memex.\n\nThat's it. On first run, the embedding model (~450MB) downloads once to `~/.memex/models/`.\n\n### Auto-recall (optional)\n\n```bash\nmemex recall install\n```\n\nTurns retrieval from something Claude has to *decide* to 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 with `get_note` when a title looks relevant.\n\nA 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.\n\nCost: ~200MB resident while warm, plus up to 3 note titles of context per prompt. Remove with `memex recall uninstall`.\n\n---\n\n## Features\n\n- **Semantic search**, finds notes by meaning, not just keywords. Multilingual (Korean + English), runs fully offline via [`multilingual-e5-base`](https://huggingface.co/intfloat/multilingual-e5-base)\n- **Hybrid retrieval**, vector search + BM25 full-text + tag matching, fused via Reciprocal Rank Fusion\n- **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\n- **Cross-encoder reranking** (opt-in, `MEMEX_RERANK=1`), retrieves twice as many candidates and reorders them with [`bge-reranker-v2-m3`](https://huggingface.co/BAAI/bge-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\n- **Date filter**, narrow search to a time range with `--from` / `--to`\n- **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\n- **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\"\n- **Desktop view**, `memex ui` opens the vault by topic and splits each one into what still stands and what has gone out of date — corrected by a later note, or a plan with newer records piled up behind it\n- **Inference engine**, deterministic *signals* surface un-synthesized patterns (cross-year arcs, stale state notes, tag revivals); you promote good ones into *inferences* (hypotheses with provenance) that auto-invalidate when their source notes change. No LLM in the core\n- **MCP server**, Claude searches and saves automatically. No extra CLAUDE.md setup needed\n- **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\n- **Duplicate detection**, `save_note` warns when a semantically similar note already exists, nudging Claude to update rather than create\n- **Backlinks**, link notes with `[[Title]]` syntax; `get_note` shows which notes reference it\n- **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\n- **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\n- **Digest**, `memex digest` summarises notes saved in the last N days, grouped by folder\n- **CLI**, add, search, tag, browse, and index notes from the terminal\n- **Obsidian-compatible**, notes saved as `.md` files; works alongside existing vaults\n- **Local DB**, SQLite + [`sqlite-vec`](https://github.com/asg017/sqlite-vec) at `~/.memex/memex.db`\n\n---\n\n## CLI\n\n```bash\n# Add notes\nmemex add                                    # interactive prompt (asks for layer)\nmemex add --title \"Note title\" --content \"...\" --layer past\nmemex add --title \"Note title\" --file ./note.md --layer state\nmemex add --title \"Note title\" --content \"...\" --folder work/people/tom --layer past\nmemex add --title \"Note title\" --content \"...\" -T typescript -T architecture --layer past\n\n# Layers\nmemex layer                               # distribution of past / state / rule\nmemex layer <id> state                     # move a note to a different layer\n\n# Search\nmemex search \"semantic search query\"         # multilingual\nmemex search \"knowledge management\" --limit 10    # multilingual: matches Korean/Japanese notes too\nmemex search \"query\" --tag typescript        # filter by tag\nmemex search \"query\" --from 2026-04-01       # notes since a date\nmemex search \"query\" --from 2026-04-01 --to 2026-04-30\n\n# Browse\nmemex list                                   # recent 10 notes\nmemex list --limit 20\nmemex show <id>\nmemex tags                                   # all tags with counts\nmemex related <id>                           # semantically related notes\nmemex digest                                 # last 7 days + signals + inferences\nmemex digest --days 30                       # summary of last 30 days\n\n# Insights (inference engine)\nmemex signals                                # detect un-synthesized patterns\nmemex signals --type hidden_arc              # one type only\nmemex signals dismiss <id>                   # triage (also: snooze)\nmemex signals mint <signalId>                        # print evidence bundle to synthesize\nmemex signals mint <signalId> --title \"...\" --summary \"...\" --confidence 0.7\nmemex inferences                             # list inferences (auto-flags stale)\nmemex schedule                               # print cron/launchd snippet (no daemon)\n\n# Edit / delete\nmemex edit <id>\nmemex delete <id>\nmemex delete --yes <id>                      # skip confirmation\n\n# Index external directories\nmemex source add ~/Documents/My\\ Notes       # register a vault\nmemex source list\nmemex source remove ~/Documents/My\\ Notes\nmemex index                                  # scan vault + all sources\nmemex index --force                          # re-index everything\nmemex reembed                                # re-embed with current model\n\n# Config\nmemex config show\nmemex config set vault-path ~/Documents/Second\\ Brain\n\n# MCP\nmemex mcp install                            # register with every MCP client on this machine\n\n# Auto-recall\nmemex recall install                         # search notes on every prompt, inject hits\nmemex recall uninstall                       # remove the hook\nmemex mcp path                               # print MCP binary path\n```\n\n---\n\n## MCP server\n\n### Claude, Claude Code, Codex, Cursor\n\n```bash\nmemex mcp install\n```\n\nOr from the app: `memex ui`, then **Connect**.\n\nBoth write each client's own config file and leave the servers already in it alone. If a client still runs an older copy of memex, both repoint it. `memex mcp path` prints the server path for a client memex does not know about yet.\n\n### Available tools\n\n| Tool | Description |\n|------|-------------|\n| `save_note` | Save a note, requires `layer`, warns if a similar note already exists, surfaces flashbacks |\n| `search_notes` | Semantic search; supports `category`, `tag`, `date_from`, `date_to` filters; appends flashbacks for the top result |\n| `list_notes` | List recent notes |\n| `list_tags` | List all tags with note counts |\n| `list_folders` | List all folders with note counts |\n| `get_note` | Get full content and backlinks of a note by ID |\n| `update_note` | Update title or content. Refuses `past` notes (with `[Amendment]` suggestion) and `rule` notes (user-only) |\n| `delete_note` | Delete a note by ID |\n| `get_signals` | Deterministic un-synthesized patterns (hidden_arc / stale_state / dangling_link / tag_burst) |\n| `update_signal_status` | Triage a signal, dismiss or snooze |\n| `list_inferences` | List synthesized hypotheses (re-checks staleness first) |\n| `get_inference` | One inference with full provenance + change/delete markers |\n| `mint_inference` | Persist an approved hypothesis, requires explicit confirmation |\n\nInferences 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.\n\n### Note layers\n\nEvery note is classified into one of three layers based on mutability:\n\n| Layer | Meaning | Claude's permission |\n|-------|---------|---------------------|\n| `past` | Record of what happened, retros, meetings, decision rationale, debugging sessions | Append-only. `update_note` refuses, suggesting an `[Amendment]` note instead |\n| `state` | Current state or plans, project progress, roadmaps, a person's current role | Freely updatable |\n| `rule` | Behaviour guide for Claude, coding style, search policy | Claude is read-only. Only the user writes |\n\nThe CLI prints a colour-coded `[past]` / `[state]` / `[rule]` badge next to each note in `list`, `search`, and `show`.\n\n- `save_note` (MCP) and `memex add` (CLI) require an explicit `layer`. The classification rules are documented in the tool description so Claude picks correctly.\n- On first run, existing notes get a folder-based backfill: `projects`/`dev`/`herald` → `state`, `coding` → `rule`, everything else → `past`. Migration is idempotent.\n- `rule` notes are also auto-injected into the MCP server's instructions, see [Rule layer auto-inject](#rule-layer-auto-inject) below.\n\n### Flashback\n\nWhen 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'`).\n\nTune via env:\n\n| Env | Default | Behaviour |\n|-----|---------|-----------|\n| `MEMEX_FLASHBACK_DAYS` | `90` | minimum age gap, in days |\n| `MEMEX_FLASHBACK_DIST` | `0.4` | maximum vector distance (lower = stricter match) |\n| `MEMEX_FLASHBACK_LIMIT` | `3` | max suggestions per surface |\n\n### Rule layer auto-inject\n\nNotes 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.\n\n| Env | Default | Behaviour |\n|-----|---------|-----------|\n| `MEMEX_INJECT_RULES` | enabled | Set to `0` to disable injection entirely |\n| `MEMEX_RULES_MAX_CHARS` | `8000` | Byte budget for the injected section; overflow is truncated with a `console.warn` |\n\nUpdates to rule notes are picked up on the next Claude Desktop / Claude Code restart.\n\n---\n\n## Configuration\n\nConfig lives at `~/.memex/config.json`.\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `vault_path` | `~/Documents/Second Brain` | Directory where `.md` files are saved |\n| `sources` | `[]` | Additional directories to index (e.g. existing Obsidian vaults) |\n| `aliases` | `{}` | Search alias map, e.g. `{ \"js\": [\"javascript\", \"ecmascript\"] }`, values can be any language to bridge across scripts |\n\n```bash\nmemex config set vault-path ~/my-vault\n```\n\n---\n\n## Architecture\n\n```\n~/.memex/\n  config.json, vault path, sources, and aliases\n  memex.db, SQLite DB (notes + note/chunk vec embeddings + FTS5 index)\n  models/, cached embedding model\n\n<vault>/\n  *.md, notes (Obsidian-compatible)\n```\n\n| Package | Role |\n|---------|------|\n| `@memex/db` | SQLite schema, drizzle queries, sqlite-vec + FTS5 integration |\n| `@memex/embed` | Local embedder via @huggingface/transformers |\n| `@memex/rerank` | Local cross-encoder reranker (opt-in) |\n| `@memex/core` | Note service shared by CLI and MCP: save, edit, search, vector indexing |\n| `@memex/utils` | Config, path helpers, shared utilities |\n| `@memex/mcp` | MCP server (bundled into CLI dist) |\n\n---\n\n## The ecosystem\n\n**memex** is 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.\n\n```mermaid\nflowchart TB\n    U([You])\n    subgraph I[\"Interfaces, talk to your tools\"]\n        direction LR\n        CD[Claude Desktop]\n        CC[Claude Code]\n        CU[Cursor]\n    end\n    subgraph T[\"Local-first tools, each owns its data, on your machine\"]\n        direction LR\n        F[\"firma · money<br/>~/.firma\"]\n        M[\"memex · memory<br/>~/.memex\"]\n        S[\"skope · news<br/>~/.skope\"]\n    end\n    U --> I\n    I -- MCP --> F & M & S\n    F <-. never call each other .-> M\n    M <-.-> S\n```\n\n- **[firma](https://github.com/evan-moon/firma)** · money, portfolio, net worth, cash flow\n- **[memex](https://github.com/evan-moon/memex)** · memory, notes and the context behind them, across sessions\n- **[skope](https://github.com/evan-moon/skope)** · news, a personalized lens on the world\n\nYou reach them through Claude Desktop, Claude Code, Cursor, or any other MCP client. The tools compose through the model, never by calling each other.\n\n---\n\n## llms.txt\n\n[`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](https://llmstxt.org/).\n\n---\n\n## License\n\nMIT\n",
  "bytes": 15832,
  "sha": "d9e2708e529581bf5f466bfb5b83c4dbc9240c4977e41eede1ba49403e942901",
  "repo_slug": "evan-moon/memex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_evan_moon_memex_7fb48b3f/readme"
}