Skip to main content
Glama

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

Arrows 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.5px

The 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.5px

Each 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 (TaylorAI/bge-micro-v2, 384 dimensions), so the two never mix.

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 Claude/Graph/, mirrored into SQLite for fast traversal. related_notes follows shared entities for up to N hops and shows the chain behind every result.

Write rules

Every path an agent writes is resolved and checked. Writes land inside Claude/ unless the call passes confirm_outside_claude=true. New notes are created with an atomic create-only write, and nothing is replaced unless the call passes overwrite=true.

Typed sheets

A folder becomes a table when you put a _schema.md in it. sheet_upsert checks every field against that schema and sheet_query filters and sorts rows with ten operators.

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 Claude/Organizer.md, which you dismiss by ticking a box. Suggestions you ignore expire after 15 days. Every move rewrites inbound links, is journaled, and can be reversed with undo_move.

Librarian

The nightly run shown above. It writes a report to Claude/Librarian.md and keeps the last 30.

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

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 Claude/ folders. --check reports drift without changing anything.

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

/recall

Answers a question from the vault with a source on every statement, and saves the answer in Claude/Answers/

/dossier

Builds a full briefing on a topic: summary, timeline, key concepts, open questions

/resume

Tells you where a project stands, from its session logs, decisions and tasks

/digest

Reviews what changed since the last digest: health, captures, tasks, new notes

/clip

Saves one web page or paper as a summarised, source-linked note in the Inbox

/distill

Turns material that keeps recurring in captures and logs into lasting concept notes

/connections

Looks through the graph for links to a topic that you probably do not have in mind

/decide

Records a decision in the append-only log after checking it against earlier ones

/rounds

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 claude or codex command on your PATH. Enigma uses it to extract entities from notes. The default is codex; to use Claude, set ENIGMA_EXTRACTOR=claude for the commands below and in the server's environment.

  • uv, if you register the two companion servers: mcp-sync starts them with uvx.

  • 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 --release

Fetch the embedding model once (three files, 34 MB):

pip install -U huggingface_hub && hf download TaylorAI/bge-micro-v2 config.json tokenizer.json model.safetensors

If 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" --check

If 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 --check

Then 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 --install

Build 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 schedule command is macOS only; run enigma-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-mcp

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

onboard

Call first: the constitution, the vault guide, a tool list and the graph's state

yes

Find

search_brain

Search by words and meaning, with optional tag and folder filters

yes

context_bundle

Search results plus the entities in them and the notes linked to those entities

yes

recall_bundle

The facts behind /digest and /resume, gathered without calling a model

yes

read_note

Read one note

yes

query_notes

Select notes by frontmatter: project, tags, folder

yes

get_backlinks

Notes that link to a given note

yes

list_recent

The most recently changed notes

yes

list_tasks

Checkbox tasks across the vault

yes

Write

log_session

A session log in Claude/Sessions/, listed in Claude/Index.md

capture

One timestamped line in today's Claude/Inbox/ note

upsert_concept

Create a concept note in Claude/Concepts/, or append to the one that exists

write_note

Write any note; outside Claude/ only with confirm_outside_claude=true

add_task

A checkbox task in Claude/Tasks.md, with an optional due date

Sheets

sheet_upsert

Create or update one row, checked against the sheet's schema

sheet_query

Filter and sort a sheet's rows

yes

sheet_schema

List sheets, or describe one

yes

Graph

index_brain

Add new and changed notes to the graph; repeat while remaining is above 0

find_entity

Look up entities by name or alias

yes

related_notes

Notes connected through shared entities, with the chain that links them

yes

graph_stats

Counts of entities, edges and mentions

yes

consolidate_graph

Suggest merges of duplicate entities; a preview unless apply=true

Organize

organize_vault

Filing suggestions; a preview unless apply=true, and then capped by ENIGMA_MAX_MOVES

undo_move

Put a moved note back, with its links

librarian_status

The latest nightly run and its health checks

yes

Configuration

Variable

Default

Purpose

ENIGMA_VAULT_PATH

required

The vault the server opens

ENIGMA_STATE_DIR

~/.enigma-mcp/<hash of the vault path>/

Where caches and the Librarian's state live

ENIGMA_AGENT_NAME

claude

