Claude Brain

A locally-running development assistant that bridges Obsidian knowledge vaults with Claude Code through the Model Context Protocol (MCP).

Features

• Eliminates repetitive context explanations to Claude Code
• Maintains project memory across sessions using Obsidian vault
• Semantic memory system learns from past decisions (ChromaDB + SQLite)
• 25 MCP tools for context retrieval, memory storage, and intelligence
• Knowledge graph connecting technologies, decisions, and concepts
• Episodic memory with session detection and extractive summarization
• Hybrid retrieval with BM25 + semantic fusion and cross-encoder reranking
• Temporal intelligence for decision timelines, evolution tracking, and trend detection
• Multi-hop reasoning with chain retrieval and what-if analysis
• Predictive intelligence with context-aware recommendations
• Cross-project intelligence for pattern discovery and knowledge transfer
• Semantic caching with cosine similarity matching for fast repeated queries
• Event-driven orchestrator for automatic file change handling
• Automatic duplicate prevention for decisions (>90% similarity detection)
• Zod-validated tool inputs for robust error handling
• Runs completely locally with zero cloud dependencies
• Compiles to single portable executable

Quick Start

# Install globally (requires Bun)
bun install -g claude-brain

# Interactive setup (vault path, log level, installs ~/.claude/CLAUDE.md)
claude-brain setup

# Register with Claude Code
claude mcp add claude-brain -- bunx claude-brain@latest

That's it. Every Claude Code session now has 25 brain tools available.

Zero-Install Alternative

Skip the global install — just register with Claude Code directly:

claude mcp add claude-brain -- bunx claude-brain@latest

On first run, ~/.claude-brain/ is auto-created with default config.

Prerequisites

• Bun >= 1.0.0
• An Obsidian vault (or any markdown folder)

CLI Commands

| Command | Description | |---------|-------------| | claude-brain | Start MCP server (default) | | claude-brain setup | Interactive setup wizard (run once per machine) | | claude-brain install | Register as MCP server in Claude Code | | claude-brain uninstall | Remove MCP server from Claude Code | | claude-brain update | Update package and refresh CLAUDE.md to latest | | claude-brain health | Run health checks | | claude-brain diagnose | Run diagnostics | | claude-brain version | Show version | | claude-brain help | Show help |

Configuration

Configuration lives in ~/.claude-brain/.env. Created automatically by claude-brain setup, or on first run with defaults.

| Variable | Description | Default | |----------|-------------|---------| | VAULT_PATH | Path to your Obsidian vault | ~/.claude-brain/vault | | LOG_LEVEL | Log level (debug/info/warn/error) | info | | NODE_ENV | Environment | production | | CLAUDE_BRAIN_HOME | Override home directory | ~/.claude-brain/ |

Development

# Clone and install dependencies
git clone <repo-url>
cd claude-brain
bun install

# Start dev server (uses local ./data, ./logs)
bun run dev

# Run tests
bun test

# Run tests in watch mode
bun test --watch

The dev script sets CLAUDE_BRAIN_HOME=. so all data stays in the project directory.

Building

# Build standalone executable for current platform
bun run build:binary

# Build for all platforms (Windows, macOS, Linux)
bun run build:all

Project Structure

claude-brain/
├── src/
│   ├── index.ts              # Entry point (thin wrapper)
│   ├── cli/
│   │   ├── bin.ts            # CLI entry point (claude-brain command)
│   │   ├── auto-setup.ts     # First-run home directory initialization
│   │   └── commands/         # serve, install-mcp, uninstall-mcp, update
│   ├── config/
│   │   ├── home.ts           # ~/.claude-brain/ path resolution
│   │   ├── loader.ts         # Config loading (defaults → file → env)
│   │   └── schema.ts         # Zod config schemas
│   ├── server/               # MCP server code
│   │   └── handlers/tools/   # 25 tool handlers with Zod validation
│   ├── vault/                # Obsidian integration
│   ├── memory/               # Vector DB & embeddings
│   │   ├── chroma/           # ChromaDB integration with duplicate detection
│   │   ├── episodic/         # Session detection & episode management
│   │   └── consolidation/    # Memory importance scoring & archival
│   ├── knowledge/            # Knowledge graph & entity extraction
│   │   └── graph/            # In-memory graph with search & auto-population
│   ├── retrieval/            # Hybrid search (BM25 + semantic + reranking)
│   ├── temporal/             # Timeline construction & trend detection
│   ├── reasoning/            # Multi-hop chain retrieval & what-if analysis
│   ├── prediction/           # Decision prediction & recommendations
│   ├── cross-project/        # Cross-project pattern discovery & transfer
│   ├── optimization/         # Semantic caching & precomputation
│   ├── orchestrator/         # Event-driven coordination system
│   ├── setup/                # Interactive setup wizard
│   ├── context/              # Context assembly
│   ├── tools/                # MCP tool definitions & registry
│   └── utils/                # Shared utilities
├── assets/
│   └── CLAUDE.md             # Protocol file (shipped with npm package)
├── tests/                    # 750+ tests
└── ~/.claude-brain/          # User data (created at runtime)
    ├── .env                  # Configuration
    ├── data/                 # SQLite + ChromaDB
    ├── logs/                 # Log files
    └── vault/                # Default vault location

Architecture Highlights

Event-Driven Orchestrator

The orchestrator automatically responds to file changes in your vault:

• Detects new decisions in decisions.md files
• Triggers automatic semantic indexing
• Coordinates between vault, memory, and context systems

Duplicate Prevention

When storing decisions, the system:

• Searches for existing decisions with >90% semantic similarity
• Returns existing ID if duplicate found (prevents bloat)
• Logs skipped duplicates for transparency

Input Validation

All tool inputs are validated using Zod schemas:

• Clear error messages for invalid parameters
• Type-safe extraction of validated inputs
• Consistent validation across all 25 tools

Embedding Cache

Uses SHA-256 hashing for cache keys to prevent collisions (improved from simple hash).

MCP Tools (25 total)

| Category | Tools | |----------|-------| | Context Retrieval | get_project_context, smart_context, recall_similar, get_code_standards, get_phase12_status | | Memory Storage | remember_decision, auto_remember, recognize_pattern, record_correction, update_progress | | Project Management | list_projects, create_project, init_project | | Knowledge Graph | search_knowledge_graph, get_episode, list_episodes | | Patterns & Corrections | get_patterns, get_corrections | | Feedback | rate_memory | | Advanced Intelligence | get_decision_timeline, analyze_decision_evolution, detect_trends, what_if_analysis, get_recommendations, find_cross_project_patterns |

License

MIT