claude-brain 0.30.2 → 0.30.3

package/README.md

@@ -1,191 +1,241 @@
-# 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 -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:
-
-```bash
-claude mcp add claude-brain -s user -- 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
+
+[![Version](https://img.shields.io/badge/version-0.30.3-blue.svg)](package.json)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Runtime](https://img.shields.io/badge/runtime-Bun-f472b6.svg)](https://bun.sh)
+
+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 -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:
+
+```bash
+claude mcp add claude-brain -s user -- 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 |
+
+## Documentation
+
+Comprehensive documentation is available in the [`docs/`](docs/) directory:
+
+| Document | Description |
+|----------|-------------|
+| [API Reference](docs/API.md) | Complete HTTP API reference — 27 endpoints with request/response schemas and curl examples |
+| [Configuration](docs/CONFIGURATION.md) | Every config option documented with types, defaults, and environment variables |
+| [Knowledge Packs](docs/PACKS.md) | Pack format, built-in packs, custom pack creation, CLI commands |
+| [Hooks & Passive Learning](docs/HOOKS.md) | Hook system architecture, passive classification, git capture, session tracking |
+| [Code Intelligence](docs/CODE-INTELLIGENCE.md) | Tree-sitter indexing, `search_code` tool, supported languages, code-memory linking |
+| [Security Hardening](docs/SECURITY.md) | Authentication, TLS proxy configs, database security, incident response |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | 16 common issues with symptoms, causes, and solutions |
+| [Production Checklist](docs/PRODUCTION-CHECKLIST.md) | 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](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
+
+```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` |
+
+## Security
+
+For production deployments, see [docs/SECURITY.md](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](docs/API.md) for the full reference.
+
+```bash
+# 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

package/VERSION

@@ -1 +1 @@
-0.30.2
+0.30.2

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,29 +1,29 @@
-# 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.
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.30.2",
+  "version": "0.30.3",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",
@@ -50,6 +50,10 @@
   ],
   "author": "",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DemGun101/2nd-Brain.git"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -63,7 +67,7 @@
   },
   "dependencies": {
     "@chroma-core/default-embed": "0.1.9",
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "1.26.0",
     "@xenova/transformers": "2.17.2",
     "chalk": "5.6.2",
     "chromadb": "3.2.2",
@@ -72,7 +76,7 @@
     "compromise": "^14.10.0",
     "dotenv": "^17.2.3",
     "gray-matter": "^4.0.3",
-    "hono": "4.11.5",
+    "hono": "4.11.9",
     "lru-cache": "11.2.5",
     "minisearch": "^6.3.0",
     "onnxruntime-web": "1.24.1",