cc-brain 0.1.3 → 0.1.4

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <h1 align="center">🧠 cc-brain</h1>
+  <h1 align="center">cc-brain</h1>
   <p align="center">
     <strong>Persistent memory for Claude Code</strong><br>
     <em>Remember context across sessions</em>
@@ -14,9 +14,10 @@
 </p>
 
 <p align="center">
-  <a href="#installation">Installation</a> •
-  <a href="#how-it-works">How It Works</a> •
-  <a href="#commands">Commands</a> •
+  <a href="#installation">Installation</a> -
+  <a href="#how-it-works">How It Works</a> -
+  <a href="#architecture">Architecture</a> -
+  <a href="#commands">Commands</a> -
   <a href="#cli">CLI</a>
 </p>
 
@@ -24,7 +25,7 @@
 
 ## The Problem
 
-Claude Code sessions are **ephemeral**. When context fills up or you start a new session, everything is forgotten. Your preferences, project decisions, debugging history — gone.
+Claude Code sessions are **ephemeral**. When context fills up or you start a new session, everything is forgotten. Your preferences, project decisions, debugging history -- gone.
 
 ## The Solution
 
@@ -70,7 +71,7 @@ claude plugins add cc-brain
 └── projects/{id}/
     ├── context.md       # Current project state
     └── archive/         # Session history
-        └── 2025-01-31.md
+        └── 2025-01-31-143052.md
 ```
 
 ### Memory Tiers
@@ -85,17 +86,65 @@ claude plugins add cc-brain
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│  Session Start  │────▶│  Brain Loaded   │────▶│   You Work...   │
+│  Session Start  │────>│  Brain Loaded   │────>│   You Work...   │
 └─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                          │
 ┌─────────────────┐     ┌─────────────────┐              │
-│  Next Session   │◀────│  Brain Saved    │◀─────────────┘
+│  Next Session   │<────│  Brain Saved    │<─────────────┘
 └─────────────────┘     └─────────────────┘
                          (before compaction)
 ```
 
 ---
 
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    Claude Code                        │
+│                                                      │
+│  SessionStart hook ──> loader.js ──> XML output      │
+│                         │                            │
+│                         ├── T1: <user-profile>       │
+│                         ├── T1: <preferences>        │
+│                         ├── T2: <project id="...">   │
+│                         └── T3: <archive hint />     │
+│                                                      │
+│  PreCompact hook ──> saver.js ──> atomic writes      │
+│                         │                            │
+│                         ├── validates input shape     │
+│                         ├── enforces line limits      │
+│                         ├── warns at 80% capacity     │
+│                         └── safeWriteFileSync()       │
+│                                                      │
+│  /recall skill ──> recall.js ──> scored results      │
+│                         │                            │
+│                         ├── regex with safe fallback  │
+│                         ├── header match scoring      │
+│                         └── TTY-aware color output    │
+└──────────────────────────────────────────────────────┘
+                          │
+                          v
+            ~/.claude/brain/ (persistent)
+```
+
+### Data Flow
+
+1. **SessionStart** - `loader.js` loads T1 + T2 into XML-tagged sections, auto-prunes archives older than 90 days
+2. **PreCompact** - Agent analyzes session, calls `saver.js` with structured JSON payload
+3. **Manual** - `/save` skill triggers the saver, `/recall` searches the archive
+4. **Archive** - Each save creates `YYYY-MM-DD-HHMMSS.md` (one file per session, no collisions)
+
+### Design Decisions
+
+- **Atomic writes** - All file writes use temp file + rename to prevent corruption
+- **Cross-runtime** - Works in both Node (>=18) and Bun via `isMainModule()` helper
+- **Hook preservation** - Install/uninstall detect cc-brain hooks by content matching, never overwrite user's other hooks
+- **XML output** - Loader wraps content in semantic tags (`<user-profile>`, `<preferences>`, `<project>`) for reliable Claude parsing
+- **Input validation** - Saver checks shape, key names, and types before writing
+
+---
+
 ## Commands
 
 Use these skills in Claude Code:
@@ -112,14 +161,15 @@ Use these skills in Claude Code:
 
 ```bash
 # Setup
-cc-brain install              # Install hooks
-cc-brain uninstall            # Remove hooks
+cc-brain install              # Install hooks (merges with existing)
+cc-brain uninstall            # Remove hooks (preserves user hooks)
 cc-brain uninstall --purge    # Remove everything
 
 # Search & Archive
