Enigma MCP
Uses an Obsidian vault as shared, plain-Markdown memory for AI agents, with tools for hybrid keyword/semantic search, reading and writing notes, following the knowledge graph, logging sessions, managing tasks, and organizing vault content.
About
An AI agent starts every session with an empty head. What Claude Code worked out yesterday is unknown to Codex today, and unknown to Claude Code itself tomorrow. Enigma gives all of them one place to remember: a folder of Markdown notes that you already open in Obsidian.
enigma-mcp is a single Rust binary that sits in front of that folder and speaks the Model Context Protocol. Every agent
that connects gets the same 25 tools: search the vault, read and write notes, follow the knowledge graph, log a session,
add a task. The notes stay yours. You can read, edit, move and back them up like any other files.
What you get that a vector database behind an MCP wrapper does not give you:
Search by words and by meaning. A keyword ranking and an embedding ranking are merged into one result list.
A graph you can open. Entities are ordinary notes under
Claude/Graph/, so Obsidian's graph view shows them.Write rules enforced in code. Agents write inside
Claude/. Anything else needs an explicit confirmation.A vault that looks after itself. One nightly run indexes new notes, suggests filing, checks health and reports.
Nothing you cannot rebuild. Every cache lives outside the vault and can be deleted and rebuilt from the notes.
Who it is for
You use more than one AI agent and want them to share what they learn.
You keep notes in Obsidian and want agents to add to them without making a mess.
You want memory that survives a new laptop: copy the vault, rebuild the caches.
Status
Version 1.3.1. Used daily on one private vault of about 1,570 notes with four agent harnesses connected at once.
Built and tested on macOS (Apple silicon), Linux and Windows: every push is linted, tested and built on all three by
GitHub Actions. Daily use so far has been on macOS only.
Scheduling uses launchd, so the schedule command is macOS only.
Windows is new in 1.3.0. It builds and passes its tests on GitHub's Windows machines, but it has not yet been used day to day on a Windows PC. Please open an issue for anything that behaves differently there.
The organizer and the Librarian change files. Run them with --dry-run first; the Librarian refuses its first real
run on a vault until you have done so.
Related MCP server: Myobscelium
Architecture
%%{init: {"theme": "base", "flowchart": {"curve": "basis"}, "themeVariables": {"primaryColor": "#101A3E", "primaryTextColor": "#F2F5FF", "primaryBorderColor": "#6FA0FF", "lineColor": "#7C9BEA", "clusterBkg": "#070B22", "clusterBorder": "#3D6BE0", "titleColor": "#C9D6FF", "edgeLabelBackground": "#070B22", "tertiaryTextColor": "#E6ECFF"}}}%%
flowchart TB
subgraph callers["Who calls it"]
agents["Agents<br/>Claude Code, Codex, OpenClaw, Hermes"]
you["You<br/>at a terminal"]
cron["Scheduler<br/>launchd, daily at 04:00"]
web["fetch and arxiv servers<br/>text from the web, untrusted"]
end
subgraph bin["enigma-mcp, one Rust binary"]
server["MCP server<br/>25 tools over stdio"]
cli["16 commands"]
lib["Librarian<br/>the nightly run"]
subgraph core["Modules"]
notes["Notes and tasks<br/>notes.rs"]
sheets["Typed sheets<br/>sheets.rs"]
vault["Write rules<br/>vault.rs"]
search["Hybrid search<br/>search.rs"]
gr["Graph<br/>graph.rs"]
indexer["Indexer<br/>indexer.rs"]
extract["Extractor<br/>extractor.rs"]
org["Organizer and mover<br/>organizer.rs, mover.rs"]
clean["Cleanup and consolidation<br/>cleanup.rs, consolidate.rs"]
end
end
subgraph truth["The vault: source of truth"]
md[("Markdown notes")]
gnotes[("Claude/Graph/<br/>one note per entity")]
sc[("Smart Connections vectors<br/>.smart-env/")]
end
subgraph state["State folder: rebuildable"]
vec[("Note and entity vectors")]
db[("graph.db")]
man[("manifest.json")]
jr[("Organizer journal")]
ls[("Librarian state")]
end
subgraph models["Models"]
emb["bge-micro-v2<br/>local embeddings"]
llm["claude or codex command<br/>tools switched off"]
end
agents -->|MCP over stdio| server
you --> cli
cron --> lib
web -.->|"clipped into notes by /clip"| md
server --> notes
server --> sheets
server --> search
server --> gr
server -->|index_brain| indexer
server -->|organize_vault, undo_move| org
server -->|consolidate_graph| clean
cli --> lib
cli --> indexer
cli --> org
cli --> clean
lib -->|"1 index"| indexer
lib -->|"2 organize"| org
lib -->|"4 cleanup, 5 consolidate"| clean
lib -->|"7 report"| vault
lib --> ls
notes --> vault
sheets --> vault
vault -->|"inside Claude/, or confirmed"| md
search -->|read| md
search --> sc
search --> vec
search --> emb
indexer --> extract
extract --> llm
indexer --> gr
indexer --> man
gr --> gnotes
gr --> db
org --> vec
org -->|"move and rewrite links"| md
org --> jr
clean --> gr
clean --> extract
class agents,you,cron outside
class web warn
class server,cli,lib entry
class notes,sheets,vault,search,gr,indexer,extract,org,clean part
class md,gnotes,sc source
class vec,db,man,jr,ls store
class emb,llm model
style callers fill:#0E1018,stroke:#8A8780,stroke-width:1px
style bin fill:#070B22,stroke:#3D6BE0,stroke-width:2px
style core fill:#0B1233,stroke:#25315F,stroke-dasharray:4 4
style truth fill:#07201A,stroke:#3E8F6A,stroke-width:1.5px
style state fill:#06202A,stroke:#2E93A8,stroke-dasharray:4 4
style models fill:#140F33,stroke:#6D58C9
classDef outside fill:#1B1D26,stroke:#C9C4B9,stroke-width:1.5px,color:#F4F2EC
classDef warn fill:#2A1014,stroke:#F0635B,stroke-width:1.5px,stroke-dasharray:5 3,color:#FFE3E0
classDef entry fill:#2447C4,stroke:#A9C4FF,stroke-width:2px,color:#FFFFFF
classDef part fill:#101A3E,stroke:#6FA0FF,stroke-width:1.5px,color:#E6ECFF
classDef lane fill:#1A2F7A,stroke:#8FB4FF,stroke-width:2px,color:#F2F5FF
classDef ask fill:#0B1130,stroke:#8FA3D6,stroke-width:1.5px,stroke-dasharray:5 3,color:#E6ECFF
classDef source fill:#12402C,stroke:#5EC28F,stroke-width:1.5px,color:#E6FFF2
classDef store fill:#0A3440,stroke:#5ED0E6,stroke-width:1.5px,color:#E3FBFF
classDef model fill:#241A52,stroke:#A78BFA,stroke-width:1.5px,color:#EFE9FF
classDef good fill:#12402C,stroke:#5EC28F,stroke-width:2px,color:#E6FFF2
classDef stop fill:#4A1014,stroke:#F0635B,stroke-width:2px,color:#FFE3E0
linkStyle default stroke:#7C9BEA,stroke-width:1.5pxArrows point from the caller to what it uses. The indexer, the organizer, cleanup, consolidation and the Librarian all take one maintenance lock before they write, so only one of them runs at a time. On GitHub you can drag and zoom each diagram.
The Markdown files are the source of truth. The state folder holds only things derived from them: the graph cache
(graph.db), note vectors and the indexing manifest. Delete it and Enigma rebuilds those, though the next index
run has the model read every note again. Two things in the folder are not derived: the organizer's undo history,
which is lost with it, and the Librarian's state, without which the next nightly run asks for
--confirm-first-run again.
More detail is in docs/architecture.md.
How search works
%%{init: {"theme": "base", "flowchart": {"curve": "basis"}, "themeVariables": {"primaryColor": "#101A3E", "primaryTextColor": "#F2F5FF", "primaryBorderColor": "#6FA0FF", "lineColor": "#7C9BEA", "clusterBkg": "#070B22", "clusterBorder": "#3D6BE0", "titleColor": "#C9D6FF", "edgeLabelBackground": "#070B22", "tertiaryTextColor": "#E6ECFF"}}}%%
flowchart LR
q(["search_brain<br/>query, tags, folder, limit"]) --> walk["Walk the vault<br/>skip .obsidian, .trash, .git"]
walk --> filt{"Tags or folder given?"}
filt -->|yes| some["Keep the matching notes"]
filt -->|no| every["Keep every note"]
some --> cand["Candidate notes"]
every --> cand
cand --> bm["Keyword ranking<br/>BM25L: k1 1.5, b 0.75, delta 0.5<br/>best 50"]
cand --> have{"A vector for each note?"}
have -->|"Smart Connections vector<br/>newer than the note"| reuse1["Use it"]
have -->|"cached with the<br/>same content hash"| reuse2["Use the cache"]
have -->|otherwise| embed["Embed now with bge-micro-v2<br/>and save to the cache"]
reuse1 --> cos["Meaning ranking<br/>cosine with the query vector<br/>best 50"]
reuse2 --> cos
embed --> cos
bm --> any{"Any keyword hits?"}
any -->|no| substr["Substring ranking<br/>title or a line contains the query<br/>best 50"]
any -->|yes| rrf
substr -.-> rrf
cos --> rrf["Rank fusion<br/>score = sum of 1 / (60 + rank)"]
rrf --> cut["Keep the first limit results"]
cut --> ex["Add an excerpt<br/>title match, matching line,<br/>or first line"]
ex --> out(["path + excerpt"])
class q,rrf entry
class out good
class filt,have,any ask
class walk,some,every,cand,cut,ex part
class bm,cos,substr lane
class reuse1,reuse2 store
class embed model
classDef outside fill:#1B1D26,stroke:#C9C4B9,stroke-width:1.5px,color:#F4F2EC
classDef warn fill:#2A1014,stroke:#F0635B,stroke-width:1.5px,stroke-dasharray:5 3,color:#FFE3E0
classDef entry fill:#2447C4,stroke:#A9C4FF,stroke-width:2px,color:#FFFFFF
classDef part fill:#101A3E,stroke:#6FA0FF,stroke-width:1.5px,color:#E6ECFF
classDef lane fill:#1A2F7A,stroke:#8FB4FF,stroke-width:2px,color:#F2F5FF
classDef ask fill:#0B1130,stroke:#8FA3D6,stroke-width:1.5px,stroke-dasharray:5 3,color:#E6ECFF
classDef source fill:#12402C,stroke:#5EC28F,stroke-width:1.5px,color:#E6FFF2
classDef store fill:#0A3440,stroke:#5ED0E6,stroke-width:1.5px,color:#E3FBFF
classDef model fill:#241A52,stroke:#A78BFA,stroke-width:1.5px,color:#EFE9FF
classDef good fill:#12402C,stroke:#5EC28F,stroke-width:2px,color:#E6FFF2
classDef stop fill:#4A1014,stroke:#F0635B,stroke-width:2px,color:#FFE3E0
linkStyle default stroke:#7C9BEA,stroke-width:1.5pxThe two rankings are merged by position, not by score, so keyword scores and similarity scores never have to be put on one scale. The substring match only runs when the keyword ranking finds nothing, for example for a single character or a query made of punctuation.
The nightly run
%%{init: {"theme": "base", "flowchart": {"curve": "basis"}, "themeVariables": {"primaryColor": "#101A3E", "primaryTextColor": "#F2F5FF", "primaryBorderColor": "#6FA0FF", "lineColor": "#7C9BEA", "clusterBkg": "#070B22", "clusterBorder": "#3D6BE0", "titleColor": "#C9D6FF", "edgeLabelBackground": "#070B22", "tertiaryTextColor": "#E6ECFF"}}}%%
flowchart LR
start(["enigma-mcp librarian"]) --> first{"Has this vault<br/>ever had a run?"}
first -->|"no, and no<br/>--confirm-first-run"| refuse["Stop: do a --dry-run first"]
first -->|yes| lk{"Maintenance lock free?"}
lk -->|no| busy["Stop: another run is writing"]
lk -->|yes| s1
subgraph steps["Seven steps; a failed step is recorded and the next still runs"]
s1["1 Index<br/>25 notes per round,<br/>up to 40 rounds"] --> s2["2 Organize<br/>move up to --max-moves,<br/>suggest the rest"]
s2 --> s3["3 Cache<br/>rebuild graph.db<br/>if anything changed"]
s3 --> s4["4 Cleanup<br/>report repairs; apply<br/>with --auto-cleanup"]
s4 --> s5["5 Consolidate<br/>propose merges,<br/>never apply"]
s5 --> s6["6 Health<br/>stale vectors, drift,<br/>orphans, cache"]
s6 --> s7["7 Report<br/>Claude/Librarian.md,<br/>last 30 kept"]
end
s7 --> done{"Did any step fail?"}
done -->|no| ok(["exit 0"])
done -->|yes| bad(["exit 1, so the<br/>scheduler can alert"])
class start entry
class ok good
class first,lk,done ask
class s1,s2,s3,s4,s5,s6,s7 lane
class refuse,busy,bad stop
style steps fill:#070B22,stroke:#3D6BE0,stroke-dasharray:4 4
classDef outside fill:#1B1D26,stroke:#C9C4B9,stroke-width:1.5px,color:#F4F2EC
classDef warn fill:#2A1014,stroke:#F0635B,stroke-width:1.5px,stroke-dasharray:5 3,color:#FFE3E0
classDef entry fill:#2447C4,stroke:#A9C4FF,stroke-width:2px,color:#FFFFFF
classDef part fill:#101A3E,stroke:#6FA0FF,stroke-width:1.5px,color:#E6ECFF
classDef lane fill:#1A2F7A,stroke:#8FB4FF,stroke-width:2px,color:#F2F5FF
classDef ask fill:#0B1130,stroke:#8FA3D6,stroke-width:1.5px,stroke-dasharray:5 3,color:#E6ECFF
classDef source fill:#12402C,stroke:#5EC28F,stroke-width:1.5px,color:#E6FFF2
classDef store fill:#0A3440,stroke:#5ED0E6,stroke-width:1.5px,color:#E3FBFF
classDef model fill:#241A52,stroke:#A78BFA,stroke-width:1.5px,color:#EFE9FF
classDef good fill:#12402C,stroke:#5EC28F,stroke-width:2px,color:#E6FFF2
classDef stop fill:#4A1014,stroke:#F0635B,stroke-width:2px,color:#FFE3E0
linkStyle default stroke:#7C9BEA,stroke-width:1.5pxEach step is independent. If one fails, its error is recorded and the later steps still run. The command exits with a non-zero code when any step failed, so a scheduler can alert you.
Features
Area | What it does |
Hybrid search | BM25L keyword ranking and embedding similarity over the same candidate notes, each cut to its best 50 and merged with reciprocal rank fusion (k = 60). Vectors written by the Obsidian Smart Connections plugin are reused while they are fresh; otherwise Enigma embeds the note itself with the same model ( |
Knowledge graph | A model reads each new or changed note and extracts six kinds of entity (person, organization, domain, topic, project, source) and six kinds of relation. Each entity is a note under |
Write rules | Every path an agent writes is resolved and checked. Writes land inside |
Typed sheets | A folder becomes a table when you put a |
Organizer | Compares each loose note with its ten most similar filed notes. When at least 70% of the vote agrees on a folder, the note can be moved; below that it becomes a suggestion in |
Librarian | The nightly run shown above. It writes a report to |
Graph cleanup | Finds mentions of deleted notes, broken relations and orphaned entities. By default it reports them. Repairs are applied only on request, and never when so many notes are missing (20 or more, and over 10% of the vault) that the vault looks only partly synced. |
Consolidation | Finds entities that are the same thing under different names, using vector similarity to pick candidates and a model to judge them. It is a preview unless you pass |
Recall skills | Nine agent skills that turn the vault into memory you can question. See Skills. |
Provisioning | One command installs a pinned set of 14 Obsidian plugins, checking every downloaded file against a SHA-256 lock before writing it, and installs the vault guides and the |
Session hooks | For Claude Code: a session-start hook loads what the vault knows about the current project, and a stop hook reminds the agent to log the session after 10 or more tool calls without one. Both stay silent on any error. |
Skills
The skills are in skills/ and are compiled into the binary. enigma-mcp skill-sync installs them.
Skill | What it does |
| Answers a question from the vault with a source on every statement, and saves the answer in |
| Builds a full briefing on a topic: summary, timeline, key concepts, open questions |
| Tells you where a project stands, from its session logs, decisions and tasks |
| Reviews what changed since the last digest: health, captures, tasks, new notes |
| Saves one web page or paper as a summarised, source-linked note in the Inbox |
| Turns material that keeps recurring in captures and logs into lasting concept notes |
| Looks through the graph for links to a topic that you probably do not have in mind |
| Records a decision in the append-only log after checking it against earlier ones |
| Checks the vault's health without changing anything, worst problems first |
Quick start
Using an AI agent? Give it this repository's link and your vault's path. AGENTS.md tells it which commands to run, which to preview first, and where to stop and ask you.
You need:
Rust 1.89 or newer.
An Obsidian vault.
The
claudeorcodexcommand on yourPATH. Enigma uses it to extract entities from notes. The default iscodex; to use Claude, setENIGMA_EXTRACTOR=claudefor the commands below and in the server's environment.uv, if you register the two companion servers:mcp-syncstarts them withuvx.The embedding model in your local Hugging Face cache. Enigma never downloads it.
macOS
git clone https://github.com/Rayhanson-Git/enigma
cd enigma
cargo build --releaseFetch the embedding model once (three files, 34 MB):
pip install -U huggingface_hub && hf download TaylorAI/bge-micro-v2 config.json tokenizer.json model.safetensorsIf your system Python refuses pip install, run it inside a virtual environment or use pipx.
Install the vault guides and the Claude/ folders. Existing files are never overwritten:
./target/release/enigma-mcp install-conventions "/path/to/vault"Optionally install the pinned Obsidian plugins. Preview first:
./target/release/enigma-mcp provision "/path/to/vault" --checkIf the list is what you want, run the same command without --check.
Register Enigma and its two companion servers (fetch and arxiv, used by /clip) with Claude Code.
--check shows what would be registered and changes nothing:
ENIGMA_VAULT_PATH="/path/to/vault" ./target/release/enigma-mcp mcp-sync --checkThen run it again without --check to register them.
Install the skills and the session hooks:
./target/release/enigma-mcp skill-sync && ./target/release/enigma-mcp hook-sync --installBuild the graph. It indexes 25 notes per run; repeat it until the output shows "remaining": 0:
ENIGMA_EXTRACTOR=claude ./target/release/enigma-mcp index "/path/to/vault"In a new agent session, call the onboard tool first.
Linux
The same commands apply. The test suite passes on Ubuntu in CI.
The schedule command is macOS only; on Linux, run enigma-mcp librarian <vault> from cron or a systemd timer.
Windows
The steps are the same, typed in PowerShell. Three things differ:
Rust needs the Visual Studio Build Tools (the "Desktop development with C++" workload), which the Rust installer offers to set up.
The program is
.\target\release\enigma-mcp.exe, and a variable is set on its own line before the command.The
schedulecommand is macOS only; runenigma-mcp.exe librarian <vault>from Task Scheduler.
git clone https://github.com/Rayhanson-Git/enigma
cd enigma
cargo build --release
pip install -U huggingface_hub; hf download TaylorAI/bge-micro-v2 config.json tokenizer.json model.safetensors
.\target\release\enigma-mcp.exe install-conventions "C:\path\to\vault"
$env:ENIGMA_VAULT_PATH = "C:\path\to\vault"
.\target\release\enigma-mcp.exe mcp-sync --check
.\target\release\enigma-mcp.exe mcp-sync
.\target\release\enigma-mcp.exe skill-sync
$env:ENIGMA_EXTRACTOR = "claude"
.\target\release\enigma-mcp.exe index "C:\path\to\vault"mcp-sync --check previews; the line after it registers. Repeat index until its output shows "remaining": 0.
Note paths are written with / inside Enigma on every system, so a note is Claude/Index.md on Windows too.
MCP client configuration
The server is the binary with no arguments. It reads its settings from environment variables and needs one:
ENIGMA_VAULT_PATH. Give each agent its own ENIGMA_AGENT_NAME so every note says who wrote it. Agents that point
at the same vault share one index without further setup, because the state folder is derived from the vault's
path. Set ENIGMA_STATE_DIR only to move that folder, and then give every agent, and the commands you run by
hand, the same value.
Claude Code. mcp-sync does this for you. By hand:
claude mcp add --scope user enigma --env ENIGMA_VAULT_PATH="/path/to/vault" -- /path/to/enigma-mcpCodex. Add to ~/.codex/config.toml:
[mcp_servers.enigma]
command = "/path/to/enigma-mcp"
[mcp_servers.enigma.env]
ENIGMA_VAULT_PATH = "/path/to/vault"
ENIGMA_AGENT_NAME = "codex"
HF_HUB_OFFLINE = "1"OpenClaw. Add under mcp.servers in ~/.openclaw/openclaw.json. Use one entry per agent, each with its own name:
{
"mcp": {
"servers": {
"enigma": {
"command": "/path/to/enigma-mcp",
"args": [],
"env": {
"ENIGMA_VAULT_PATH": "/path/to/vault",
"ENIGMA_AGENT_NAME": "openclaw",
"ENIGMA_NO_TOOL_APPLY": "1",
"HF_HUB_OFFLINE": "1"
}
}
}
}
}Claude Desktop. Add the same command and env under mcpServers in claude_desktop_config.json.
Hermes and any other client. Anything that can start a stdio MCP server works: set the command to the
enigma-mcp binary and pass the environment variables above.
Tool reference
25 tools. In the read-only profile (ENIGMA_READONLY=1) only the 15 that change nothing are offered.
Group | Tool | Purpose | Read-only |
Start |
| Call first: the constitution, the vault guide, a tool list and the graph's state | yes |
Find |
| Search by words and meaning, with optional tag and folder filters | yes |
| Search results plus the entities in them and the notes linked to those entities | yes | |
| The facts behind | yes | |
| Read one note | yes | |
| Select notes by frontmatter: project, tags, folder | yes | |
| Notes that link to a given note | yes | |
| The most recently changed notes | yes | |
| Checkbox tasks across the vault | yes | |
Write |
| A session log in | |
| One timestamped line in today's | ||
| Create a concept note in | ||
| Write any note; outside | ||
| A checkbox task in | ||
Sheets |
| Create or update one row, checked against the sheet's schema | |
| Filter and sort a sheet's rows | yes | |
| List sheets, or describe one | yes | |
Graph |
| Add new and changed notes to the graph; repeat while | |
| Look up entities by name or alias | yes | |
| Notes connected through shared entities, with the chain that links them | yes | |
| Counts of entities, edges and mentions | yes | |
| Suggest merges of duplicate entities; a preview unless | ||
Organize |
| Filing suggestions; a preview unless | |
| Put a moved note back, with its links | ||
| The latest nightly run and its health checks | yes |
Configuration
Variable | Default | Purpose |
| required | The vault the server opens |
|
| Where caches and the Librarian's state live |
|
| The name stamped on notes and sheet rows this server writes |
|
| Which model command extracts entities: |
|
| Model for extraction ( |
|
| Model for judging duplicate entities ( |
| your system account's full name | Owner name written into a new vault's constitution and guides |
|
| The settings file |
| Hugging Face defaults | Where the embedding model is looked up |
The safety settings are listed under Safety settings. Every variable is specified in spec/01-config.md.
Operator commands
These run from a terminal and are never offered to agents as tools.
Command | What it does |
| The full nightly run |
| Index notes, or rebuild |
| Only the filing step |
| Report deleted notes and orphaned entities; repair on request |
| Suggest merges of duplicate entities; apply on request |
| Check every sheet row against its schema |
| Print the context block the session-start hook uses |
| Run the retrieval benchmark |
| Install the constitution, the vault guides and the |
| Install or check the pinned Obsidian plugins |
| Register the MCP servers with Claude Code |
| Install the skills into |
| Install the session-start and stop hooks |
| Manage the nightly launchd job (macOS) |
| The indexing-only runner the |
Scheduled maintenance
First run on a real vault. Use
--dry-runand read the report before you schedule anything. A dry run writes nothing. On a vault that has never had a run, an applying run refuses to start until you pass--confirm-first-runonce by hand.
Preview the job, then install it:
enigma-mcp schedule print --job librarian "/path/to/vault"enigma-mcp schedule install --job librarian "/path/to/vault"Job | Runs |
| The full nightly run, every day at 04:00. It includes indexing. |
| Indexing only, every day at 04:30. It never moves a file. |
Install one of the two, not both; schedule refuses the second. If two runs ever overlap, a lock in the state
folder makes the second one stop instead of writing at the same time.
macOS privacy. A launchd job cannot read a vault in iCloud Drive, Desktop, Documents or Downloads unless the
enigma-mcpbinary has Full Disk Access.schedule installwarns you when the vault is in one of these places. Grant the access on purpose, keep the vault elsewhere, or start the run from a scheduler that already has access.
Trust boundaries
The
Claude/write rule is enforced by the MCP tools. The operator commands above also write elsewhere:provisionwrites Obsidian plugins and settings,install-conventionswrites guides at the vault root, and the organizer moves notes. Read their--checkor--dry-runoutput before running them on a vault you care about.Text that arrives through
fetchandarxivis untrusted. It ends up in notes, and the extractor reads whole notes. For that reason the extractor's model runs with its tools switched off by default, and the skills tell agents to treat clipped text as data, never as instructions.Enigma does not sync or back up your vault. Use whatever you already trust for that.
Retrieval quality
Measured on this build with enigma-mcp evals: 17 golden queries against the real search path and the real
embedding model, over the 29-note fixture vault in spec/fixtures/.
success@5 | success@10 | recall@5 | recall@10 | MRR |
1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
The fixture set is small and every query ranks first, so treat it as a regression guard, not as proof of quality on your notes. A harder check on a real, private vault of 1,570 notes, with 36 hand-written questions whose right answers are known:
success@5 | success@10 | MRR |
0.97 | 1.00 | 0.84 |
For your own vault, create a private golden set with ENIGMA_VAULT_PATH=<vault> enigma-mcp evals --init-live and
run ENIGMA_VAULT_PATH=<vault> enigma-mcp evals --live.
Speed
Measured on a real vault of 1,570 notes and 1,240 graph entities, on an Apple M4, in the read-only profile. Tool figures are the median and 95th percentile over repeated calls; start-up figures are the median and slowest of five runs.
Operation | Median | Slow end |
Start the server and answer | 30 ms | 60 ms |
Start the server and answer the first search | 0.81 s | 1.04 s |
| 260 ms | 524 ms |
| 257 ms | 341 ms |
| 95 ms | 133 ms |
| 36 ms | 81 ms |
| 47 ms | 62 ms |
| 11 ms | 13 ms |
| under 5 ms | under 10 ms |
| 0.1 ms | 0.3 ms |
Librarian dry run, whole vault (one run) | 1.4 s | |
Embed every note from nothing, cache deleted (one run) | 44 s |
In the same run, read_note returned all 1,570 notes without an error, including notes with Windows line endings,
an empty note and non-ASCII file names.
Repository layout
src/ the server and all commands (9,000 lines of Rust in 31 modules)
skills/ the nine agent skills, compiled into the binary
spec/ the behaviour specification the code is written from
acceptance/ one file of acceptance cases per area
constitution/ the vault guides installed by install-conventions
fixtures/ the fixture vault and golden queries used by tests and evals
tests/ 512 tests, one file per area of the specification
docs/ architecture and other guides
AGENTS.md setup instructions for AI agents
assets/ logo and diagramsContributing
cargo test && cargo clippy --all-targetsThe tests load the real embedding model, so it must be in your Hugging Face cache (see Quick start).
Behaviour is specified before it is coded. A change starts in
spec/, then the code, then a test that names the acceptance case.The Markdown stays the source of truth. Anything Enigma derives must be rebuildable from the vault.
Never point a test at a real vault. Tests use temp folders and the fixture vault only.
Never lower a floor in the eval tests to make them pass. Fix the search or fix the fixture.
More in CONTRIBUTING.md.
Safety settings
The first two are on by default. The others are off until you set them.
Setting | Effect |
| The model that reads your notes runs with no tools ( |
| The most notes one |
| Agents keep the note-writing tools but cannot run |
| The server offers only the 15 read-only tools. |
| Caps the notes one nightly run may move. |
| The nightly run applies the mechanical graph repairs itself instead of only reporting them. |
Many agents, one vault
Point every agent at the same vault, each through its own server process with its own ENIGMA_AGENT_NAME. There is
no coordinator to run.
Adding is safe at the same time.
captureandadd_taskappend.log_session,upsert_concept,write_noteandsheet_upsertcreate notes with a create-only write, so exactly one writer wins. Two agents logging the same title get two notes (TitleandTitle 2). Two agents creating the same concept end up extending one note.Every note says who wrote it. The agent's name goes into the note's frontmatter, into sheet rows and into concept update headings, so you can filter by author in Obsidian or with
query_notes.Maintenance takes turns. Indexing, organizing, consolidating and the nightly run share one lock. A second one started while the first is running stops with a clear message.
The write rule applies to everyone. Any agent can write inside
Claude/. None can write elsewhere withoutconfirm_outside_claude=true.
Going deeper
docs/architecture.md: how search, the graph, the write rules, the organizer and the Librarian work, with a map of the modules
spec/: the full behaviour specification, one file per area
spec/13-evals.md: the golden-query format and how the benchmark is scored
CHANGELOG.md: what changed in each version
Licence
MIT. Made by Harvey Rayhanson (Rayhanson-Git).
Listed in the MCP Registry as:
mcp-name: io.github.Rayhanson-Git/enigma
Available Tools
25 toolsadd_taskA
Append an open checkbox task to Claude/Tasks.md, in the format the Obsidian Tasks plugin reads. due is optional and must be YYYY-MM-DD.
Inputs: content (required), due. Returns: result
captureA
Add one timestamped line to today's note in Claude/Inbox/, for thoughts worth keeping that do not need a note of their own yet.
Inputs: content (required). Returns: result
consolidate_graphA
Ask a model which graph entities are the same thing under different names. The default is a preview that returns the suggested merges. Review them, then call with apply=true to fold each group into one canonical entity.
Inputs: apply.
context_bundleB
Search plus graph context in a single call. Returns the best-matching notes for the query, the entities those notes mention, and other notes reachable from those entities in up to hops steps.
Inputs: query (required), hops, limit.
find_entityA
Search the graph's entities by part of a name or alias, ignoring case. type optionally limits the result to person, organization, domain, topic, project or source.
Inputs: query (required), type. Returns: result
get_backlinksA
Which notes link to this one with a [[wikilink]]? Useful for seeing what already depends on a topic before you add to it.
Inputs: path (required). Returns: result
graph_statsA
How many entities, edges and mentions the graph holds.
Inputs: no named parameters.
index_brainA
Read notes that are new or have changed and add their entities and relations to the graph, using the configured model CLI. The result includes a remaining count; repeat the call until it is 0. force=true processes every note again.
Inputs: force.
librarian_statusA
Report from the most recent Librarian run: what each step did, the health checks, and how many proposals are waiting. Changes nothing; the Librarian itself is started on a schedule with enigma-mcp librarian.
Inputs: no named parameters.
list_recentA
The n notes changed most recently, latest first. A quick way to see what has been happening in the vault.
Inputs: n. Returns: result
list_tasksA
Collect checkbox tasks from every note in the vault, or from one folder. Finished tasks are left out unless include_done=true.
Inputs: folder, include_done. Returns: result
log_sessionA
Save a session log as a new note in Claude/Sessions/ and list it in Claude/Index.md. Call it when a meaningful piece of work ends, and say what happened, what was learned and what was decided.
Inputs: title (required), content (required), project (required), tags. Returns: result
onboardA
Start every new session here. Returns the vault's constitution, its guide to where things go, a short list of the tools, and the state of the graph.
Inputs: no named parameters.
organize_vaultA
Suggest where loose notes belong by comparing each one with its most similar filed notes. The default is a preview that changes nothing and lists moved, proposals and skipped. With apply=true the suggestion list is refreshed and no more than ENIGMA_MAX_MOVES notes are moved (0 unless the owner raises it); every move is journaled and undo_move reverses it.
Inputs: apply.
query_notesA
Select notes by their frontmatter: project, tags, folder, or any mix of them. Each result is a note path with its frontmatter. With no filter it returns the notes that have any frontmatter at all.
Inputs: tags, limit, folder, project. Returns: result
read_noteB
Return the text of one note. path is relative to the vault root, for example 'Claude/Index.md'.
Inputs: path (required). Returns: result
recall_bundleA
Collect, without calling a model, the facts the recall skills build on. mode='digest' lists what changed after a date (7 days ago when omitted). mode='resume' gathers session logs, decisions, open tasks and graph entities whose project contains the given text, ignoring case. A section that fails does not stop the others.
Inputs: mode (required), since, project.
search_brainA
Find notes by exact words and by meaning at once: a keyword ranking and an embedding ranking are merged into one list. Narrow it with frontmatter tags or a folder. Each result is a note path with a short excerpt, most relevant first.
Inputs: query (required), tags, limit, folder. Returns: result
sheet_queryA
Filter and sort the rows of a sheet. filters maps a column to {op: value}; the ops are eq, ne, lt, lte, gt, gte, contains, missing, in and nin, and every filter must hold. sort is {by, dir}. limit caps the number of rows.
Inputs: sheet (required), sort, limit, filters. Returns: result
sheet_schemaA
Describe sheets. Called with no sheet, it lists every sheet with its folder and number of rows. Called with a sheet, it returns that sheet's columns, types, key, identity columns and filing instructions.
Inputs: sheet.
sheet_upsertA
Add a row to a sheet, or update the row that is already there. A sheet is a folder the owner marked with a _schema.md file. Fields are checked against that schema, the existing row is located by its key and identity columns, and only the fields you pass are changed. agent is the name recorded on the row; it defaults to this server's ENIGMA_AGENT_NAME.
Inputs: sheet (required), fields (required), body, agent.
undo_moveA
Put a note the organizer moved back where it was. Pass the note's present path inside the vault; the latest move of that note is reversed, including the links that were rewritten and the note's indexing record.
Inputs: path (required).
upsert_conceptA
Keep one lasting note per concept in Claude/Concepts/. A new name creates the note; a name that already exists (letter case ignored) gets a dated update appended, so nothing is duplicated or replaced. Search before calling.
Inputs: name (required), content (required). Returns: result
write_noteA
Write a note at any path. Paths outside Claude/ are rejected unless confirm_outside_claude=true, and that flag is only for writes the user asked for in so many words. An existing note is kept unless overwrite=true.
Inputs: path (required), content (required), overwrite, confirm_outside_claude. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools target a distinct resource plus action: notes (read_note, write_note, query_notes), tasks (add_task, list_tasks), sheets (sheet_upsert/query/schema), graph (find_entity, related_notes, graph_stats, consolidate_graph) and vault maintenance (organize_vault, undo_move). The blurriest boundaries are the retrieval trio search_brain / context_bundle / recall_bundle, which all 'gather context' with different scopes, and the content-capture quartet capture / log_session / upsert_concept / write_note, which overlap in 'add prose to the vault.' Descriptions do differentiate them (digest/resume vs. search+graph vs. hybrid ranking), so confusion is limited but real.
A verb_noun convention dominates (read_note, write_note, add_task, find_entity, index_brain, consolidate_graph), but it is broken by the noun_verb sheet family (sheet_upsert, sheet_query, sheet_schema), noun_noun tools (graph_stats, librarian_status, context_bundle, recall_bundle, related_notes) and bare verbs (capture, onboard). Notably 'upsert' appears as both upsert_concept and sheet_upsert with inverted ordering. The prefixes make the families readable, but ordering is not predictable.
At 25 tools the set sits at the top of the acceptable band and feels heavy: notes, tasks, sheets, graph, search, sessions, organizing and diagnostics are all covered. Most tools earn their place in a genuinely broad vault domain, but several (recall_bundle vs context_bundle, capture vs log_session) look like they could be folded together to reduce the surface the agent must choose from.
Coverage is strong across the lifecycle: note create/read/update, task create/list, sheet upsert/query/schema, graph index/query/consolidate, hybrid search, link traversal and session logging, plus safe preview-and-apply semantics with undo. The notable gaps are deletion and task completion: there is no delete_note, no sheet row delete, and add_task/list_tasks without a way to mark a task done. These are workable around but leave the CRUD surface uneven.
Maintenance
Related MCP Connectors
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA local-first CLI and MCP server that helps you build and search a personal knowledge vault from Markdown notes, with semantic search and AI-powered features like stale note detection and session memory harvesting. It’s provider-agnostic, requires no GPU in its default mode, and exposes your vault as long-term memory to any MCP-compatible AI tool like Claude Code.47Apache 2.0
- FlicenseNot gradedqualityCmaintenanceA Python MCP server that gives Claude long-term memory and full context of everything by connecting to an Obsidian vault, enabling context retrieval, note management, and automatic graph linking.-
- AlicenseNot gradedqualityBmaintenanceA personal memory MCP server for Obsidian/markdown vaults that provides hybrid retrieval (semantic, keyword, tag, time-aware co-occurrence) and is shared across multiple AI clients.175 npmMIT
- AlicenseAqualityAmaintenanceLocal-first persistent memory for Claude Code and OpenAI Codex CLI. A single Rust binary captures, distills, searches, and injects project memory across sessions via hooks, MCP, CLI, and localhost REST.1533MIT