Enigma MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HF_HOME | No | Where the embedding model is looked up. | |
| HF_HUB_CACHE | No | Where the embedding model is looked up. | |
| ENIGMA_READONLY | No | Set to 1 so the server offers only the 15 read-only tools. | |
| ENIGMA_EXTRACTOR | No | Which model command extracts entities: codex or claude. | codex |
| ENIGMA_MAX_MOVES | No | The most notes one organize_vault(apply=true) call from an agent may move. At 0 the call refreshes suggestions and moves nothing. | 0 |
| ENIGMA_STATE_DIR | No | Where caches and the Librarian's state live. | ~/.enigma-mcp/<hash of the vault path>/ |
| ENIGMA_AGENT_NAME | No | The name stamped on notes and sheet rows this server writes. | claude |
| ENIGMA_VAULT_PATH | Yes | The vault the server opens. Required. | |
| ENIGMA_EXTRACT_MODEL | No | Model for extraction (claude only). | haiku |
| ENIGMA_NO_TOOL_APPLY | No | Set to 1 to let agents keep note-writing tools but prevent organize_vault(apply=true), consolidate_graph(apply=true) and index_brain(force=true). | |
| ENIGMA_CONSOLIDATE_MODEL | No | Model for judging duplicate entities (claude only). | sonnet |
| ENIGMA_EXTRACTOR_NO_TOOLS | No | Runs the model that reads notes with no tools so instructions hidden in a note cannot make it act. On by default; set to 0 only if you trust every note. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Enigma is the long-term memory this vault's owner shares with their AI agents: one Obsidian vault that all of them read and write.
First step in any new session: call onboard. Before your first write, read Claude/README.md; it is the constitution and its rules bind every agent.
Where things live: agents write only inside Claude/. Sessions/ holds work logs, Concepts/ holds lasting topic notes, Inbox/ holds quick captures, Tasks.md holds checkbox tasks, Decisions.md is a decision log that is only ever appended to, and Graph/ holds the entity graph. The rest of the vault is the owner's. Read any of it, but write outside Claude/ only on an explicit request; without confirm_outside_claude such a write is rejected.
Working habits: look before you conclude something is unknown (search_brain, query_notes, related_notes, find_entity). When a meaningful piece of work ends, call log_session. Use capture for passing thoughts, add_task for follow-ups, and upsert_concept for lasting knowledge, after searching, so that you extend a concept instead of duplicating it.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| read_noteB | Return the text of one note. path is relative to the vault root, for example 'Claude/Index.md'. |
| 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. |
| 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. |
| 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. |
| 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. |
| add_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. |
| list_tasksA | Collect checkbox tasks from every note in the vault, or from one folder. Finished tasks are left out unless include_done=true. |
| 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. |
| 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. |
| list_recentA | The n notes changed most recently, latest first. A quick way to see what has been happening in the vault. |
| 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. |
| 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. |
| 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. |
| related_notesA | Notes that share graph entities with the given note, directly or through up to hops steps. Strongest connections come first, at most limit results, and each one shows the chain of entities that links it. |
| graph_statsA | How many entities, edges and mentions the graph holds. |
| 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.