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

``bash


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:

`bash
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

`bash


Clone and install dependencies

git clone
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

`bash


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

$3


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

$3

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

$3

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

$3

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

$3

| 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