obsidian-brain-mcp

Turn your Obsidian vault into a domain-specific AI brain. An MCP (Model Context Protocol) server that enables dynamic agent creation, knowledge management, and cross-agent intelligence.

Features

• Dynamic Agent Creation — Create specialized domain agents that accumulate knowledge over time
• Belief Evolution — Track how understanding changes with confidence scoring and supersede chains
• Decision Recording — Capture decisions with context, reasoning, and outcomes
• Pattern Recognition — Promote recurring patterns from accumulated decisions
• Cross-Agent Search — Search knowledge across all agents simultaneously
• Knowledge Linking — Create typed relationships between knowledge nodes across agents
• Conflict Detection — Surface contradictory beliefs within and across agents
• Memory Consolidation — Automatically archive and summarize aging knowledge
• Agent Dialogue — Generate structured dialogue material between two agents on a topic
• Note Import — Import existing Obsidian notes into agent knowledge bases

Installation

npm install -g obsidian-brain-mcp

Configuration

Set the environment variable to point to your Obsidian vault directory where agent brains will be stored:

export OBSIDIAN_BRAIN_VAULT_PATH="/path/to/your/obsidian-vault/AI Brain"

Usage with Claude Code

Add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "obsidian-brain-mcp",
      "env": {
        "OBSIDIAN_BRAIN_VAULT_PATH": "/path/to/your/obsidian-vault/AI Brain"
      }
    }
  }
}

Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | create_agent | Create a new domain agent | name, description, scope | | list_agents | List all agents with statistics | (none) | | get_agent_context | Get full knowledge context for an agent (for prompt injection) | agent | | suggest_agents | Suggest relevant agents for a given task | task | | record_decision | Record a decision with context and reasoning | agent, title, context, decision, reasoning, tags | | query_agent | Search an agent's knowledge base | agent, question | | evolve_belief | Record or evolve a belief with confidence tracking | agent, title, content, reasoning, supersedes? | | promote_pattern | Promote a recurring pattern from decisions | agent, title, description, conditions, decision_refs, confidence | | search_across_agents | Search knowledge across all agents | query | | link_knowledge | Create typed links between knowledge across agents | source_agent, source_file, target_agent, target_file, relationship | | detect_conflicts | Detect contradictory beliefs within/across agents | agent? | | consolidate_memory | Archive and summarize aging knowledge | agent, before_date?, dry_run? | | agent_dialogue | Generate dialogue material between two agents on a topic | agents (array of 2), topic | | import_notes | Import existing Obsidian notes into an agent's knowledge base | agent, note_path, import_as, title? |

Vault Structure

{OBSIDIAN_BRAIN_VAULT_PATH}/
├── _registry.md              # Agent registry
├── master/                   # Default root agent
│   ├── _agent.md
│   ├── beliefs/
│   ├── decisions/
│   ├── patterns/
│   ├── knowledge-links/
│   └── consolidations/
├── {agent-name}/
│   ├── _agent.md
│   ├── beliefs/
│   │   └── {slug}.md         # Frontmatter: confidence, formed, supersedes
│   ├── decisions/
│   │   └── {date}-{slug}.md  # Frontmatter: tags, outcome
│   ├── patterns/
│   │   └── {slug}.md         # Frontmatter: confidence, derived_from
│   ├── knowledge-links/
│   │   └── {slug}.md         # Cross-agent relationship links
│   └── consolidations/
│       └── {date}-consolidated-{timestamp}.md
└── ...

How It Works

Each agent lives as a directory in your Obsidian vault. Knowledge is stored as Markdown files with YAML frontmatter for metadata (confidence scores, timestamps, relationships, tags).

When you create an agent, it gets its own directory with subdirectories for beliefs, decisions, patterns, knowledge-links, and consolidations. As you record decisions and evolve beliefs, the agent accumulates structured knowledge that can be queried, searched, and linked across agents.

The frontmatter-based metadata system enables features like belief evolution (tracking how understanding changes over time via supersede chains), pattern promotion (elevating recurring decision patterns), and conflict detection (surfacing contradictory beliefs by comparing content across agents).

Because everything is plain Markdown, you can browse, edit, and link your agent knowledge directly in Obsidian — or any text editor.

Requirements

• Node.js >= 18.0.0
• An Obsidian vault (or any directory — Obsidian is optional but recommended for browsing)

License

MIT