claude-brain 0.15.2 → 0.17.0

package/README.md

@@ -1,191 +1,191 @@
-# 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](https://bun.sh) >= 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 <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
-
-```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
-
-### 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
+# 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](https://bun.sh) >= 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 <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
+
+```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
+
+### 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

package/VERSION

@@ -1 +1 @@
-0.15.2
+0.17.0

package/assets/CLAUDE-unified.md

@@ -1,11 +1,11 @@
-# Claude Brain
-
-Call `brain()` with what you are doing. The server handles the rest.
-
-Examples:
-- brain("starting work on the auth system")
-- brain("decided to use JWT because sessions don't scale")
-- brain("finished the login page, next is the dashboard")
-- brain("what auth patterns have we used?")
-- brain("the bug was a race condition, fixed by adding a mutex")
-- brain("React vs Vue for the new project?")
+# Claude Brain
+
+Call `brain()` with what you are doing. The server handles the rest.
+
+Examples:
+- brain("starting work on the auth system")
+- brain("decided to use JWT because sessions don't scale")
+- brain("finished the login page, next is the dashboard")
+- brain("what auth patterns have we used?")
+- brain("the bug was a race condition, fixed by adding a mutex")
+- brain("React vs Vue for the new project?")

package/assets/CLAUDE.md

@@ -1,11 +1,29 @@
-# Claude Brain
-
-Brain works automatically in the background — you don't need to call it.
-
-Use the `brain` tool ONLY when you want to:
-- Explicitly store a decision: "I decided to use Redis for caching"
-- Ask a specific question: "What did we decide about auth?"
-- Update something: "Changed my mind, use Postgres instead"
-- Delete something: "Remove the note about migrations"
-
-Everything else (session tracking, file captures, git commits, context loading) happens automatically via invisible PostToolUse and Stop hooks in ~/.claude/settings.json. These hooks silently capture tool events and store patterns, decisions, and corrections without any explicit brain() call.
+# Claude Brain
+
+You have persistent memory via the `brain` tool. It remembers across sessions.
+
+## Session Start
+At the beginning of significant work sessions, check what you know:
+- `brain("What do I know about this project?")` — recalls past decisions, preferences, lessons
+
+## During Work
+Call brain when you make or encounter something worth remembering:
+- Decisions: `brain("I decided to use JWT over sessions because the app is stateless")`
+- Mistakes: `brain("The bug was caused by missing CORS credentials — fixed with credentials: include")`
+- Preferences: `brain("User prefers explicit error messages over generic 500s")`
+- Updates: `brain("Changed my mind, use Postgres instead of MySQL")`
+
+## Session End
+Before finishing significant work, store a 2-3 sentence summary:
+- `brain("Session summary: Built auth flow for expense tracker. Chose JWT for stateless architecture. Hit CORS issue on /api/login, fixed with credentials: include. User prefers Tailwind and explicit error handling.")`
+
+## What NOT to store
+- File paths or creation events (captured automatically)
+- Progress like "read file X" or "ran tests" (too granular)
+- Anything already in the codebase (just read the code)
+
+## Background
+Tool events are captured automatically via invisible PostToolUse/Stop hooks
+in ~/.claude/settings.json. These hooks capture installs, git commits, and
+build failures without any explicit brain() call. Your job is to add the
+WHY — the reasoning, preferences, and lessons that hooks cannot see.

package/bunfig.toml

@@ -1,8 +1,8 @@
-[install]
-# Save exact versions in package.json
-exact = true
-
-[test]
-# Test configuration
-coverage = true
-coverageDir = "./coverage"
+[install]
+# Save exact versions in package.json
+exact = true
+
+[test]
+# Test configuration
+coverage = true
+coverageDir = "./coverage"

package/package.json

