Obsidian MCP Server
A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your Obsidian vault. Access your notes, create content, manage tags, and search your knowledge base through natural conversation.
Features
Note Management
- CRUD Operations: Create, read, update, and delete notes (with safety confirmation)
- Write Modes: Overwrite, append, or prepend content
- Batch Reading: Read multiple notes in a single request
- File Info: Get metadata without reading content (efficient for large vaults)
- Move/Duplicate: Reorganize your vault structure
- Section Operations: Read, append, or replace specific sections by heading
Frontmatter & Tags
- Frontmatter Parsing: Get/set YAML frontmatter as structured JSON (powered by gray-matter)
- Tag Management: Add/remove tags (frontmatter or inline)
- Tag Auditing: Find notes missing required tags
- Tag Search: List all tags with usage counts
Search & Links
- Full-Text Search: Search content and filenames with context
- Backlinks: Find all notes linking to a specific note
- Broken Links: Detect wiki-links that don't resolve
- Find & Replace: Bulk text replacement with regex support
Semantic Search (optional)
- Search by meaning: hybrid vector + full-text retrieval over heading-aware chunks, backed by Postgres + pgvector and local embeddings from Ollama
- Similar notes: nearest notes to a given note, by whole-note embedding
- Incremental indexer: a second process from the same image that polls the vault and re-embeds only what changed; works over NFS/SMB where inotify does not
- Nothing leaves your network: embeddings are computed locally; the feature is off entirely unless
DATABASE_URLis set
Directory Operations
- Create/Delete/Rename: Full directory management
- List Contents: Browse vault structure
Performance
- Token Optimization: Optional compact response mode (40-60% smaller responses)
- Efficient Scanning: Get file info without reading content
- SSE Transport: Remote access without local installation
Quick Start
How clients connect: the server speaks MCP over HTTP + SSE only (there is no stdio mode). You start it (npx, Docker or from source), then point a client at http://HOST:PORT/sse. Clients that only support stdio servers connect through mcp-remote, as shown below. It listens on all network interfaces on PORT, so set an API_KEY (see Authentication) or keep it on loopback (for example -p 127.0.0.1:3001:3000 in Docker) unless you want the whole network to have read/write access to your vault.
npx (Quickest)
Requires Node.js 20.19 or newer. This starts the server in the foreground (default port 3000):
VAULT_PATH=/path/to/your/vault npx @smith-and-web/obsidian-mcp-server
With options:
VAULT_PATH=/path/to/vault PORT=3001 COMPACT_RESPONSES=true npx @smith-and-web/obsidian-mcp-server
Docker (Recommended for Production)
Using the pre-built image from GitHub Container Registry:
docker run -d \
--name obsidian-mcp \
-v /path/to/your/vault:/vault:rw \
-p 127.0.0.1:3001:3000 \
-e VAULT_PATH=/vault \
ghcr.io/smith-and-web/obsidian-mcp-server:latest
latest follows the newest release; pin a version tag (for example :1.6.0) for production. Drop 127.0.0.1: only if you set API_KEY and want other machines to connect.
Or with Docker Compose:
-
Create a
docker-compose.yml:services: obsidian-mcp: image: ghcr.io/smith-and-web/obsidian-mcp-server:latest container_name: obsidian-mcp restart: unless-stopped volumes: - /path/to/your/vault:/vault:rw ports: - "127.0.0.1:3001:3000" environment: - VAULT_PATH=/vault -
Start the server
docker compose up -d -
Verify it's running
curl http://localhost:3001/health
Local Development
-
Install dependencies
npm install -
Set environment variables
export VAULT_PATH=/path/to/your/vault export PORT=3000 -
Start the server
npm start # Or with auto-reload: npm run dev
AI Assistant Configuration
Claude Desktop
Add to your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Option 1: Local server (via mcp-remote)
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3001/sse"]
}
}
}
Option 2: Remote server with HTTPS
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-domain.com/sse"]
}
}
}
The server must already be running (see Quick Start). Claude Desktop launches mcp-remote, which bridges its stdio to the server's SSE endpoint; Claude Desktop cannot launch this server directly, because the server does not speak stdio.
Cursor
Add to your Cursor MCP settings (Settings → MCP):
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3001/sse"]
}
}
}
Other MCP Clients
Claude Code supports SSE servers directly:
claude mcp add --transport sse obsidian http://localhost:3001/sse
# with an API key:
claude mcp add --transport sse obsidian https://your-host/sse --header "Authorization: Bearer your-secret-key"
Any other MCP-compatible client can connect using mcp-remote:
npx mcp-remote http://localhost:3001/sse
Or connect directly to the SSE endpoint at http://localhost:3001/sse if the client supports SSE servers natively.
Available Tools
Note Operations
Directory Operations
Frontmatter & Tags
Search & Links
Semantic Search (only when DATABASE_URL is set)
See Semantic search for setup.
Section Operations
Architecture
┌─────────────────┐ HTTPS/SSE ┌──────────────────┐
│ Claude Desktop │ ◄────────────────► │ MCP Server │
└─────────────────┘ │ (Express.js) │
└────────┬─────────┘
│
┌────────▼─────────┐
│ VaultManager │
│ (File System) │
└────────┬─────────┘
│
┌────────▼─────────┐
│ Obsidian Vault │
│ (Markdown) │
└──────────────────┘
Project Structure
obsidian-mcp-server/
├── src/
│ ├── index.ts # Express server entry point
│ ├── vault/
│ │ ├── VaultManager.ts # Core vault operations
│ │ └── frontmatter.ts # YAML parsing utilities
│ ├── tools/
│ │ ├── definitions.ts # MCP tool schemas
│ │ ├── handlers.ts # Tool execution logic
│ │ └── index.ts # Tool exports
│ ├── server/
│ │ ├── mcp.ts # MCP protocol handlers
│ │ └── middleware.ts # Express middleware
│ ├── index/ # Optional semantic search
│ │ ├── config.ts # DATABASE_URL / OLLAMA_URL / EMBED_MODEL
│ │ ├── exclusions.ts # What the indexer never reads
│ │ ├── chunker.ts # Heading-aware chunking
│ │ ├── embedder.ts # Ollama client (+ a fake for tests)
│ │ ├── ranking.ts # Fusion, weights, per-note cap and env validation
│ │ ├── store.ts # pgvector schema, upserts, hybrid search
│ │ ├── scanner.ts # Vault walk and change detection
│ │ └── SearchService.ts # What the MCP tools call
│ ├── maintain/ # Report configuration, decisions, renderer and worker
│ ├── maintain.ts # Report-only maintenance CLI
│ ├── learn/ # Learn log, redaction, configuration and reports
│ ├── learn-report.ts # Read-only learn-report CLI
│ ├── eval/ # Golden validation, metrics and fixed ranking grid
│ ├── eval.ts # Read-only brain-eval CLI entry point
│ ├── indexer.ts # Indexer entry point (second container)
│ └── types/
│ └── index.ts # TypeScript type definitions
├── sql/001_schema.sql # Index schema (dimension substituted at start)
├── tests/ # Vitest unit tests
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md
Environment Variables
Learn log
The optional measurement layer requires semantic search and is off by default. It records the three search tools (semantic-search, similar-notes, search-vault), successful reads (read-note, read-multiple-notes, read-section), explicit feedback and session start/close with client names. Sessions are the legacy SSE stream (GET /sse + /message) and, since 1.10.1, POST /sse clients: initialize returns an Mcp-Session-Id header, later requests that echo it are logged under that session, and DELETE /sse with the header closes it. POST /sse requests without the header are logged with client name post and no session. Search ranking is unchanged; search never reads these logs.
Set LEARN_LOG=true and LEARN_REDACT_PATTERNS_FILE to a readable UTF-8 file. Blank lines and comments are ignored, whitespace is trimmed, and each other line is a JavaScript regex source compiled case-insensitively. An example file is:
# comment
\bexample-term\b
Eight built-in patterns also detect private-key headers, access-key shapes, JWTs, hosted Git tokens, secret assignments, bearer credentials, URL token parameters and 64-character hex strings. Sensitive queries (including similar-note paths) and their embeddings are cleared before storage. Sensitive string parameters become [redacted]; sensitive feedback notes are cleared, sensitive feedback paths are dropped, and sensitive read paths are never logged. Site-specific patterns belong in the external file. An invalid configuration disables logging, never search, and is reported at startup.
Logged searches return an additive requestId. Pass it to a read's optional requestId argument, then call search-feedback with requestId, rating (positive, negative, neutral) and usedPaths. expectedPaths and a short note are optional. source defaults to agent; use user only for explicit human feedback. Unknown ids return { recorded: false, reason: 'unknown requestId' }. Reads with unknown ids are recorded without a link.
Search, read and session writes are fire and forget: they never delay tool responses and failures are logged with learn-log:. Feedback is awaited. The indexer loop applies retention at most daily, excluding --once. After LEARN_RETENTION_DAYS (default 30), query text, query embeddings and feedback notes are cleared. Paths, ranks, timestamps, checked parameters, client names and feedback paths remain. sql/002_learning.sql creates the four learn tables even when logging is off; the embedding column is recreated after a dimension reset. Keep learn-table data out of database dumps and exclude raw database files from backups when query retention is required.
Run the read-only report against an existing database:
node dist/learn-report.js --days 30 --out /existing-directory/learn-report.json
--days defaults to 30 (range 1–365); the output directory must already exist. It uses a read-only connection, ignores ranking and logging environment settings, and outputs counts and rates without query text. Stdout lists dotted keys in report order, followed by VOLUME GATE: pass|fail.
The report covers the selected collection and time window. Sessions include counts by client and the median closed duration in minutes. Searches include counts by tool and redacted share. Linked semantic reads use the minimum rank of the read path: usedAt1, usedAt3, usedAt8 are shares of linked reads, and missRate is the share absent from results. linkedSearchRate is the share of semantic searches with a linked read, and linkedSemanticPerDay is their daily count. Reformulation and fallback rates count session-linked semantic searches followed within 120 seconds by another semantic search or text search. Feedback coverage is the share of semantic searches with feedback; source counts and negative rates include all feedback. Zero-denominator rates and empty medians are null; numbers are rounded to four decimals. The volume gate passes at a rounded 30 linked semantic searches per day. Feedback from agents measures compliance; user corrections provide independent labels.
Semantic search
Off by default. Setting DATABASE_URL turns it on in both the server (four extra tools) and the indexer (a second process that keeps the index current). Everything runs locally: Postgres with the pgvector extension, and Ollama for embeddings.
How it works
- The vault stays the source of truth. The index is a derivative you can drop and rebuild (
--reindex). - Chunking is heading-aware. Notes split on H1–H3; sections longer than ~800 tokens split further with overlap; each chunk carries its breadcrumb (
Title › H2 › H3). Chunk 0 is the title plus the frontmattersummary, so a one-line summary is the strongest signal for "which note answers this". - Retrieval is hybrid. Cosine similarity over an HNSW index and Postgres full-text search run side by side and are fused with configurable weighted reciprocal rank fusion (the default) or distribution-based score fusion (DBSF), so paraphrases and exact identifiers (hostnames, ticket numbers) both work.
- Change detection is a poll, not a watcher, because inotify does not propagate over NFS or SMB. The indexer stats every file each interval, hashes only files whose mtime or size moved, and re-embeds only files whose content changed.
- Exclusions are enforced by path before any read:
.obsidian/,.trash/,.git/, Synology#recycle/@eaDir/@tmp/, AppleDouble._*, dotfiles, non-.mdfiles, any directory containing a.noindexfile, and any note with frontmatterindex: false. - Links resolve like Obsidian does.
[[Areas/note]]resolves by path;[[note]]resolves if exactly one note in the vault has that basename, and stays unresolved (recorded,NULLtarget) when two do. Deleting one of two duplicates re-resolves the other the next time it is indexed. - The model is a schema fact. The embedding model and dimension are recorded in the database on first run; a different model refuses to index until
--reindex.
Evaluating search quality (brain-eval)
Build with npm run build, then run with the same database, collection and embedding
configuration as the index:
node dist/eval.js --golden /private/golden.json --grid --out /private/runs/grid.json
# Or evaluate one configuration alongside the baseline:
node dist/eval.js --golden /private/golden.json --config '{"wText":1.5,"perNoteCap":2}' --out /private/runs/candidate.json
# npm run eval -- <the same arguments> also works.
The output directory must already exist. The CLI opens the database read-only: it never
applies schema changes, reindexes or writes to the index. The embedding model and dimension
must match the stored metadata, and every expected note must already exist in the collection.
Every query is embedded once and its vector reused across configurations. The fixed grid
contains 40 configurations, starting with the v1.8.0 baseline rrf-k60-v1-t1-cap0.
The CLI ignores ambient SEARCH_* ranking settings; --config merges only the supplied
fields over the baseline. Invalid ranking environment settings fail server startup.
Golden files are private evaluation data, with exactly these keys:
{
"version": 1,
"created": "2026-01-01",
"notes": "Synthetic example only",
"queries": [
{
"id": "example-1",
"category": "exact-id",
"query": "synthetic search phrase",
"expected": ["Example.md"]
}
]
}
Query ids must be unique, query strings non-empty, and expected lists non-empty with
unique .md paths. Categories are exact-id, paraphrase, decision-why, multi-hop,
and recent, reported in that order. Unknown keys are rejected. Keep golden sets and
evaluation reports outside a public code repository.
Metrics use unique note paths in result order, after requesting eight chunks:
mrr: mean reciprocal rank of the first expected note, or zero for a miss.recall5: a hit rate at 5, meaning any expected note in the first five notes.ndcg8: binary-relevance normalised discounted cumulative gain at eight notes.distinctNotes: mean number of distinct notes returned. Metrics are also broken down by category, and the JSON report rounds them to four decimal places.
A candidate must improve MRR by at least 0.0300, preserve every category's hit rate,
and preserve every query whose baseline hit was within five. Comparisons round metrics
to integer ten-thousandths. Passing candidates are ordered by higher MRR, hit rate, then
NDCG; ties prefer fewer changed ranking fields, then the lexicographically smaller id.
If none passes, the baseline wins with changed: false. The JSON includes the golden
file's SHA-256, per-query note lists, gate reasons, and the winning environment variables;
stdout prints the ranking table, category comparison and final WINNER line.
Exit codes: 0 for a completed report (including no ranking change), 2 for input
problems (arguments, golden validation, model mismatch or missing expected paths), and
1 for other runtime failures (database, embedding service or output writes).
Searches require pgvector 0.8.0 or newer: each transaction uses strict-order iterative
HNSW scans and filtered searches raise hnsw.ef_search to 100. Default RRF scores match
v1.8.0, with exact ties ordered by chunk position then id. DBSF scores range from zero
to the sum of the two leg weights.
Frontmatter the index understands
---
title: ubuntubox — NFS mount gate # else first H1, else file name
type: area # filterable: semantic-search { type }
status: active # filterable: semantic-search { status }
tags: [infra, nas] # filterable: semantic-search { tags }
summary: One line that answers "what is this note about".
index: true # false = never indexed
---
Invalid frontmatter is reported, not hidden. A note whose --- block is not valid YAML (the usual cause is an unquoted value containing : , such as summary: Finished it: all done; quote it: summary: "Finished it: all done") is still indexed by its body, but without its metadata. The indexer logs WARN invalid frontmatter in <path>: <YAML error> when it indexes such a note and again at every start, each pass line carries invalid_frontmatter=<count>, and index-status returns invalidFrontmatter: { count, notes: [{ path, error }] } (first 20). reindex-note returns a warning. Fix the note and the flag clears on the next pass.
Setup
- Database: any Postgres 16+ with pgvector. The schema is created on first start from
sql/001_schema.sql; nothing to run by hand. HNSW index builds need shared memory: give the Postgres containershm_size: 1g. - Embeddings:
ollama pull nomic-embed-text(768-d, 8k context) orbge-m3(1024-d). - Server: add
DATABASE_URL,OLLAMA_URL,EMBED_MODEL(and optionallyINDEX_COLLECTION) to the server's environment. The/healthendpoint reportssemanticSearch: enabled. - Indexer: run the same image again with
command: ["node", "dist/indexer.js"], the same environment, and the vault mounted read-only.node dist/indexer.js --once --verbosedoes a single pass and exits non-zero if any file failed.
services:
obsidian-mcp:
image: ghcr.io/smith-and-web/obsidian-mcp-server:latest
environment:
VAULT_PATH: /vault
API_KEY: ${API_KEY}
DATABASE_URL: postgres://brain:${DB_PASSWORD}@brain-db:5432/brain
OLLAMA_URL: http://ollama:11434
EMBED_MODEL: nomic-embed-text
INDEX_COLLECTION: secondbrain
volumes:
- /path/to/vault:/vault:rw
ports: ["127.0.0.1:3001:3000"]
obsidian-indexer:
image: ghcr.io/smith-and-web/obsidian-mcp-server:latest
command: ["node", "dist/indexer.js"]
environment:
VAULT_PATH: /vault
DATABASE_URL: postgres://brain:${DB_PASSWORD}@brain-db:5432/brain
OLLAMA_URL: http://ollama:11434
EMBED_MODEL: nomic-embed-text
INDEX_COLLECTION: secondbrain
INDEX_INTERVAL_SECONDS: "60"
volumes:
- /path/to/vault:/vault:ro
brain-db:
image: pgvector/pgvector:0.8.2-pg16
shm_size: 1g
environment:
POSTGRES_DB: brain
POSTGRES_USER: brain
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- ./brain-db:/var/lib/postgresql/data
ollama:
image: ollama/ollama:latest
volumes:
- ./ollama:/root/.ollama
Indexer CLI
Security notes
- The indexer needs only read access to the vault; mount it
:ro. - Chunk text is stored in Postgres in clear. Treat the database as you treat the vault: same network boundary, same backup policy, and don't index material that should not share an access key with the rest of the vault (use
index: falseor a.noindexdirectory). - Embeddings never leave the Ollama host. No external API is involved anywhere in this feature.
API Endpoints
Authentication
The server supports optional API key authentication. When API_KEY is set, all /sse and /message endpoints require authentication. The /health endpoint remains public.
Enabling Authentication
Set the API_KEY environment variable:
# Docker
docker run -d \
--name obsidian-mcp \
-v /path/to/vault:/vault:rw \
-p 3001:3000 \
-e VAULT_PATH=/vault \
-e API_KEY=your-secret-key \
ghcr.io/smith-and-web/obsidian-mcp-server:latest
# npx
API_KEY=your-secret-key VAULT_PATH=/path/to/vault npx @smith-and-web/obsidian-mcp-server
Authentication Method
Clients send the key in the Authorization header:
Authorization: Bearer your-secret-key
The ?api_key= query parameter was removed in 1.6.0 (it ends up in access logs and client history). Clients that used it must switch to the header, for example mcp-remote with --header "Authorization: Bearer your-secret-key".
Tailscale login (optional second factor)
Behind tailscale serve on loopback, set [email protected]. Requests then also need the Tailscale-User-Login header that serve adds for tailnet users; anything else gets 403. Do not rely on this if the port is reachable any other way, because the header can be forged by a direct client.
Client Configuration with API Key
Claude Desktop / Cursor (via mcp-remote):
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://your-domain.com/sse",
"--header", "Authorization: Bearer your-secret-key"
]
}
}
}
Claude Code:
claude mcp add --transport sse obsidian https://your-domain.com/sse --header "Authorization: Bearer your-secret-key"
Security Considerations
- Generate strong keys: Use a random string of at least 32 characters
- HTTPS required: Always use HTTPS when exposing the server remotely to prevent key interception
- File Access: The server has full read/write access to the mounted vault, but every path is confined to it (paths that escape the vault, such as
../../etc/passwd, are rejected; fixed in 1.4.1) - Bind address: the server listens on all interfaces. In Docker, publish to loopback (
127.0.0.1:3001:3000) unless remote access is intended - CORS: Currently allows all origins. Restrict in production if needed
- Key in logs: only send the key in the
Authorizationheader; the old?api_key=query parameter was removed because URLs end up in access logs - Network security: Consider additional layers like VPN or firewall rules for sensitive vaults
Deployment with NGINX Proxy Manager
For remote access with SSL:
-
Add a Proxy Host:
- Domain:
obsidian.yourdomain.com - Forward Hostname:
obsidian-mcp(container name) - Forward Port:
3000 - Websockets are not required (SSE is plain HTTP); the Advanced block below is what matters
- Domain:
-
SSL Tab: Request Let's Encrypt certificate
-
Advanced Tab (for SSE):
proxy_buffering off; proxy_cache off; proxy_set_header Connection ''; proxy_http_version 1.1; chunked_transfer_encoding off;
Private access with Tailscale
If your clients are on a Tailscale tailnet you can skip the public reverse proxy entirely. Keep the container on loopback and let tailscale serve publish it with a tailnet-only HTTPS certificate:
docker run -d --name obsidian-mcp -v /path/to/vault:/vault:rw -p 127.0.0.1:3001:3000 \
-e API_KEY=your-secret-key -e [email protected] \
ghcr.io/smith-and-web/obsidian-mcp-server:latest
sudo tailscale serve --bg --https=443 http://127.0.0.1:3001
Clients then use https://<machine>.<tailnet>.ts.net/sse with the Authorization: Bearer header. Never enable Tailscale Funnel for this server. See Tailscale login for what REQUIRE_TAILSCALE_LOGIN does and does not protect against.
Troubleshooting
Container Issues
# View logs
docker-compose logs -f obsidian-mcp
# Restart
docker-compose restart
# Rebuild
docker-compose up -d --build
Vault Access
# Check host mount
ls -la /path/to/your/vault
# Check container access
docker exec obsidian-mcp ls -la /vault
Connection and auth errors
401 Unauthorized: missing or wrongAuthorization: Bearer <key>header (the?api_key=query parameter is no longer accepted).403 Forbidden:REQUIRE_TAILSCALE_LOGINis set and the request did not arrive throughtailscale serveas that user.Path escapes vault: the requested path resolves outsideVAULT_PATH; use a path relative to the vault.- Search results are missing a note's
summary, tags or type filters: checkindex-statusforinvalidFrontmatter(or the indexer log forWARN invalid frontmatter); the note's YAML is invalid and was indexed without its metadata. - SSE connection drops behind a reverse proxy: turn proxy buffering off (see the NGINX block above), check the certificate, and verify the firewall allows the port.
- Claude Desktop starts but shows no tools: the server must already be running and the config must use
mcp-remote(the server has no stdio mode).
Development
Quick Start
# Clone and install
git clone https://github.com/smith-and-web/obsidian-mcp-server.git
cd obsidian-mcp-server
make install
# Run with example vault
make dev
# Test connection
make test-connection
Available Commands
Run make help to see all available commands:
Development:
make install Install dependencies
make dev Run server with hot-reload
make start Run server in production mode
make test-connection Test server connectivity
Docker:
make docker-build Build Docker image
make docker-up Start Docker container
make docker-down Stop Docker container
make docker-logs View container logs
make docker-restart Restart container
make docker-shell Open shell in container
API Testing with Bruno
The repository includes a Bruno collection for testing the core tools (the four semantic-search tools need DATABASE_URL and a running index).
- Install Bruno (free, open-source API client)
- Open the collection from
./bruno/obsidian-mcp - Select the
localorremoteenvironment - Run requests to test each tool
The collection is organized by category:
health/- Server health and tool listingnotes/- Note CRUD operationsdirectories/- Directory operationsfrontmatter/- Frontmatter operationstags/- Tag managementsearch/- Search and find-replacelinks/- Backlinks and broken linkssections/- Section-based operations
Example Vault
An example vault is included in ./examples/test-vault/ for development and testing. It includes sample notes with tags, links, and sections to test all features.
Contributing
See CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE for details.
Related Projects
- Model Context Protocol - Protocol specification
- Obsidian - Knowledge base application
- Claude - AI assistant by Anthropic
Maintenance worker
Run node dist/maintain.js (or npm run maintain) from the same image as the server, with DATABASE_URL, INDEX_COLLECTION, VAULT_PATH and MAINTAIN_REPORT_DIR configured. Schedule it weekly with your host's scheduler. --dry prints candidate counts and hygiene metrics without recording a run or writing a report. The index must already exist.
Seven deterministic checks find missing links, unlinked mentions, uniquely repairable unresolved links, missing index or aliases frontmatter, stale summaries, near-duplicates and stale project or area hubs. Notes with type journal or inbox are excluded as targets. Notes under Journal/ get no link suggestions in either direction. An unlinked mention counts only in a note's prose (not its frontmatter, first H1, code, wikilinks or markdown links) and only as a whole word, case-insensitively, with hyphens part of the word; the worker reads the source note from VAULT_PATH to check. Near-duplicate pairs skip notes that already link to each other and pairs of plan notes. The indexer records summary/body cosine history when content changes, and maintenance backfills baselines for older notes. Search ranking stays unchanged, and maintenance never reads learn tables.
Each ISO week produces Brain maintenance YYYY-Www.md in the configured output directory. Reports are draft notes with index: false, stable finding ids, accept/reject checkboxes, trends and acceptance counts. They stay out of search and the link graph. A rerun parses ticks first and atomically replaces only that week's report; moved reports are still discovered by their maintenance_report frontmatter.
Tick one checkbox per finding, or explicitly ask the assistant to call maintenance-decision with finding: "f17", decision: "accept" or "reject", and an optional reason. Conflicting ticks record no decision. A checkbox never overrides an earlier decision; an explicit tool call may change one. Rejected findings are never proposed again. Fixed findings resolve without counting as acceptance. New findings are capped per class, with at most 50 open findings listed in a report.
This stage is report-only: accepting records a decision and changes no note. Apply accepted findings yourself. Near-duplicate merges and hub reviews remain report-only permanently. The worker never edits existing notes; its only vault write is its own report.
recommend-notes takes 1–10 positive paths, up to 10 negative paths, an optional integer k (1–50), type and directory. It excludes the examples. best_score compares the nearest positive and negative; average_vector uses the positive mean, moved away from the negative mean when present. Neither tool requires learn logging; sensitive decision reasons are stored as null using the active redaction patterns or the built-ins.
