memex MCP server
Commit Sep 20, 2026Provides a local-first semantic memory for AI clients by indexing Markdown notes with a local ML model for offline retrieval.
Also known as evan-moon/memex, @evan-moon/memex
- Stars
- 3
- Tools
- 13
- Downloads, 30 days
- 226
- Latest version
- 0.5.0
- Last commit
- Sep 20, 2026
- License
- MIT
What is memex MCP?
memex provides a local-first semantic memory for AI clients by indexing Markdown notes with a local ML model for offline retrieval. It exposes 13 tools, such as save_note, search_notes, list_notes.
Summary generated from the project's README
About memex MCP server
Memex provides a local-first semantic memory system designed to give AI clients like Claude, Cursor, and Codex access to your personal knowledge. By indexing Markdown notes using a local machine learning model, it allows your AI assistant to retrieve relevant context from your previous decisions, thoughts, and documentation without any data leaving your machine. It operates entirely offline and requires no external API keys.
The system uses a hybrid retrieval approach combining vector search, full-text matching, and tag filtering. It organizes information into three distinct layers: past records, mutable state plans, and read-only rules for AI behavior. Users can manage their knowledge through a command line interface or let the MCP server handle retrieval automatically. For enhanced performance, an optional auto-recall feature can be enabled to inject relevant note titles into every prompt, ensuring the AI has immediate access to your most important context.
What you can do with it
- 1Retrieve past project decisionsAsk your AI client to find specific architectural choices or meeting outcomes from your previous Markdown notes.
- 2Automate context injectionEnable a background process that automatically searches your notes and provides the top results to the AI before it answers.
- 3Manage AI behavior guidelinesCreate specific rule notes that are automatically injected into the AI's system prompt to guide its coding style or policies.
- 4Discover hidden patterns in notesUse the inference engine to detect un-synthesized patterns or long-term trends across your stored information.
Written from the project's README. Every use case is checked against a quote from it.
How to install memex MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall memex MCP in Claude Code
$ claude mcp add memex -- npx -y @evan-moon/memexInstall memex MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"memex": {
"command": "npx",
"args": [
"-y",
"@evan-moon/memex"
]
}
}
}Install memex MCP in VS Code
.vscode/mcp.json
{
"servers": {
"memex": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@evan-moon/memex"
]
}
}
}Install memex MCP in VS Code CLI
$ code --add-mcp '{"name":"memex","type":"stdio","command":"npx","args":["-y","@evan-moon/memex"]}'Install memex MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"memex": {
"command": "npx",
"args": [
"-y",
"@evan-moon/memex"
]
}
}
}Install memex MCP in Codex
$ codex mcp add memex -- npx -y @evan-moon/memexInstall memex MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.memex] command = "npx" args = ["-y", "@evan-moon/memex"]
Install memex MCP in Gemini CLI
$ gemini mcp add -s user memex npx -- -y @evan-moon/memexInstall memex MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"memex": {
"command": "npx",
"args": [
"-y",
"@evan-moon/memex"
]
}
}
}memex MCP tools 13
Detected from the READMEsave_notesearch_noteslist_noteslist_tagslist_foldersget_noteupdate_notedelete_noteget_signalsupdate_signal_statuslist_inferencesget_inference
| save_note | — | |
| search_notes | — | |
| list_notes | — | |
| list_tags | — | |
| list_folders | — | |
| get_note | — | |
| update_note | — | |
| delete_note | — | |
| get_signals | — | |
| update_signal_status | — | |
| list_inferences | — | |
| get_inference | — |
Show all 13 toolsShow fewer tools
mint_inference
| mint_inference | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableevan-moon/memex is public and reachablegithub.com/evan-moon/memex ↗Pass
- Package names this repository as its source@evan-moon/memex names evan-moon/memex as sourcenpmjs.com/package/@evan-moon/memex ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-20github.com/evan-moon/memex ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular package@evan-moon/memex looks like memdex-mcpFinding
- No critical advisory in the package or its dependencies128 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMake 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 your apps:
memex mcp install
This 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.
That's it. On first run, the embedding model (~450MB) downloads once to ~/.memex/models/.
Auto-recall (optional)
memex recall install
Turns 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.
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 with memex recall uninstall.
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
- 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 is
past(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 a different folder that are semantically related, "you wrote about this 124 days ago in a different context"
- 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
- 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
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 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 every MCP client on this machine
# 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
MCP server
Claude, Claude Code, Codex, Cursor
memex mcp install
It writes each client's own config file and leaves the servers already in it alone. If a client still runs an older copy of memex, it gets repointed. memex mcp path prints the server path for a client memex does not know about yet.
Available tools
| Tool | Description |
|---|---|
save_note |
Save a note, requires layer, warns if a similar note already exists, surfaces flashbacks |
search_notes |
Semantic search; supports category, tag, date_from, date_to filters; appends flashbacks for the top result |
list_notes |
List recent notes |
list_tags |
List all tags with note counts |
list_folders |
List all folders with note counts |
get_note |
Get full content and backlinks of a note by ID |
update_note |
Update title or content. Refuses past notes (with [Amendment] suggestion) and rule notes (user-only) |
delete_note |
Delete a note by ID |
get_signals |
Deterministic un-synthesized patterns (hidden_arc / stale_state / dangling_link / tag_burst) |
update_signal_status |
Triage a signal, dismiss or snooze |
list_inferences |
List synthesized hypotheses (re-checks staleness first) |
get_inference |
One inference with full provenance + change/delete markers |
mint_inference |
Persist an approved hypothesis, requires explicit confirmation |
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.
Note layers
Every note is classified into one of three layers based on mutability:
| Layer | Meaning | Claude's permission |
|---|---|---|
past |
Record of what happened, retros, meetings, decision rationale, debugging sessions | Append-only. update_note refuses, suggesting an [Amendment] note instead |
state |
Current state or plans, project progress, roadmaps, a person's current role | Freely updatable |
rule |
Behaviour guide for Claude, coding style, search policy | Claude is read-only. Only the user writes |
The CLI prints a colour-coded [past] / [state] / [rule] badge next to each note in list, search, and show.
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, 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:
| Env | Default | Behaviour |
|---|---|---|
MEMEX_FLASHBACK_DAYS |
90 |
minimum age gap, in days |
MEMEX_FLASHBACK_DIST |
0.4 |
maximum vector distance (lower = stricter match) |
MEMEX_FLASHBACK_LIMIT |
3 |
max suggestions per surface |
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.
| Env | Default | Behaviour |
|---|---|---|
MEMEX_INJECT_RULES |
enabled | Set to 0 to disable injection entirely |
MEMEX_RULES_MAX_CHARS |
8000 |
Byte budget for the injected section; overflow is truncated with a console.warn |
Updates to rule notes are picked up on the next Claude Desktop / Claude Code restart.
Configuration
Config lives at ~/.memex/config.json.
| Key | Default | Description |
|---|---|---|
vault_path |
~/Documents/Second Brain |
Directory where .md files are saved |
sources |
[] |
Additional directories to index (e.g. existing Obsidian vaults) |
aliases |
{} |
Search alias map, e.g. { "js": ["javascript", "ecmascript"] }, values can be any language to bridge across scripts |
memex config set vault-path ~/my-vault
Architecture
~/.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)
| Package | Role |
|---|---|
@memex/db |
SQLite schema, drizzle queries, sqlite-vec + FTS5 integration |
@memex/embed |
Local embedder via @huggingface/transformers |
@memex/rerank |
Local cross-encoder reranker (opt-in) |
@memex/core |
Note service shared by CLI and MCP: save, edit, search, vector indexing |
@memex/utils |
Config, path helpers, shared utilities |
@memex/mcp |
MCP server (bundled into CLI dist) |
The ecosystem
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.
flowchart TB
U([You])
subgraph I["Interfaces, talk to your tools"]
direction LR
CD[Claude Desktop]
CC[Claude Code]
CU[Cursor]
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, or any other MCP client. The tools compose through the model, never by calling each other.
Where this is going
memex is a memory engine, not a place to read. There is no window, no editor, and no screen to keep up with. Everything a person would have supervised by hand — what is still true, what a later note corrected, which notes answer a question nobody phrased the way they were written — has to be settled by the retrieval path itself, at the moment an agent asks.
The reasoning behind dropping the desktop app: a document an LLM wrote is a document nobody reads. A vault that needs curating is a vault that rots. So the target is a structure that retrieves correctly without being read and without being maintained:
| Goal | Status |
|---|---|
| Retrieval that answers the question, not the phrasing (hybrid + rerank + chunking) | shipped |
| A correction reaching every surface that returns the note it corrected | shipped |
| Signals and inferences that name what went stale, deterministically | shipped |
| Layers and templates that make a note's lifetime explicit at write time | shipped |
| Staleness settled at read time rather than by a person clearing a queue | in progress |
Evidence (derives_from) required, so a claim can be rechecked without guessing |
in progress |
Out of scope: a GUI, sync, collaboration, publishing, a plugin system, and a graph canvas.
The design record is in docs/plans/. Those documents are a
history of decisions, not a roadmap, and the ones written for the desktop app
have been removed.
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
memex MCP questions
How do I add memex MCP to Claude Code?
Run claude mcp add memex -- npx -y @evan-moon/memex in your terminal. Add --scope user to make it available in every project.
How do I add memex MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does memex MCP provide?
It exposes 13 tools, including save_note, search_notes, list_notes, list_tags, list_folders.
Does my data leave my machine?
No, everything is fully offline and nothing leaves your machine.
How do I connect it to my AI clients?
You can register memex with MCP clients like Claude, Cursor, and Codex by running a specific command.
What happens during the first run?
The embedding model, which is approximately 450MB, will download to your local directory.