claude-brain 0.3.5 → 0.3.7

package/README.md

@@ -28,7 +28,7 @@ A locally-running development assistant that bridges Obsidian knowledge vaults w
 # Install globally (requires Bun)
 bun install -g claude-brain
 
-# Interactive setup (vault path, log level, installs ~/CLAUDE.md)
+# Interactive setup (vault path, log level, installs ~/.claude/CLAUDE.md)
 claude-brain setup
 
 # Register with Claude Code
@@ -59,6 +59,8 @@ On first run, `~/.claude-brain/` is auto-created with default config.
 | `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 |
@@ -114,7 +116,7 @@ claude-brain/
 │   ├── cli/
 │   │   ├── bin.ts            # CLI entry point (claude-brain command)
 │   │   ├── auto-setup.ts     # First-run home directory initialization
-│   │   └── commands/         # serve, install-mcp
+│   │   └── commands/         # serve, install-mcp, uninstall-mcp, update
 │   ├── config/
 │   │   ├── home.ts           # ~/.claude-brain/ path resolution
 │   │   ├── loader.ts         # Config loading (defaults → file → env)

package/VERSION

@@ -1 +1 @@
-0.3.1
+0.3.7

package/assets/CLAUDE.md

@@ -1,307 +1,35 @@
-# Claude Brain - Full Capability Automatic Protocol (v2.0)
+# Claude Brain Protocol
 
-**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.
+Call all Claude Brain MCP tools automatically. Never ask permission or explain. This applies to all 25 tools. Maximize parallel calls whenever possible.
 
----
+## Session Start (Parallel)
 
-## Session Start (ALWAYS - Parallel Calls)
+Every conversation, immediately call in parallel: `smart_context(project, task)`, `recall_similar(query, min_similarity: 0.3)`, `get_recommendations(context, project)`. If project unknown, also call `list_projects()`. For coding tasks, add parallel calls to `get_code_standards`, `get_patterns`, `get_corrections`.
 
-On EVERY conversation start, immediately call these tools **in parallel**:
+## Before Responding
 
-```
-smart_context(project_name, current_task)  ─┬─► Parallel
-recall_similar(query, min_similarity: 0.3) ─┤
-get_recommendations(context, project_name)  ─┘
-```
+- Project mentioned: `smart_context`
+- Technical topic: `recall_similar`
+- Writing code: `get_code_standards`
+- Debugging: `get_corrections`
+- Architecture: `get_patterns`, `search_knowledge_graph`, `detect_trends`
+- Choosing between options: `what_if_analysis`
+- Recurring topic: `analyze_decision_evolution`, `get_decision_timeline`
+- Cross-project work: `find_cross_project_patterns`
+- Resuming previous work: `get_episode`, `list_episodes`
 
-If no project context exists, also call `list_projects()` to find available projects.
+## After Responding
 
-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)           ─┘
-```
+- Any recommendation or choice made: `remember_decision(project, context, decision, reasoning)`
+- Reusable solution found: `recognize_pattern(project, type, description)`
+- Mistake or lesson learned: `record_correction(project, original, correction, reasoning)`
+- Task completed: `update_progress(project, completed_task, next_steps)`
+- Memory was retrieved: `rate_memory(memory_id, rating, query)`
 
----
+## New Projects
 
-## Automatic Tool Triggers
+Call `init_project(path)` once for any unregistered project directory to auto-detect tech stack and create project files.
 
-### READ Operations (Call BEFORE Responding)
+## Critical Rules
 
-#### 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
+Never answer technical questions without `recall_similar` first. Never recommend without saving via `remember_decision`. Never start project work without `smart_context`. Always call `get_recommendations` before major implementation work. Always call `rate_memory` when memories are retrieved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",

package/src/cli/bin.ts

