claude-brain

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 -s user -- 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 -s user -- 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

Documentation

Comprehensive documentation is available in the docs/ directory:

Document	Description
API Reference	Complete HTTP API reference — 27 endpoints with request/response schemas and curl examples
Configuration	Every config option documented with types, defaults, and environment variables
Knowledge Packs	Pack format, built-in packs, custom pack creation, CLI commands
Hooks & Passive Learning	Hook system architecture, passive classification, git capture, session tracking
Code Intelligence	Tree-sitter indexing, search_code tool, supported languages, code-memory linking
Security Hardening	Authentication, TLS proxy configs, database security, incident response
Troubleshooting	16 common issues with symptoms, causes, and solutions
Production Checklist	Pre/post deployment checklists, systemd/pm2 configs, backup & recovery

Configuration

Configuration lives in ~/.claude-brain/.env. Created automatically by claude-brain setup, or on first run with defaults. See docs/CONFIGURATION.md for the full reference (40+ options).

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/
CLAUDE_BRAIN_API_KEY	API key for HTTP endpoint auth	(none)
PORT	HTTP API server port	3333

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

Security

For production deployments, see docs/SECURITY.md. Key recommendations:

• Always set CLAUDE_BRAIN_API_KEY in production — generate with openssl rand -hex 32
• Server binds to localhost only by default — use a reverse proxy for remote access
• CORS is restricted to localhost — add explicit origins via corsOrigins config
• Rate limiting is enabled by default (200 req/60s)
• All file operations are protected against path traversal

API

Claude Brain exposes an HTTP API on port 3333 (default) for programmatic access. See docs/API.md for the full reference.

# Health check
curl http://localhost:3333/api/health

# Store a memory (requires API key)
curl -X POST http://localhost:3333/api/memory \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"content": "Use ESM imports", "project": "my-app", "category": "decision"}'

# Search memories
curl "http://localhost:3333/api/search?q=imports&project=my-app" \
  -H "X-API-Key: your-key"

License

MIT