Obsidian Brain

A local second brain for AI assistants: searchable Markdown memory, guarded write-back, a visual map and an optional CPU companion.

Keep knowledge in ordinary notes. Brain combines keyword and semantic search, reads complete sources, and saves evidence-bearing memories through MCP. The assistant skill helps resume projects without repeating old work.

New here? Read how the stack fits together, then start below. No personal notes, weights or production databases are included.

Cross-project learning: use one shared Brain

The Brain can be a shared knowledge hub for multiple projects and agents. A lesson learned in one application can be retrieved while working in another repository. The current project folder does not limit the server's search: it searches the configured vault and project-document roots.

For example, Sample Alpha has a worker-recovery procedure. Sample Beta is a different application with a similar background-worker problem. Beta's agent can find Alpha's lesson by searching the underlying problem, compare the conditions, and verify the approach in Beta. The included examples are fictional; they do not claim a real application was tested.

To enable this across your own projects:

1. Run one shared Brain instance for the projects that should share knowledge. Point every participating MCP client at the same endpoint, VAULT_PATH and PROJECTS_PATH. The automatic setup generates a matching mcp-server.json.

2. Install the Brain skill. Merge these project instructions into each participating project's AGENTS.md, preserving existing instructions. Automatic setup also puts a copy at <state>/PROJECT-INSTRUCTIONS.md; it does not edit your repos.

3. Tell the agent your memory-write preference. To enable routine learning, you can explicitly instruct it: "During my authorized project work, save useful decisions, verified fixes, failed attempts and reusable lessons to the shared Brain. Read-only, private and no-save instructions override this preference."

4. Recall the current project's checkpoint, then search the problem pattern across shared lessons. Remove the current project-name/folder restriction for this second search. Read the full lesson and check its evidence, platform, version and applicability before using it.

5. Verify the approach in the target project. Save its actual outcome in that project's checkpoint, and update the reusable lesson when there is meaningful new evidence. Keep project-specific settings out of a universal procedure.

A useful vault layout is:

Cowork/Projects/    # Per-project checkpoints and current state
Cowork/Patterns/    # Reusable procedures
Cowork/Gotchas/     # Failed approaches, pitfalls and retry conditions
Cowork/Examples/    # Worked examples with evidence

Folder names are configurable conventions. Typed memory saves use these Cowork folders by default. Preserve the originating project, evidence/sources, applies_when, limitations and links to relevant checkpoints. Read an existing lesson before revising it with its current hash rather than adding duplicates.

Ask your MCP-connected assistant to make these calls against the sample vault:

obsidian_search(query="Sample Beta", roots="vault", include="Projects", mode="current")
obsidian_search(query="worker crash recovery persistent pause", roots="vault", include="Patterns,Gotchas,Examples", mode="current")
obsidian_get_note(path="Cowork/Patterns/owned-worker-recovery.md", root="vault")

Or, with the example indexer running, try the read-only demonstration:

.\.venv\Scripts\python.exe examples/cross_project_demo.py

It changes between two disposable caller directories and retrieves the same Alpha-origin lesson through HTTP, then reads its complete example source. Use --url http://127.0.0.1:5180 to select the example indexer. It does not save notes or evaluate whether an autonomous agent follows the workflow correctly.

Graphify reveals possible connections; Atlas provides a map and review suggestions. The transfer happens when an agent retrieves, checks and applies the lesson. The Brain does not automatically ingest every chat or retrain a model. Sharing lessons does not authorize editing another project's files or starting its services. Search filters are not access controls: use separate vaults/Brain instances for projects that must not share information.

Already installed? Pull this update, rerun scripts/sync_skill.py --apply, and merge the template into your project instructions. Keep your existing shared MCP entry and vault; no model replacement, index rebuild or new per-project server is needed.

Related MCP server: mor

Quick start

For the complete Windows background setup—including sign-in startup, crash recovery and daily semantic graph refresh—follow Automatic setup.

Use Python 3.11 or 3.12. In PowerShell:

git clone https://github.com/CaptainKeat/obsidian-brain.git
cd obsidian-brain
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install torch==2.12.1 --index-url https://download.pytorch.org/whl/cpu
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe rag_indexer.py

The first run downloads an embedding model and indexes examples/vault plus examples/projects. Leave the terminal running. In another PowerShell window:

Invoke-RestMethod http://127.0.0.1:5180/health
Invoke-RestMethod "http://127.0.0.1:5180/search?q=sample&k=3"

