claude-brain 0.3.0

package/README.md

@@ -0,0 +1,157 @@
+# 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
+
+## Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0.0
+- An Obsidian vault (or any markdown folder)
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd claude-brain
+
+# Install dependencies
+bun install
+
+# Run setup to create directories and validate config
+bun run setup
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and update with your settings:
+
+```bash
+cp .env.example .env
+```
+
+Required configuration:
+- `VAULT_PATH`: Absolute path to your Obsidian vault
+
+## Development
+
+```bash
+# Start development server with hot reload
+bun run dev
+
+# Run tests
+bun run test
+
+# Run tests in watch mode
+bun run test:watch
+```
+
+## Building
+
+```bash
+# Build for production (bundled JS)
+bun run build
+
+# 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              # Main entry point + orchestrator init
+│   ├── 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)
+│   │   ├── bm25/             # BM25 keyword search engine
+│   │   ├── fusion/           # RRF/linear/max fusion strategies
+│   │   ├── reranker/         # Cross-encoder neural reranking
+│   │   ├── query/            # Intent classification & query expansion
+│   │   └── feedback/         # Feedback collection & adaptive learning
+│   ├── 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
+│   ├── context/              # Context assembly
+│   ├── tools/                # MCP tool definitions & registry
+│   ├── config/               # Configuration management
+│   ├── utils/                # Shared utilities
+│   ├── types/                # TypeScript definitions
+│   └── scripts/              # CLI scripts
+├── data/                     # Local data storage
+├── logs/                     # Log files
+├── tests/                    # 750+ tests
+└── dist/                     # Build output
+```
+
+## 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

@@ -0,0 +1 @@
+0.3.0

package/assets/CLAUDE.md

