cc-brain 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# cc-brain
+
+Persistent memory for [Claude Code](https://github.com/anthropics/claude-code). Remembers context across sessions.
+
+## What It Does
+
+Claude Code sessions are ephemeral - when context fills up or you start a new session, everything is forgotten. cc-brain fixes this by:
+
+- **Loading** your profile and project context on every session start
+- **Saving** important learnings before context compaction
+- **Searching** past sessions for decisions and context
+
+## Installation
+
+Choose your preferred method:
+
+### Option 1: npm (recommended)
+
+```bash
+npm install -g cc-brain
+cc-brain install
+```
+
+### Option 2: npx/bunx (no install)
+
+```bash
+npx cc-brain install
+# or
+bunx cc-brain install
+```
+
+### Option 3: Claude Plugin
+
+```bash
+claude plugins add cc-brain
+```
+
+### Option 4: Git Clone
+
+```bash
+git clone https://github.com/tripzcodes/cc-brain.git
+cd cc-brain
+node scripts/install.js
+```
+
+## Memory Tiers
+
+```
+~/.claude/brain/
+├── user.md              # T1: Your profile (always loaded)
+├── preferences.md       # T1: Code preferences (always loaded)
+└── projects/{id}/
+    ├── context.md       # T2: Current project state
+    └── archive/         # T3: Session history
+        └── 2025-01-31.md
+```
+
+| Tier | What | Limit | Loaded |
+|------|------|-------|--------|
+| T1 | User identity & preferences | 80 lines | Always |
+| T2 | Project context | 120 lines | Current project |
+| T3 | Archive | Unlimited | On-demand |
+
+## Skills
+
+| Command | Description |
+|---------|-------------|
+| `/save` | Save session context to brain |
+| `/recall <query>` | Search archive for past context |
+| `/brain` | View current brain state |
+
+## CLI
+
+```bash
+cc-brain install          # Install hooks
+cc-brain uninstall        # Remove hooks
+cc-brain uninstall --purge # Remove everything
+
+cc-brain recall "query"   # Search archive
+cc-brain archive list     # List archive entries
+cc-brain archive stats    # Show statistics
+cc-brain archive prune --keep 20  # Keep last 20
+
+cc-brain project-id --init  # Create stable .brain-id
+cc-brain save --dry-run --json '{"t2": {"focus": "testing"}}'
+```
+
+## How It Works
+
+1. **SessionStart hook** runs on every session:
+   - Loads T1 (user profile + preferences)
+   - Loads T2 (current project context)
+   - Auto-prunes archives older than 90 days
+
+2. **PreCompact hook** triggers before context dies:
+   - Analyzes session for important learnings
+   - Saves to appropriate tier using structured format
+
+3. **Skills** for manual control:
+   - `/save` - capture context anytime
+   - `/recall` - search past sessions
+   - `/brain` - see what's loaded
+
+## Project Identity
+
+By default, projects are identified by directory name. For stable identity that survives renames:
+
+```bash
+cc-brain project-id --init
+```
+
+This creates a `.brain-id` file with a UUID. Commit it to your repo.
+
+## Uninstall
+
+```bash
+cc-brain uninstall          # Remove hooks, keep brain data
+cc-brain uninstall --purge  # Remove everything
+```
+
+Or if installed via npm:
+
+```bash
+npm uninstall -g cc-brain
+```
+
+## Requirements
+
+- Node.js >= 18 or [Bun](https://bun.sh)
+- [Claude Code](https://github.com/anthropics/claude-code) CLI
+
+## License
+
+MIT

package/bin/cc-brain.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * cc-brain CLI
+ * Persistent memory for Claude Code
+ */
+
+import { spawn, execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+// Check for bun, fallback to node
+let runtime = 'node';
+try {
+  execSync('bun --version', { stdio: 'ignore' });
+  runtime = 'bun';
+} catch {
+  // bun not available, use node
+}
+
+const commands = {
+  install: 'scripts/install.js',
+  uninstall: 'scripts/uninstall.js',
+  load: 'src/loader.js',
+  save: 'src/saver.js',
+  recall: 'src/recall.js',
+  archive: 'src/archive.js',
+  'project-id': 'src/project-id.js',
+};
+
+function showHelp() {
+  console.log(`cc-brain - Persistent memory for Claude Code
+
+Usage: cc-brain <command> [options]
+
+Commands:
+  install      Install hooks to Claude Code
+  uninstall    Remove hooks (--purge to delete data)
+  load         Load brain (usually run by hook)
+  save         Save to brain (--json '{}' --dry-run)
+  recall       Search archive (query)
+  archive      Manage archive (list|stats|prune)
+  project-id   Manage project identity (--init|--path)
+
+Examples:
+  cc-brain install
+  cc-brain uninstall --purge
+  cc-brain recall "authentication"
+  cc-brain archive stats
+  cc-brain project-id --init
+
+More info: https://github.com/tripzcodes/cc-brain`);
+}
+
+if (!command || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  const pkg = await import('../package.json', { assert: { type: 'json' } });
+  console.log(pkg.default.version);
+  process.exit(0);
+}
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run cc-brain --help for usage');
+  process.exit(1);
+}
+
+const script = join(ROOT, commands[command]);
+const child = spawn(runtime, [script, ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+  env: { ...process.env, CLAUDE_PROJECT_DIR: process.cwd() }
+});
+
+child.on('exit', (code) => process.exit(code || 0));

package/brain/preferences.md

@@ -0,0 +1,13 @@
+# Code & Tool Preferences
+
+## Code Style
+
+
+## Frameworks & Tools
+
+
+## Patterns
+
+
+## Avoid
+

package/brain/projects/example/context.md

@@ -0,0 +1,16 @@
+# Project Context
+
+## What
+(One-liner: what this project is)
+
+## Current Focus
+(What we're actively working on)
+
+## Decisions
+(Key choices made + why)
+
+## Key Files
+(Important files and their purposes)
+
+## Blockers
+(Known issues or questions)

package/brain/user.md

@@ -0,0 +1,13 @@
+# User Profile
+
+## Communication Style
+
+
+## Thinking Patterns
+
+
+## Preferences
+
+
+## Pet Peeves
+

package/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "SessionStart": [
+    {
+      "matcher": "startup|resume|compact",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bun \"$CLAUDE_PROJECT_DIR/src/loader.js\"",
+          "timeout": 5,
+          "statusMessage": "Loading brain..."
+        }
+      ]
+    }
+  ],
+  "PreCompact": [
+    {
+      "hooks": [
+        {
+          "type": "agent",
+          "prompt": "Context is being compacted. Save important information using the structured saver.\n\nANALYZE this session for:\n- New user insights (T1 - rare)\n- New preferences (T1 - rare)\n- Project decisions + rationale (T2)\n- Current focus/state (T2)\n- Session summary (T3 - if significant)\n\nBUILD JSON payload:\n```json\n{\n  \"t2\": {\n    \"what\": \"Project description\",\n    \"focus\": [\"current tasks\"],\n    \"decisions\": {\"decision\": \"rationale\"}\n  },\n  \"t3\": \"Session summary if significant work done.\"\n}\n```\n\nSAVE using:\n```bash\nbun src/saver.js --json '<payload>'\n```\n\nRules:\n- Only include tiers with new info\n- T2 updates are common, T1 updates are rare\n- Decisions need rationale\n- Keep it concise",
+          "timeout": 120,
+          "statusMessage": "Saving to brain..."
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "cc-brain",
+  "version": "0.1.0",
+  "description": "Persistent memory system for Claude Code - remembers context across sessions",
+  "type": "module",
+  "bin": {
+    "cc-brain": "./bin/cc-brain.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "skills",
+    "hooks",
+    "brain",
+    "plugin.json"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "preuninstall": "node scripts/uninstall.js",
+    "test": "node src/loader.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "memory",
+    "context",
+    "ai",
+    "persistent",
+    "brain"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tripzcodes/cc-brain.git"
+  },
+  "homepage": "https://github.com/tripzcodes/cc-brain#readme",
+  "bugs": {
+    "url": "https://github.com/tripzcodes/cc-brain/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "cc-brain",
+  "version": "0.1.0",
+  "description": "Persistent memory system for Claude Code",
+  "skills": [
+    "skills/save.md",
+    "skills/recall.md",
+    "skills/brain.md"
+  ],
+  "hooks": "hooks/hooks.json"
+}

package/scripts/install.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * Install cc-brain
+ * Sets up brain directory and hooks
+ */
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const HOME = homedir();
+const CLAUDE_DIR = join(HOME, '.claude');
+const BRAIN_DIR = join(CLAUDE_DIR, 'brain');
+const PROJECT_ROOT = join(import.meta.dirname, '..');
+
+console.log('Installing cc-brain...\n');
+
+// Create brain directory structure
+const dirs = [
+  BRAIN_DIR,
+  join(BRAIN_DIR, 'projects')
+];
+
+for (const dir of dirs) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+    console.log(`Created: ${dir}`);
+  }
+}
+
+// Clean up legacy files from previous versions
+const legacyFiles = [
+  join(BRAIN_DIR, 'load-brain.sh'),
+];
+
+for (const file of legacyFiles) {
+  if (existsSync(file)) {
+    unlinkSync(file);
+    console.log(`Removed: ${file} (legacy)`);
+  }
+}
+
+// Copy template brain files if they don't exist
+const templates = ['user.md', 'preferences.md'];
+for (const file of templates) {
+  const dest = join(BRAIN_DIR, file);
+  if (!existsSync(dest)) {
+    copyFileSync(join(PROJECT_ROOT, 'brain', file), dest);
+    console.log(`Created: ${dest}`);
+  } else {
+    console.log(`Exists:  ${dest} (skipped)`);
+  }
+}
+
+// Add hooks to settings.json
+const settingsPath = join(CLAUDE_DIR, 'settings.json');
+let settings = {};
+
+if (existsSync(settingsPath)) {
+  settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+}
+
+// Read our hooks config
+const hooks = JSON.parse(readFileSync(join(PROJECT_ROOT, 'hooks', 'hooks.json'), 'utf-8'));
+
+// Update loader path to absolute (forward slashes for cross-platform)
+const loaderPath = join(PROJECT_ROOT, 'src', 'loader.js').replace(/\\/g, '/');
+hooks.SessionStart[0].hooks[0].command = `bun "${loaderPath}"`;
+
+// Merge hooks (preserve existing hooks, add ours)
+settings.hooks = settings.hooks || {};
+settings.hooks.SessionStart = hooks.SessionStart;
+settings.hooks.PreCompact = hooks.PreCompact;
+
+writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+console.log(`\nUpdated: ${settingsPath}`);
+
+console.log(`
+cc-brain installed!
+
+Brain location: ${BRAIN_DIR}
+
+Memory tiers:
+  T1 (always):   user.md, preferences.md
+  T2 (project):  projects/{name}/context.md
+  T3 (archive):  projects/{name}/archive/
+
+Hooks installed:
+  SessionStart → loads T1 + T2 into context
+  PreCompact   → saves important bits before compaction
+
+Edit your brain:
+  ${BRAIN_DIR}/user.md
+  ${BRAIN_DIR}/preferences.md
+`);

package/scripts/uninstall.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * Uninstall cc-brain
+ * Removes hooks from settings.json
+ * Use --purge to also delete brain data
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const HOME = homedir();
+const CLAUDE_DIR = join(HOME, '.claude');
+const BRAIN_DIR = join(CLAUDE_DIR, 'brain');
+const SETTINGS_PATH = join(CLAUDE_DIR, 'settings.json');
+
+const purge = process.argv.includes('--purge');
+
+console.log('Uninstalling cc-brain...\n');
+
+// Remove hooks from settings.json
+if (existsSync(SETTINGS_PATH)) {
+  const settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+
+  if (settings.hooks) {
+    delete settings.hooks.SessionStart;
+    delete settings.hooks.PreCompact;
+
+    // Clean up empty hooks object
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+    console.log(`Removed hooks from: ${SETTINGS_PATH}`);
+  } else {
+    console.log('No hooks found in settings.json');
+  }
+} else {
+  console.log('No settings.json found');
+}
+
+// Optionally remove brain data
+if (purge) {
+  if (existsSync(BRAIN_DIR)) {
+    rmSync(BRAIN_DIR, { recursive: true, force: true });
+    console.log(`Deleted: ${BRAIN_DIR}`);
+  } else {
+    console.log('No brain directory found');
+  }
+  console.log('\ncc-brain completely removed (hooks + data).');
+} else {
+  console.log(`
+cc-brain hooks removed.
+
+Brain data preserved at: ${BRAIN_DIR}
+
+To also delete brain data, run:
+  bun scripts/uninstall.js --purge
+`);
+}

package/skills/brain.md

@@ -0,0 +1,55 @@
+---
+name: brain
+description: View current brain state (what Claude remembers about you)
+user_invocable: true
+---
+
+# View Brain State
+
+Show the user what's currently in persistent memory.
+
+## Instructions
+
+1. **Show Tier 1** (always loaded):
+```bash
+cat ~/.claude/brain/user.md
+cat ~/.claude/brain/preferences.md
+```
+
+2. **Show Tier 2** (current project):
+```bash
+bun src/project-id.js --path
+# Then read context.md from that path
+```
+
+3. **Show Tier 3 stats**:
+```bash
+bun src/archive.js stats
+```
+
+4. **Format output** showing:
+   - T1: User profile and preferences
+   - T2: Current project context
+   - T3: Archive statistics (count, date range, size)
+
+5. **Note any empty sections** or missing files
+
+6. **Remind user** of available commands:
+   - `/save` - Update brain from session
+   - `/recall <query>` - Search archive
+   - `bun src/archive.js list` - List all archive entries
+   - `bun src/archive.js prune --keep 20` - Prune old entries
+   - Direct file edits for precision
+
+## Project Identity
+
+Show the project ID being used:
+```bash
+bun src/project-id.js
+```
+
+If using directory name fallback, suggest:
+```bash
+bun src/project-id.js --init
+```
+to create a stable `.brain-id` file.

package/skills/recall.md

@@ -0,0 +1,44 @@
+---
+name: recall
+description: Search brain archive for past context and decisions
+args: query
+user_invocable: true
+---
+
+# Recall from Brain Archive
+
+Search Tier 3 archive for historical context.
+
+## Instructions
+
+The user wants to recall: `$ARGUMENTS`
+
+1. **Run the search**:
+```bash
+bun src/recall.js "$ARGUMENTS"
+```
+
+2. **For regex patterns or context**:
+```bash
+bun src/recall.js "$ARGUMENTS" --context
+```
+
+3. **Present the results** to the user:
+   - What was found
+   - When it was recorded (from dates)
+   - Key relevant details
+
+4. **If nothing found**, let the user know and suggest:
+   - Different search terms
+   - Checking T2 context.md for recent info
+
+## Examples
+
+User: `/recall authentication`
+→ Searches archive for anything about auth decisions, implementations, issues
+
+User: `/recall why did we choose bun`
+→ Look for decision rationale in archive
+
+User: `/recall API.*endpoint`
+→ Regex search for API endpoint mentions

package/skills/save.md

@@ -0,0 +1,73 @@
+---
+name: save
+description: Save important context to brain memory
+user_invocable: true
+---
+
+# Save to Brain
+
+Save important information from this session to persistent memory.
+
+## Instructions
+
+1. **Analyze this session** and identify what's worth saving:
+   - New insights about the user (T1 - rare)
+   - New code/tool preferences (T1 - rare)
+   - Project decisions + rationale (T2 - common)
+   - Current focus/state (T2 - common)
+   - Session summary (T3 - if significant work done)
+
+2. **Build the save payload** as JSON:
+
+```json
+{
+  "t1_user": {
+    "Communication Style": ["new insight 1", "new insight 2"],
+    "Pet Peeves": ["discovered pet peeve"]
+  },
+  "t1_prefs": {
+    "Code Style": ["preference learned"],
+    "Tools": ["tool preference"]
+  },
+  "t2": {
+    "what": "One-line project description",
+    "focus": ["current task 1", "current task 2"],
+    "decisions": {
+      "Decision made": "rationale for why"
+    },
+    "files": {
+      "path/to/file.js": "what it does"
+    },
+    "blockers": ["any blockers"]
+  },
+  "t3": "Summary of significant work done this session."
+}
+```
+
+3. **Preview changes** with dry-run:
+```bash
+bun src/saver.js --dry-run --json '<payload>'
+```
+
+4. **Apply changes** if preview looks good:
+```bash
+bun src/saver.js --json '<payload>'
+```
+
+5. **Report** what was saved.
+
+## Rules
+
+- Only include tiers that have new information
+- T1 updates are rare - only genuine new user insights
+- T2 updates are common - project state changes frequently
+- T3 is optional - only for significant sessions
+- REPLACE outdated info, don't append endlessly
+- Decisions need rationale (the "why")
+
+## Size Limits
+
+- T1 user.md: 40 lines max
+- T1 preferences.md: 40 lines max
+- T2 context.md: 120 lines max
+- T3 archive: unlimited (but keep summaries concise)