Stop with Ctrl+C. On macOS/Linux, use python3 -m venv .venv and .venv/bin/python instead of the Windows executable. Python entry points are portable; .bat, .ps1 and .vbs launchers are Windows-specific.

Try guarded memory revisions without dependencies or model downloads:

python examples/revision_demo.py

This uses a disposable synthetic vault and checks that stale hashes are rejected.

Connect an MCP assistant

Start the indexer, then configure your client with the environment's Python and absolute adapter path. For clients using mcpServers:

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "C:/path/to/obsidian-brain/.venv/Scripts/python.exe",
      "args": ["C:/path/to/obsidian-brain/obsidian_brain_mcp.py"],
      "env": {"RAG_URL": "http://127.0.0.1:5180"}
    }
  }
}

Replace paths for your machine. Tools are obsidian_search, obsidian_get_note, obsidian_save_memory, obsidian_update_note, obsidian_record_feedback, obsidian_save_note and obsidian_health. The Windows adapter can try start-rag.bat when down; explicit startup is recommended with custom roots. Other platforms need explicit startup. The basic commands do not install tasks; the optional Windows installer adds them explicitly.

For Codex, review and install the skill:

.\.venv\Scripts\python.exe scripts/sync_skill.py --apply

Default target: ~/.codex/skills/obsidian-brain. Supply repeated --target <directory> for other clients. Files get backups, unrelated files stay intact; omitting --apply only checks drift. Configure your own routine-write authorization; this skill does not inherit anyone else's personal permissions.

Configure your own vault

Set matching VAULT_PATH and PROJECTS_PATH for both indexer and MCP adapter. Shell variables do not automatically transfer to desktop client configuration. The engine does not load .env files automatically.

Vault Markdown is watched live. Project docs refresh at startup or explicit POST /reindex. Health exposes scan timestamps/errors. Changing embedding models may rebuild the database when dimensions change; use a separate DB_PATH to experiment. mode=current hides explicitly stale/expired/superseded notes; mode=all includes history. Read full latest applicable notes before acting.

Upgrading an older checkout? Select a fresh DB_PATH once for this release's chunking fix. Preserve the old index for recovery; ordinary /reindex skips unchanged files and does not regenerate their existing vectors.

Add the visual companion

.\.venv\Scripts\python.exe neural-atlas/configure.py
.\.venv\Scripts\python.exe neural-atlas/atlas.py serve

Open http://127.0.0.1:5190. This starts a synthetic graph/source demo. The map uses Python's standard library. Brain search requires the separate indexer; CPU triage requires a separately installed pinned Laya runtime/model and reports unavailable weights until configured. See Atlas setup and Graphify integration.

Checks and status

.\.venv\Scripts\python.exe -B -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -B -m unittest discover -s neural-atlas/tests -v
.\.venv\Scripts\python.exe scripts/check_recall.py --report recall-report.json
.\.venv\Scripts\python.exe examples/cross_project_demo.py

The backend and automation suites have 64 tests for memory/revision contracts, retrieval, incremental refresh, rollback, guarded digest updates and startup ownership. Atlas has 26 temporary-vault, HTTP and supervisor tests using a fake classifier. The read-only recall checker accepts JSON --cases; keep reports outside indexed roots. Release notes record validation.

This source release passed a fresh Windows dependency install, default embedding startup, CPU inference and real scheduled-task checks. First-time Laya weight download, classification quality and an actual sign-in/reboot remain separate checks. Core versions are pinned; verification details record the tested scope. Other platforms still need their own checks.

For connection errors, check /health, scan errors, root configuration and the indexer terminal. Allow slow model startup to finish before retrying. Back up private generated state separately. Services bind to loopback for trusted local clients; they are not authenticated public servers. See SECURITY.md. Original code is MIT; dependencies/models retain their own licenses.

Native Obsidian graph connections

Typed memories now link to a stable hub for their explicit project label, and to verified existing vault-note sources. This keeps native graph navigation connected while preserving Brain metadata identities and historical content. Semantic search and Graphify remain separate from Obsidian's internal-link graph.

Existing users: read the safe update and graph repair guide. It includes a dry-run historical migration, external backups, hash-checked rollback, client reconnection and validation. No database/model rebuild is required. For an agent-assisted upgrade, use the guide's copyable update and reconciliation prompt.