-cc-brain recall "query"       # Search archive
+cc-brain recall "query"       # Search archive (scored results)
+cc-brain recall "query" --context   # Show surrounding lines
 cc-brain archive list         # List entries
-cc-brain archive stats        # Show statistics
+cc-brain archive stats        # Statistics (avg size, time span)
 cc-brain archive prune --keep 20
 
 # Project Identity
@@ -127,11 +177,52 @@ cc-brain project-id --init    # Create stable .brain-id
 
 # Manual Save
 cc-brain save --dry-run --json '{"t2": {"focus": "testing"}}'
-cc-brain save --json '{"t2": {"focus": "testing"}}'
+cc-brain save --json '{"t3": "Added search functionality"}'
 ```
 
 ---
 
+## Project Structure
+
+```
+src/
+  utils.js            Shared utilities (safeWriteFileSync, isMainModule)
+  loader.js           Loads T1+T2 into XML context, auto-prunes archive
+  saver.js            Structured saver with validation, limits, atomic writes
+  recall.js           Scored archive search with safe regex and color detection
+  archive.js          Archive management (list, prune, stats)
+  project-id.js       Stable project identity (.brain-id)
+bin/
+  cc-brain.js         CLI entry point with fast runtime detection
+hooks/
+  hooks.json          Hook configuration (SessionStart, PreCompact)
+skills/
+  save.md             /save skill
+  recall.md           /recall skill
+  brain.md            /brain skill
+scripts/
+  install.js          Install hooks (merges, preserves existing)
+  uninstall.js        Remove hooks (filters cc-brain only)
+```
+
+---
+
+## Features
+
+- **Persistent memory** across sessions and compactions
+- **Structured saving** with JSON validation and dry-run preview
+- **Input validation** with shape checking, key allowlist, type enforcement
+- **Capacity warnings** at 80% of line limits before rejecting
+- **Atomic file writes** via temp + rename to prevent corruption
+- **Scored search** with regex safe fallback and header-weighted ranking
+- **Smart color output** that detects TTY and respects NO_COLOR
+- **Auto-prune** removes archive entries older than 90 days
+- **Hook-safe install** that merges without clobbering user config
+- **Cross-runtime** support for Node (>=18) and Bun
+- **Stable project identity** via `.brain-id` that survives renames
+
+---
+
 ## Project Identity
 
 By default, projects are identified by directory name. For stable identity that survives renames:
@@ -162,4 +253,4 @@ cc-brain uninstall --purge    # Remove everything
 
 ## License
 
-MIT © [tripzcodes](https://github.com/tripzcodes)
+MIT - [tripzcodes](https://github.com/tripzcodes)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "cc-brain",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Persistent memory system for Claude Code - remembers context across sessions",
   "type": "module",
   "bin": {
-    "cc-brain": "./bin/cc-brain.js"
+    "cc-brain": "bin/cc-brain.js"
   },
   "files": [
     "bin",

package/scripts/install.js

@@ -93,6 +93,22 @@ settings.hooks.PreCompact = mergeHookArray(settings.hooks.PreCompact, hooks.PreC
 writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 console.log(`\nUpdated: ${settingsPath}`);
 
+// --- Install Skills to ~/.claude/skills/ ---
+const SKILLS_DIR = join(CLAUDE_DIR, 'skills');
+const skillNames = ['save', 'recall', 'brain'];
+
+for (const name of skillNames) {
+  const skillDir = join(SKILLS_DIR, name);
+  mkdirSync(skillDir, { recursive: true });
+  copyFileSync(
+    join(PROJECT_ROOT, 'skills', `${name}.md`),
+    join(skillDir, 'SKILL.md')
+  );
+}
+
+console.log(`\nInstalled skills to: ${SKILLS_DIR}`);
+console.log('  /save, /recall, /brain');
+
 console.log(`
 cc-brain installed!
 

package/scripts/uninstall.js

@@ -69,6 +69,18 @@ if (existsSync(SETTINGS_PATH)) {
   console.log('No settings.json found');
 }
 
+// --- Remove Skills from ~/.claude/skills/ ---
+const SKILLS_DIR = join(CLAUDE_DIR, 'skills');
+const skillNames = ['save', 'recall', 'brain'];
+
+for (const name of skillNames) {
+  const skillDir = join(SKILLS_DIR, name);
+  if (existsSync(skillDir)) {
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`Removed: ${skillDir}`);
+  }
+}
+
 // Optionally remove brain data
 if (purge) {
   if (existsSync(BRAIN_DIR)) {