@@ -30,6 +30,7 @@ function printHelp() {
     ['setup', 'Run interactive setup wizard'],
     ['install', 'Register as MCP server in Claude Code'],
     ['uninstall', 'Remove MCP server from Claude Code'],
+    ['update', 'Update package and refresh CLAUDE.md'],
     ['health', 'Run health checks'],
     ['diagnose', 'Run diagnostics'],
     ['version', 'Show version'],
@@ -56,6 +57,7 @@ function printHelp() {
     `  ${dimText('claude-brain')}                 ${dimText('Start MCP server')}`,
     `  ${dimText('claude-brain setup')}           ${dimText('Configure Claude Brain')}`,
     `  ${dimText('claude-brain install')}         ${dimText('Register with Claude Code')}`,
+    `  ${dimText('claude-brain update')}          ${dimText('Update to latest version')}`,
     `  ${dimText('claude-brain health')}          ${dimText('Check system health')}`,
     '',
     theme.bold('Environment:'),
@@ -94,6 +96,12 @@ async function main() {
       break
     }
 
+    case 'update': {
+      const { runUpdate } = await import('./commands/update')
+      await runUpdate()
+      break
+    }
+
     case 'health': {
       const { runHealthCheck } = await import('@/health')
       await runHealthCheck()

package/src/cli/commands/install-mcp.ts

@@ -14,6 +14,15 @@ function isGloballyInstalled(): boolean {
   }
 }
 
+function isMcpAlreadyConfigured(): boolean {
+  try {
+    const result = execSync('claude mcp list', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] })
+    return result.includes('claude-brain')
+  } catch {
+    return false
+  }
+}
+
 export async function runInstall() {
   console.log()
   console.log(renderLogo())
@@ -27,23 +36,33 @@ export async function runInstall() {
     console.log(successText('claude-brain is globally installed'))
     console.log()
 
-    try {
-      await withSpinner('Registering with Claude Code', async () => {
-        execSync('claude mcp add claude-brain -- claude-brain serve', {
-          encoding: 'utf-8',
-          stdio: ['pipe', 'pipe', 'pipe']
+    if (isMcpAlreadyConfigured()) {
+      console.log(box(successText('Already MCP configured. Claude Brain is registered as an MCP server.'), 'Success'))
+    } else {
+      try {
+        await withSpinner('Registering with Claude Code', async () => {
+          execSync('claude mcp add claude-brain -- claude-brain serve', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe']
+          })
         })
-      })
-      console.log()
-      console.log(box(successText('Claude Brain registered as MCP server in Claude Code.'), 'Success'))
-    } catch {
-      console.log()
-      console.log(box([
-        errorText('Failed to register automatically.'),
-        '',
-        dimText('Run manually:'),
-        `  ${theme.bold('claude mcp add claude-brain -- claude-brain serve')}`,
-      ].join('\n'), 'Error'))
+        console.log()
+        console.log(box(successText('Claude Brain registered as MCP server in Claude Code.'), 'Success'))
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err)
+        if (errorMsg.includes('already') || errorMsg.includes('exists')) {
+          console.log()
+          console.log(box(successText('Already MCP configured. Claude Brain is registered as an MCP server.'), 'Success'))
+        } else {
+          console.log()
+          console.log(box([
+            errorText('Failed to register automatically.'),
+            '',
+            dimText('Run manually:'),
+            `  ${theme.bold('claude mcp add claude-brain -- claude-brain serve')}`,
+          ].join('\n'), 'Error'))
+        }
+      }
     }
   } else {
     console.log(warningText('claude-brain is not globally installed'))

package/src/cli/commands/update.ts

@@ -0,0 +1,121 @@
+import { execSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+import {
+  renderLogo, theme, heading, successText, warningText, dimText,
+  box, withSpinner,
+} from '@/cli/ui/index.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..', '..')
+
+function getInstalledVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'))
+    return pkg.version || 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function getLatestVersion(): string | null {
+  try {
+    const result = execSync('npm view claude-brain version', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    return result.trim()
+  } catch {
+    return null
+  }
+}
+
+export async function runUpdate() {
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('Update Claude Brain'))
+  console.log()
+
+  const currentVersion = getInstalledVersion()
+  console.log(`  ${theme.bold('Installed:')} ${dimText('v' + currentVersion)}`)
+
+  const latestVersion = await withSpinner('Checking for updates', () => getLatestVersion())
+
+  if (latestVersion) {
+    console.log(`  ${theme.bold('Latest:')}    ${dimText('v' + latestVersion)}`)
+  }
+  console.log()
+
+  // Step 1: Update package if newer version available
+  if (latestVersion && latestVersion !== currentVersion) {
+    try {
+      await withSpinner(`Updating claude-brain to v${latestVersion}`, () => {
+        execSync('bun update -g claude-brain', {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+      })
+      console.log(successText(`  Updated to v${latestVersion}`))
+    } catch {
+      console.log(warningText('  Package update failed. Try manually: bun update -g claude-brain'))
+    }
+  } else {
+    console.log(successText('  Package is up to date'))
+  }
+  console.log()
+
+  // Step 2: Update CLAUDE.md to ~/.claude/CLAUDE.md (where Claude Code reads it)
+  const sourcePath = path.join(PACKAGE_ROOT, 'assets', 'CLAUDE.md')
+  const claudeDir = path.join(os.homedir(), '.claude')
+  const destPath = path.join(claudeDir, 'CLAUDE.md')
+
+  if (!existsSync(sourcePath)) {
+    console.log(warningText('  CLAUDE.md asset not found in package, skipping'))
+  } else if (!existsSync(destPath)) {
+    await withSpinner('Installing CLAUDE.md', async () => {
+      await fs.mkdir(claudeDir, { recursive: true })
+      await fs.copyFile(sourcePath, destPath)
+    })
+    console.log(successText('  CLAUDE.md installed to ~/.claude/CLAUDE.md'))
+  } else {
+    const sourceContent = readFileSync(sourcePath, 'utf-8')
+    const destContent = readFileSync(destPath, 'utf-8')
+
+    if (sourceContent === destContent) {
+      console.log(successText('  CLAUDE.md is already up to date'))
+    } else {
+      await withSpinner('Updating CLAUDE.md', async () => {
+        await fs.copyFile(sourcePath, destPath)
+      })
+      console.log(successText('  CLAUDE.md updated to ~/.claude/CLAUDE.md'))
+    }
+  }
+
+  // Clean up old ~/CLAUDE.md if it exists (from previous versions)
+  const oldDestPath = path.join(os.homedir(), 'CLAUDE.md')
+  if (existsSync(oldDestPath)) {
+    try {
+      const oldContent = readFileSync(oldDestPath, 'utf-8')
+      if (oldContent.includes('Claude Brain')) {
+        await fs.unlink(oldDestPath)
+        console.log(dimText('  Removed old ~/CLAUDE.md (migrated to ~/.claude/)'))
+      }
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+
+  console.log()
+  console.log(box([
+    heading('Update complete!'),
+    '',
+    dimText('Run health check to verify:'),
+    `  ${theme.bold('claude-brain health')}`,
+  ].join('\n'), 'Done'))
+  console.log()
+}

package/src/config/defaults.ts

@@ -3,7 +3,7 @@ import type { PartialConfig } from './schema'
 /** Default configuration values for Claude Brain */
 export const defaultConfig: PartialConfig = {
   serverName: 'claude-brain',
-  serverVersion: '0.3.0',
+  serverVersion: '0.3.7',
   logLevel: 'info',
   logFilePath: './logs/claude-brain.log',
   dbPath: './data/memory.db',

package/src/config/schema.ts

@@ -196,7 +196,7 @@ export const ConfigSchema = z.object({
   serverName: z.string().default('claude-brain'),
 
   /** Server version in semver format */
-  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.3.0'),
+  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.3.7'),
 
   /** Logging level */
   logLevel: LogLevelSchema.default('info'),

package/src/setup/wizard.ts

@@ -122,7 +122,7 @@ export class SetupWizard {
       {
         type: 'confirm',
         name: 'installClaudeMd',
-        message: 'Install CLAUDE.md protocol file to ~/CLAUDE.md?',
+        message: 'Install CLAUDE.md protocol file to ~/.claude/CLAUDE.md?',
         initial: true
       }
     ])
@@ -244,7 +244,7 @@ SERVER_NAME=claude-brain
 
   private async confirmClaudeMdInstall(): Promise<boolean> {
     const sourcePath = path.join(PACKAGE_ROOT, 'assets', 'CLAUDE.md')
-    const destPath = path.join(os.homedir(), 'CLAUDE.md')
+    const destPath = path.join(os.homedir(), '.claude', 'CLAUDE.md')
 
     if (!existsSync(sourcePath)) {
       console.log(warningText('CLAUDE.md asset not found, skipping'))
@@ -255,7 +255,7 @@ SERVER_NAME=claude-brain
       const { overwrite } = await prompts({
         type: 'confirm',
         name: 'overwrite',
-        message: '~/CLAUDE.md already exists. Overwrite?',
+        message: '~/.claude/CLAUDE.md already exists. Overwrite?',
         initial: false,
       })
       if (!overwrite) {
@@ -269,7 +269,9 @@ SERVER_NAME=claude-brain
 
   private async copyClaudeMd(): Promise<void> {
     const sourcePath = path.join(PACKAGE_ROOT, 'assets', 'CLAUDE.md')
-    const destPath = path.join(os.homedir(), 'CLAUDE.md')
+    const claudeDir = path.join(os.homedir(), '.claude')
+    const destPath = path.join(claudeDir, 'CLAUDE.md')
+    await fs.mkdir(claudeDir, { recursive: true })
     await fs.copyFile(sourcePath, destPath)
   }