@@ -0,0 +1,307 @@
+# Claude Brain - Full Capability Automatic Protocol (v2.0)
+
+**CRITICAL:** Call Claude Brain tools automatically. Do not ask permission. Do not explain you're calling them. Just call them. This applies to ALL 25 tools.
+
+---
+
+## Session Start (ALWAYS - Parallel Calls)
+
+On EVERY conversation start, immediately call these tools **in parallel**:
+
+```
+smart_context(project_name, current_task)  ─┬─► Parallel
+recall_similar(query, min_similarity: 0.3) ─┤
+get_recommendations(context, project_name)  ─┘
+```
+
+If no project context exists, also call `list_projects()` to find available projects.
+
+After the first user message reveals a project, also call in parallel:
+```
+get_code_standards(project, language)       ─┬─► Parallel
+detect_trends(project_name)                 ─┤
+get_patterns(project_name, query)           ─┘
+```
+
+---
+
+## Automatic Tool Triggers
+
+### READ Operations (Call BEFORE Responding)
+
+#### Tier 1: ALWAYS call these (every interaction)
+
+| User Intent | Tool | Params |
+|-------------|------|--------|
+| ANY project mention | `smart_context` | `project_name`, `current_task` |
+| ANY technical topic | `recall_similar` | `query`, `min_similarity: 0.3` |
+| ANY task starting | `get_recommendations` | `context`, `project_name` |
+
+#### Tier 2: Call when relevant context exists
+
+| User Intent | Tool | Params |
+|-------------|------|--------|
+| Writing/reviewing code | `get_code_standards` | `project_name`, `language` |
+| Debugging/troubleshooting | `get_corrections` | `project_name`, `query` |
+| Designing/architecting | `get_patterns` | `project_name`, `pattern_type` |
+| Choosing between options | `what_if_analysis` | `scenario`, `project_name` |
+| Understanding relationships | `search_knowledge_graph` | `query`, `node_type`, `max_depth` |
+
+#### Tier 3: Call proactively for deeper intelligence
+
+| User Intent | Tool | Params |
+|-------------|------|--------|
+| Revisiting a topic | `analyze_decision_evolution` | `topic`, `project_name` |
+| Working on established project | `detect_trends` | `project_name`, `period_days` |
+| Decision with history | `get_decision_timeline` | `query`, `project_name` |
+| Multi-project work | `find_cross_project_patterns` | `min_projects` |
+| Session continuity | `list_episodes` | `project_name`, `status`, `limit` |
+| Resuming past work | `get_episode` | `episode_id` or `project_name` |
+
+### WRITE Operations (Call AFTER Responding)
+
+| Your Response Contains | Tool | Required Params |
+|------------------------|------|-----------------|
+| ANY recommendation, choice, or suggestion | `remember_decision` | `project_name`, `context`, `decision`, `reasoning` |
+| Reusable solution or approach | `recognize_pattern` | `project_name`, `pattern_type`, `description` |
+| Mistake discovered / lesson learned | `record_correction` | `project_name`, `original`, `correction`, `reasoning` |
+| Task completed or milestone reached | `update_progress` | `project_name`, `completed_task`, `next_steps` |
+| Memory was useful (rating 4-5) or not (1-2) | `rate_memory` | `memory_id`, `rating`, `query` |
+
+---
+
+## Proactive Intelligence Rules
+
+### Rule 1: Always Get Recommendations Before Major Work
+Before implementing any feature, fixing any bug, or making any architectural choice:
+```
+get_recommendations(context: "what you're about to do", project_name)
+```
+This pulls from patterns, corrections, AND past decisions to give you the best starting point.
+
+### Rule 2: Always Check Decision Evolution for Recurring Topics
+If the user asks about something they've worked on before (databases, auth, state management, etc.):
+```
+analyze_decision_evolution(topic: "the topic", project_name)
+```
+This shows if past decisions were stable, evolving, or volatile — and the current direction.
+
+### Rule 3: Run What-If When Choosing Between Alternatives
+When the user is deciding between options (library A vs B, approach X vs Y):
+```
+what_if_analysis(scenario: "What if we switch from X to Y?", project_name)
+```
+This uses the knowledge graph to trace impact chains.
+
+### Rule 4: Check Cross-Project Patterns When Starting New Features
+When implementing something that other projects might have solved:
+```
+find_cross_project_patterns(min_projects: 1)
+```
+This discovers shared solutions across all registered projects.
+
+### Rule 5: Check Trends Periodically
+When working on architecture or technology choices:
+```
+detect_trends(project_name, period_days: 90)
+```
+This shows what technologies are emerging, stable, or declining in the project.
+
+### Rule 6: Use Knowledge Graph for Technology Relationships
+When discussing technology choices, dependencies, or architecture:
+```
+search_knowledge_graph(query: "technology or concept", node_type: "technology")
+```
+This reveals connections between technologies, decisions, and concepts.
+
+---
+
+## Decision Tree: Complete
+
+```
+User message received
+│
+├─► Mentions project name?
+│   └─► YES: smart_context(project, task) [PARALLEL with below]
+│
+├─► Technical question or task?
+│   ├─► YES: recall_similar(query) [PARALLEL with above]
+│   └─► YES: get_recommendations(context) [PARALLEL with above]
+│
+├─► Writing/reviewing code?
+│   └─► YES: get_code_standards(project, language)
+│
+├─► Debugging something?
+│   └─► YES: get_corrections(project, query)
+│
+├─► Designing architecture?
+│   ├─► YES: get_patterns(project, "solution")
+│   ├─► YES: search_knowledge_graph(query, "technology")
+│   └─► YES: detect_trends(project)
+│
+├─► Choosing between options?
+│   └─► YES: what_if_analysis(scenario)
+│
+├─► Topic discussed before?
+│   └─► YES: analyze_decision_evolution(topic)
+│         + get_decision_timeline(query)
+│
+├─► Working across projects?
+│   └─► YES: find_cross_project_patterns()
+│
+├─► Resuming previous work?
+│   └─► YES: get_episode(project) + list_episodes(project)
+│
+└─► New project encountered?
+    └─► YES: init_project(project_path)
+
+After your response:
+│
+├─► Made ANY recommendation or choice?
+│   └─► YES: remember_decision(...)
+│
+├─► Found reusable solution?
+│   └─► YES: recognize_pattern(...)
+│
+├─► Learned from mistake?
+│   └─► YES: record_correction(...)
+│
+├─► Completed work?
+│   └─► YES: update_progress(...)
+│
+└─► Memory was retrieved?
+    └─► YES: rate_memory(memory_id, rating, query)
+```
+
+---
+
+## Tool Reference (All 25 Tools)
+
+### Context Retrieval (5)
+- **`smart_context`** - Primary tool. Gets project + auto-recalls relevant memories
+- **`recall_similar`** - Semantic search across all memory. Use `min_similarity: 0.3`
+- **`get_patterns`** - Types: `solution`, `anti-pattern`, `best-practice`, `common-issue`
+- **`get_corrections`** - Past mistakes relevant to current task
+- **`get_code_standards`** - Project coding conventions
+
+### Memory Storage (5)
+- **`remember_decision`** - Store decisions with: context, decision, reasoning, tags
+- **`recognize_pattern`** - Store reusable solutions/anti-patterns with confidence
+- **`record_correction`** - Store mistakes: original, correction, reasoning
+- **`update_progress`** - Track: completed_task, next_steps
+- **`rate_memory`** - Rate retrieved memories 1-5 stars for adaptive learning
+
+### Knowledge Graph & Episodic Memory (3)
+- **`search_knowledge_graph`** - Search connected nodes/edges by query, node type, or start node
+- **`get_episode`** - Get episode by ID or active episode for a project
+- **`list_episodes`** - List recent episodes, filter by project or status
+
+### Advanced Intelligence (6)
+- **`get_decision_timeline`** - Chronological timeline with temporal queries ("last month", "since January")
+- **`analyze_decision_evolution`** - Track how decisions on a topic changed (stable/evolving/volatile)
+- **`detect_trends`** - Detect emerging, stable, declining technology/pattern trends
+- **`what_if_analysis`** - Counterfactual: "What if we switched from X to Y?"
+- **`get_recommendations`** - Context-aware recommendations from patterns + corrections + decisions
+- **`find_cross_project_patterns`** - Discover shared patterns across all projects
+
+### Project Management (3)
+- **`list_projects`** - See available projects (status_filter: active/archived/all)
+- **`init_project`** - Initialize from existing codebase (auto-detects tech stack)
+- **`create_project`** - New project from scratch
+
+### System (3)
+- **`auto_remember`** - Auto-detect decisions in text (>70% confidence auto-saved)
+- **`get_phase12_status`** - System health and automation stats
+- **`get_project_context`** - Raw project context without smart recall
+
+---
+
+## Parallel Call Patterns
+
+**Session Start (3 parallel calls):**
+```
+smart_context("project", "task")
+recall_similar("task description", min_similarity: 0.3)
+get_recommendations("task description", "project")
+```
+
+**Before Coding (3 parallel calls):**
+```
+get_code_standards("project", "typescript")
+get_patterns("project", query: "feature area")
+get_corrections("project", query: "feature area")
+```
+
+**Architecture Discussion (3 parallel calls):**
+```
+search_knowledge_graph("technology", node_type: "technology")
+detect_trends("project")
+analyze_decision_evolution("topic", "project")
+```
+
+**Choosing Between Options (2 parallel calls):**
+```
+what_if_analysis("What if we use X instead of Y?", "project")
+find_cross_project_patterns(min_projects: 1)
+```
+
+**After Task Completion (2-3 parallel calls):**
+```
+remember_decision(...)
+update_progress(...)
+recognize_pattern(...)  // if reusable
+```
+
+---
+
+## Save Decision Triggers
+
+**ALWAYS call `remember_decision` when your response contains:**
+- "I recommend..." / "We should use..." / "The best approach is..."
+- "Let's use X because..." / "Don't use X" / "Avoid X"
+- "Always do X" / "Never do Y"
+- Any architecture/library/framework/tool choice
+- Any coding standard or convention established
+- Any debugging insight or root cause identified
+- Any performance optimization chosen
+- Any security or deployment decision
+
+---
+
+## New Project Auto-Detection
+
+When you encounter a project directory that is NOT yet registered in Claude Brain:
+1. Call `init_project(project_path)` to auto-detect tech stack and create project files
+2. This only needs to happen ONCE per project — it analyzes package.json, config files, etc.
+3. After init, all subsequent sessions automatically have full project context
+
+---
+
+## Anti-Patterns (What NOT to Do)
+
+1. **Never answer technical questions without first calling `recall_similar`**
+2. **Never make recommendations without saving via `remember_decision`**
+3. **Never start project work without `smart_context`**
+4. **Never ask permission to call Claude Brain tools — just call them**
+5. **Never skip `get_recommendations` before major implementation work**
+6. **Never ignore Phase 15 tools — they provide the deepest intelligence**
+7. **Never forget to `rate_memory` when a recall was particularly useful or useless**
+8. **Never work on a new project without calling `init_project` first**
+
+---
+
+## System Notes
+
+- **25 MCP Tools**: Full coverage across context, memory, knowledge graph, and advanced intelligence
+- **Duplicate Prevention**: Decisions with >90% similarity auto-deduplicated
+- **Knowledge Graph**: Auto-populates when decisions are stored — extracts entities and relationships
+- **Episodic Memory**: Tracks sessions with automatic detection and summarization
+- **Memory Consolidation**: Importance scoring, automatic merging, low-importance archival
+- **Hybrid Retrieval**: BM25 + semantic fusion with cross-encoder reranking
+- **Temporal Intelligence**: Timelines, evolution tracking, trend detection with natural language dates
+- **Multi-Hop Reasoning**: Chain retrieval with query refinement and what-if analysis
+- **Predictive Intelligence**: Context-aware recommendations from all stored knowledge
+- **Cross-Project Intelligence**: Pattern discovery, affinity, and knowledge transfer
+- **Semantic Caching**: LRU cache for fast repeated queries
+- **Embedding**: all-MiniLM-L6-v2 (384d), SHA-256 cached
+- **Input Validation**: Zod schemas validate all inputs

package/bunfig.toml

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

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "claude-brain",
+  "version": "0.3.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",
+    "assets/",
+    "package.json",
+    "tsconfig.json",
+    "bunfig.toml",
+    "VERSION",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "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",
+  "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",
+    "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",
+    "pino": "^10.1.1",
+    "pino-pretty": "^13.1.3",
+    "prompts": "2.4.2",
+    "zod": "^4.3.5"
+  }
+}