The name stamped on notes and sheet rows this server writes

ENIGMA_EXTRACTOR

codex

Which model command extracts entities: codex or claude

ENIGMA_EXTRACT_MODEL

haiku

Model for extraction (claude only)

ENIGMA_CONSOLIDATE_MODEL

sonnet

Model for judging duplicate entities (claude only)

ENIGMA_OWNER

your system account's full name

Owner name written into a new vault's constitution and guides

CLAUDE_SETTINGS_PATH

~/.claude/settings.json

The settings file hook-sync reads and edits

HF_HOME, HF_HUB_CACHE

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

enigma-mcp librarian <vault> [--dry-run] [--max-moves N] [--auto-cleanup]

The full nightly run

enigma-mcp index <vault> [--batch N] [--force] [--retry-failures] [--rebuild-only]

Index notes, or rebuild graph.db from the Markdown

enigma-mcp organize <vault> [--dry-run]

Only the filing step

enigma-mcp cleanup <vault> [--apply-repairs] [--apply-retirements]

Report deleted notes and orphaned entities; repair on request

enigma-mcp consolidate <vault> [--apply]

Suggest merges of duplicate entities; apply on request

enigma-mcp sheets --check <vault>

Check every sheet row against its schema

enigma-mcp recall --vault <vault> --context [--project P]

Print the context block the session-start hook uses

enigma-mcp evals [--vault V] [--live] [--json]

Run the retrieval benchmark

enigma-mcp install-conventions <vault>

Install the constitution, the vault guides and the Claude/ folders

enigma-mcp provision <vault> [--check]

Install or check the pinned Obsidian plugins

enigma-mcp mcp-sync [--check]

Register the MCP servers with Claude Code

enigma-mcp skill-sync [--check] [--force]

Install the skills into ~/.claude/skills

enigma-mcp hook-sync [--check | --install]

Install the session-start and stop hooks

enigma-mcp schedule install|uninstall|print --job index|librarian [vault]

Manage the nightly launchd job (macOS)

enigma-mcp index-nightly <vault>

The indexing-only runner the index job uses

Scheduled maintenance

First run on a real vault. Use --dry-run and 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-run once 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

librarian

The full nightly run, every day at 04:00. It includes indexing.

index

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-mcp binary has Full Disk Access. schedule install warns 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: provision writes Obsidian plugins and settings, install-conventions writes guides at the vault root, and the organizer moves notes. Read their --check or --dry-run output before running them on a vault you care about.

  • Text that arrives through fetch and arxiv is 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 initialize

30 ms

60 ms

Start the server and answer the first search

0.81 s

1.04 s

search_brain (272 queries)

260 ms

524 ms

context_bundle

257 ms

341 ms

recall_bundle

95 ms

133 ms

query_notes

36 ms

81 ms

get_backlinks

47 ms

62 ms

list_recent

11 ms

13 ms

find_entity, related_notes, graph_stats

under 5 ms

under 10 ms

read_note

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 diagrams

Contributing

cargo test && cargo clippy --all-targets
  • The 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

ENIGMA_EXTRACTOR_NO_TOOLS (on)

The model that reads your notes runs with no tools (claude --tools "" --strict-mcp-config, codex exec --sandbox read-only), so instructions hidden in a note cannot make it act. Set it to 0 only if you trust every note.

ENIGMA_MAX_MOVES (0)

The most notes one organize_vault(apply=true) call from an agent may move. At 0 the call refreshes suggestions and moves nothing.

ENIGMA_NO_TOOL_APPLY=1

Agents keep the note-writing tools but cannot run organize_vault(apply=true), consolidate_graph(apply=true) or index_brain(force=true). Only you, at the terminal, or the nightly run can.

ENIGMA_READONLY=1

The server offers only the 15 read-only tools.

librarian --max-moves N

Caps the notes one nightly run may move. 0 means suggest only.

librarian --auto-cleanup or ENIGMA_AUTO_CLEANUP=1

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. capture and add_task append. log_session, upsert_concept, write_note and sheet_upsert create notes with a create-only write, so exactly one writer wins. Two agents logging the same title get two notes (Title and Title 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 without confirm_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 tools
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.

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

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

    A3.6/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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.
      47
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      A 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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 npm
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Local-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.
      15
      33
      MIT