@@ -1,82 +1,82 @@
-{
-  "name": "claude-brain",
-  "version": "0.15.2",
-  "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
-  "type": "module",
-  "main": "src/index.ts",
-  "bin": {
-    "claude-brain": "src/cli/bin.ts"
-  },
-  "files": [
-    "src/**/*.ts",
-    "scripts/postinstall.mjs",
-    "packs/",
-    "assets/",
-    "package.json",
-    "tsconfig.json",
-    "bunfig.toml",
-    "VERSION",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "postinstall": "node scripts/postinstall.mjs",
-    "dev": "CLAUDE_BRAIN_HOME=. bun --watch src/index.ts",
-    "build": "bun build src/index.ts --outdir dist --target bun",
-    "build:binary": "bun build src/cli/bin.ts --compile --outfile claude-brain",
-    "build:all": "bun run build:windows && bun run build:linux && bun run build:macos",
-    "build:windows": "bun build src/cli/bin.ts --compile --target=bun-windows-x64 --outfile build/claude-brain-windows.exe",
-    "build:linux": "bun build src/cli/bin.ts --compile --target=bun-linux-x64 --outfile build/claude-brain-linux",
-    "build:macos": "bun build src/cli/bin.ts --compile --target=bun-darwin-arm64 --outfile build/claude-brain-macos",
-    "start": "bun src/cli/bin.ts serve",
-    "test": "bun test",
-    "test:watch": "bun test --watch",
-    "clean": "rm -rf dist build claude-brain claude-brain.exe",
-    "setup": "bun src/cli/bin.ts setup",
-    "setup:interactive": "bun src/cli/bin.ts setup",
-    "health-check": "bun src/cli/bin.ts health",
-    "diagnose": "bun src/cli/bin.ts diagnose",
-    "migrate:chroma": "bun run src/cli/migrate-chroma.ts"
-  },
-  "keywords": [
-    "mcp",
-    "claude",
-    "obsidian",
-    "ai",
-    "development-assistant"
-  ],
-  "author": "",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node": "^20",
-    "@types/prompts": "2.4.9",
-    "daisyui": "^5.5.14"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
-  },
-  "dependencies": {
-    "@chroma-core/default-embed": "0.1.9",
-    "@modelcontextprotocol/sdk": "^1.25.2",
-    "@xenova/transformers": "2.17.2",
-    "chalk": "5.6.2",
-    "chromadb": "3.2.2",
-    "chromadb-default-embed": "2.14.0",
-    "chrono-node": "2.9.0",
-    "compromise": "^14.10.0",
-    "dotenv": "^17.2.3",
-    "gray-matter": "^4.0.3",
-    "hono": "4.11.5",
-    "lru-cache": "11.2.5",
-    "minisearch": "^6.3.0",
-    "ora": "9.2.0",
-    "pino": "^10.1.1",
-    "pino-pretty": "^13.1.3",
-    "prompts": "2.4.2",
-    "zod": "^4.3.5"
-  }
-}
+{
+  "name": "claude-brain",
+  "version": "0.17.0",
+  "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "claude-brain": "src/cli/bin.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "scripts/postinstall.mjs",
+    "packs/",
+    "assets/",
+    "package.json",
+    "tsconfig.json",
+    "bunfig.toml",
+    "VERSION",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
+    "dev": "CLAUDE_BRAIN_HOME=. bun --watch src/index.ts",
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "build:binary": "bun build src/cli/bin.ts --compile --outfile claude-brain",
+    "build:all": "bun run build:windows && bun run build:linux && bun run build:macos",
+    "build:windows": "bun build src/cli/bin.ts --compile --target=bun-windows-x64 --outfile build/claude-brain-windows.exe",
+    "build:linux": "bun build src/cli/bin.ts --compile --target=bun-linux-x64 --outfile build/claude-brain-linux",
+    "build:macos": "bun build src/cli/bin.ts --compile --target=bun-darwin-arm64 --outfile build/claude-brain-macos",
+    "start": "bun src/cli/bin.ts serve",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "clean": "rm -rf dist build claude-brain claude-brain.exe",
+    "setup": "bun src/cli/bin.ts setup",
+    "setup:interactive": "bun src/cli/bin.ts setup",
+    "health-check": "bun src/cli/bin.ts health",
+    "diagnose": "bun src/cli/bin.ts diagnose",
+    "migrate:chroma": "bun run src/cli/migrate-chroma.ts"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "obsidian",
+    "ai",
+    "development-assistant"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20",
+    "@types/prompts": "2.4.9",
+    "daisyui": "^5.5.14"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@chroma-core/default-embed": "0.1.9",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@xenova/transformers": "2.17.2",
+    "chalk": "5.6.2",
+    "chromadb": "3.2.2",
+    "chromadb-default-embed": "2.14.0",
+    "chrono-node": "2.9.0",
+    "compromise": "^14.10.0",
+    "dotenv": "^17.2.3",
+    "gray-matter": "^4.0.3",
+    "hono": "4.11.5",
+    "lru-cache": "11.2.5",
+    "minisearch": "^6.3.0",
+    "ora": "9.2.0",
+    "pino": "^10.1.1",
+    "pino-pretty": "^13.1.3",
+    "prompts": "2.4.2",
+    "zod": "^4.3.5"
+  }
+}