cc-brain 0.1.2 → 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/bin/cc-brain.js

@@ -15,13 +15,17 @@ const ROOT = join(__dirname, '..');
 const command = process.argv[2];
 const args = process.argv.slice(3);
 
-// Check for bun, fallback to node
+// Check for bun, fallback to node (fast path avoids spawning a process)
 let runtime = 'node';
-try {
-  execSync('bun --version', { stdio: 'ignore' });
+if (process.versions.bun || process.env.BUN_INSTALL) {
   runtime = 'bun';
-} catch {
-  // bun not available, use node
+} else {
+  try {
+    execSync('bun --version', { stdio: 'ignore', timeout: 2000 });
+    runtime = 'bun';
+  } catch {
+    // bun not available, use node
+  }
 }
 
 const commands = {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "cc-brain",
-  "version": "0.1.2",
+  "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/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-brain",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Persistent memory system for Claude Code",
   "skills": [
     "skills/save.md",

package/scripts/install.js

@@ -6,13 +6,15 @@
  */
 
 import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
 
 const HOME = homedir();
 const CLAUDE_DIR = join(HOME, '.claude');
 const BRAIN_DIR = join(CLAUDE_DIR, 'brain');
-const PROJECT_ROOT = join(import.meta.dirname, '..');
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = join(__dirname, '..');
 
 console.log('Installing cc-brain...\n');
 
@@ -68,14 +70,45 @@ const hooks = JSON.parse(readFileSync(join(PROJECT_ROOT, 'hooks', 'hooks.json'),
 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)
+// Merge hooks — preserve user's other hooks, replace/append ours
+function isCcBrainHook(entry) {
+  if (!entry || !entry.hooks) return false;
+  return entry.hooks.some(h =>
+    (h.command && h.command.includes('loader.js')) ||
+    (h.prompt && h.prompt.includes('structured saver'))
+  );
+}
+
+function mergeHookArray(existing, ours) {
+  if (!existing) return ours;
+  // Filter out old cc-brain hooks, then append ours
+  const filtered = existing.filter(entry => !isCcBrainHook(entry));
+  return [...filtered, ...ours];
+}
+
 settings.hooks = settings.hooks || {};
-settings.hooks.SessionStart = hooks.SessionStart;
-settings.hooks.PreCompact = hooks.PreCompact;
+settings.hooks.SessionStart = mergeHookArray(settings.hooks.SessionStart, hooks.SessionStart);
+settings.hooks.PreCompact = mergeHookArray(settings.hooks.PreCompact, hooks.PreCompact);
 
 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

@@ -19,21 +19,49 @@ const purge = process.argv.includes('--purge');
 
 console.log('Uninstalling cc-brain...\n');
 
-// Remove hooks from settings.json
+// Remove cc-brain hooks from settings.json (preserves user's other hooks)
+function isCcBrainHook(entry) {
+  if (!entry || !entry.hooks) return false;
+  return entry.hooks.some(h =>
+    (h.command && h.command.includes('loader.js')) ||
+    (h.prompt && h.prompt.includes('structured saver'))
+  );
+}
+
 if (existsSync(SETTINGS_PATH)) {
-  const settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+  } catch (e) {
+    console.error(`Error: Could not parse ${SETTINGS_PATH}`);
+    console.error(`  ${e.message}`);
+    console.error('Fix the file manually or delete it, then re-run.');
+    process.exit(1);
+  }
 
   if (settings.hooks) {
-    delete settings.hooks.SessionStart;
-    delete settings.hooks.PreCompact;
+    let removed = false;
+
+    for (const event of ['SessionStart', 'PreCompact']) {
+      if (Array.isArray(settings.hooks[event])) {
+        const before = settings.hooks[event].length;
+        settings.hooks[event] = settings.hooks[event].filter(entry => !isCcBrainHook(entry));
+        if (settings.hooks[event].length < before) removed = true;
+        if (settings.hooks[event].length === 0) delete settings.hooks[event];
+      }
+    }
 
     // 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}`);
+    if (removed) {
+      writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+      console.log(`Removed cc-brain hooks from: ${SETTINGS_PATH}`);
+    } else {
+      console.log('No cc-brain hooks found in settings.json');
+    }
   } else {
     console.log('No hooks found in settings.json');
   }
@@ -41,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)) {

package/src/archive.js

@@ -16,6 +16,7 @@ import { existsSync, readdirSync, statSync, unlinkSync, readFileSync } from 'fs'
 import { join } from 'path';
 import { homedir } from 'os';
 import { getProjectId } from './project-id.js';
+import { isMainModule } from './utils.js';
 
 const BRAIN_DIR = process.env.CC_BRAIN_DIR || join(homedir(), '.claude', 'brain');
 const PROJECT_ID = getProjectId();
@@ -70,11 +71,17 @@ function showStats() {
   const oldest = entries[entries.length - 1];
   const newest = entries[0];
 
+  const avgSize = totalSize / entries.length;
+  const spanMs = newest.date - oldest.date;
+  const spanDays = Math.round(spanMs / (1000 * 60 * 60 * 24));
+
   console.log(`Archive Statistics`);
   console.log(`──────────────────`);
   console.log(`Location:  ${ARCHIVE_DIR}`);
   console.log(`Entries:   ${entries.length}`);
   console.log(`Total:     ${(totalSize / 1024).toFixed(1)}kb`);
+  console.log(`Average:   ${(avgSize / 1024).toFixed(1)}kb per entry`);
+  console.log(`Span:      ${spanDays} days`);
   console.log(`Oldest:    ${oldest.date.toISOString().split('T')[0]} (${oldest.name})`);
   console.log(`Newest:    ${newest.date.toISOString().split('T')[0]} (${newest.name})`);
 }
@@ -144,41 +151,42 @@ function autoPrune(days = 90, silent = false) {
 }
 
 // CLI
-const args = process.argv.slice(2);
-const command = args[0];
-
-if (command === 'list') {
-  listArchive();
-} else if (command === 'stats') {
-  showStats();
-} else if (command === 'prune') {
-  const keepIdx = args.indexOf('--keep');
-  const olderIdx = args.indexOf('--older-than');
-
-  if (keepIdx !== -1) {
-    const keep = parseInt(args[keepIdx + 1], 10);
-    if (isNaN(keep)) {
-      console.error('Error: --keep requires a number');
-      process.exit(1);
-    }
-    pruneByCount(keep);
-  } else if (olderIdx !== -1) {
-    const ageStr = args[olderIdx + 1];
-    const days = parseInt(ageStr, 10);
-    if (isNaN(days)) {
-      console.error('Error: --older-than requires a number (e.g., 90d)');
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command === 'list') {
+    listArchive();
+  } else if (command === 'stats') {
+    showStats();
+  } else if (command === 'prune') {
+    const keepIdx = args.indexOf('--keep');
+    const olderIdx = args.indexOf('--older-than');
+
+    if (keepIdx !== -1) {
+      const keep = parseInt(args[keepIdx + 1], 10);
+      if (isNaN(keep) || keep <= 0) {
+        console.error('Error: --keep requires a positive number');
+        process.exit(1);
+      }
+      pruneByCount(keep);
+    } else if (olderIdx !== -1) {
+      const ageStr = args[olderIdx + 1] || '';
+      if (!/^\d+d?$/.test(ageStr)) {
+        console.error('Error: --older-than requires format like "90" or "90d"');
+        process.exit(1);
+      }
+      const days = parseInt(ageStr, 10);
+      pruneByAge(days);
+    } else {
+      console.error('Error: prune requires --keep <n> or --older-than <days>');
       process.exit(1);
     }
-    pruneByAge(days);
-  } else {
-    console.error('Error: prune requires --keep <n> or --older-than <days>');
-    process.exit(1);
-  }
-} else if (command === 'auto-prune') {
-  const days = parseInt(args[1], 10) || 90;
-  autoPrune(days);
-} else if (command === '--help' || command === '-h' || !command) {
-  console.log(`Usage: bun src/archive.js <command> [options]
+  } else if (command === 'auto-prune') {
+    const days = parseInt(args[1], 10) || 90;
+    autoPrune(days);
+  } else if (command === '--help' || command === '-h' || !command) {
+    console.log(`Usage: bun src/archive.js <command> [options]
 
 Commands:
   list                      List all archive entries
@@ -191,9 +199,10 @@ Examples:
   bun src/archive.js list
   bun src/archive.js prune --keep 20
   bun src/archive.js prune --older-than 90d`);
-} else {
-  console.error(`Unknown command: ${command}`);
-  process.exit(1);
+  } else {
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+  }
 }
 
 // Export for use as module

package/src/loader.js

@@ -49,6 +49,8 @@ function readIfExists(path, limit = null) {
 }
 
 function ensureProjectDir() {
+  if (!PROJECT_ID) return;
+
   const archiveDir = join(PROJECT_PATH, 'archive');
 
   if (!existsSync(PROJECT_PATH)) {
@@ -81,7 +83,7 @@ function autoPruneArchive() {
       }
     }
   } catch (e) {
-    // Ignore errors during auto-prune
+    console.error(`[cc-brain] Auto-prune warning: ${e.message}`);
   }
 
   return deleted;
@@ -108,34 +110,45 @@ function loadBrain() {
 
   const user = readIfExists(join(BRAIN_DIR, 'user.md'), LIMITS.user);
   if (user && user.trim()) {
+    parts.push('<user-profile>');
     parts.push(user);
+    parts.push('</user-profile>');
   }
 
   const prefs = readIfExists(join(BRAIN_DIR, 'preferences.md'), LIMITS.preferences);
   if (prefs && prefs.trim()) {
+    parts.push('<preferences>');
     parts.push(prefs);
+    parts.push('</preferences>');
   }
 
   // ═══════════════════════════════════════════
   // TIER 2: Project context (current project)
   // ═══════════════════════════════════════════
 
-  const projectContext = join(PROJECT_PATH, 'context.md');
-  const context = readIfExists(projectContext, LIMITS.context);
-  if (context && context.trim()) {
-    parts.push(`## Project: ${PROJECT_ID}\n`);
-    parts.push(context);
+  if (!PROJECT_ID) {
+    parts.push('<!-- T2 skipped: no project ID -->');
+  } else {
+    const projectContext = join(PROJECT_PATH, 'context.md');
+    const context = readIfExists(projectContext, LIMITS.context);
+    if (context && context.trim()) {
+      parts.push(`<project id="${PROJECT_ID}">`);
+      parts.push(context);
+      parts.push('</project>');
+    }
   }
 
   // ═══════════════════════════════════════════
   // TIER 3: Archive (NOT loaded, just noted)
   // ═══════════════════════════════════════════
 
-  const archiveDir = join(PROJECT_PATH, 'archive');
-  if (existsSync(archiveDir)) {
-    const archiveFiles = readdirSync(archiveDir).filter(f => f.endsWith('.md'));
-    if (archiveFiles.length > 0) {
-      parts.push(`\n[Archive: ${archiveFiles.length} entries. Use /recall to search.]`);
+  if (PROJECT_ID) {
+    const archiveDir = join(PROJECT_PATH, 'archive');
+    if (existsSync(archiveDir)) {
+      const archiveFiles = readdirSync(archiveDir).filter(f => f.endsWith('.md'));
+      if (archiveFiles.length > 0) {
+        parts.push(`<archive entries="${archiveFiles.length}" hint="Use /recall to search" />`);
+      }
     }
   }
 
@@ -147,7 +160,7 @@ function loadBrain() {
 const brain = loadBrain();
 
 // Only output if there's actual content
-if (brain.replace(/<\/?brain>/g, '').replace(/\[.*?\]/g, '').trim()) {
+if (brain.replace(/<\/?brain>/g, '').replace(/<[^>]+\/>/g, '').replace(/<[^>]+>[^<]*<\/[^>]+>/g, '').replace(/\[.*?\]/g, '').replace(/<!--.*?-->/g, '').trim()) {
   console.log(brain);
   console.log('\n---');
   console.log('Above is your persistent memory. Use /save to update, /recall to search archive.');

package/src/project-id.js

@@ -17,6 +17,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
+import { homedir } from 'os';
+import { isMainModule } from './utils.js';
 
 const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const BRAIN_ID_FILE = join(PROJECT_DIR, '.brain-id');
@@ -47,12 +49,12 @@ function initBrainId() {
 }
 
 function getProjectBrainPath() {
-  const brainDir = process.env.CC_BRAIN_DIR || join(process.env.HOME || process.env.USERPROFILE, '.claude', 'brain');
+  const brainDir = process.env.CC_BRAIN_DIR || join(homedir(), '.claude', 'brain');
   return join(brainDir, 'projects', getProjectId());
 }
 
 // CLI (only when run directly)
-if (import.meta.main) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
 
   if (args.includes('--init')) {

package/src/recall.js

@@ -14,15 +14,28 @@ import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { getProjectId } from './project-id.js';
+import { isMainModule } from './utils.js';
 
 const BRAIN_DIR = process.env.CC_BRAIN_DIR || join(homedir(), '.claude', 'brain');
 const PROJECT_ID = getProjectId();
 const ARCHIVE_DIR = join(BRAIN_DIR, 'projects', PROJECT_ID, 'archive');
 const CONTEXT_DIR = join(BRAIN_DIR, 'projects', PROJECT_ID);
 
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function buildRegex(query) {
+  try {
+    return new RegExp(query, 'i');
+  } catch {
+    return new RegExp(escapeRegex(query), 'i');
+  }
+}
+
 function searchArchive(query, options = {}) {
   const results = [];
-  const regex = new RegExp(query, 'gi');
+  const regex = buildRegex(query);
 
   // Search archive files
   if (existsSync(ARCHIVE_DIR)) {
@@ -62,12 +75,19 @@ function searchArchive(query, options = {}) {
         const dateMatch = file.match(/(\d{4}-\d{2}-\d{2})/);
         const date = dateMatch ? dateMatch[1] : 'unknown';
 
+        // Score: header matches (#) get bonus weight
+        let score = matches.length;
+        for (const m of matches) {
+          if (/^#{1,6}\s/.test(m.text)) score += 2;
+        }
+
         results.push({
           file,
           date,
           path,
           matches,
-          matchCount: matches.length
+          matchCount: matches.length,
+          score
         });
       }
     }
@@ -90,27 +110,45 @@ function searchArchive(query, options = {}) {
     }
 
     if (matches.length > 0) {
+      let score = matches.length;
+      for (const m of matches) {
+        if (/^#{1,6}\s/.test(m.text)) score += 2;
+      }
+
       results.unshift({
         file: 'context.md',
         date: 'current',
         path: contextPath,
         matches,
-        matchCount: matches.length
+        matchCount: matches.length,
+        score
       });
     }
   }
 
-  // Sort by match count (most relevant first), then by date
+  // Sort by score (most relevant first), then by date
   results.sort((a, b) => {
     if (a.date === 'current') return -1;
     if (b.date === 'current') return 1;
-    if (b.matchCount !== a.matchCount) return b.matchCount - a.matchCount;
+    if (b.score !== a.score) return b.score - a.score;
     return b.date.localeCompare(a.date);
   });
 
   return results;
 }
 
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function highlight(text, query) {
+  if (!useColor) return text;
+  try {
+    const highlightRegex = new RegExp(`(${escapeRegex(query)})`, 'gi');
+    return text.replace(highlightRegex, '\x1b[33m$1\x1b[0m');
+  } catch {
+    return text;
+  }
+}
+
 function formatResults(results, query) {
   if (results.length === 0) {
     console.log(`No results found for: "${query}"`);
@@ -124,11 +162,7 @@ function formatResults(results, query) {
     console.log(`── ${result.file} (${result.date}) ──`);
 
     for (const match of result.matches) {
-      // Highlight the match
-      const highlighted = match.text.replace(
-        new RegExp(`(${query})`, 'gi'),
-        '\x1b[33m$1\x1b[0m'
-      );
+      const highlighted = highlight(match.text, query);
       console.log(`  L${match.line}: ${highlighted}`);
 
       if (match.context && match.context.length > 0) {
@@ -142,7 +176,7 @@ function formatResults(results, query) {
 }
 
 // CLI
-if (import.meta.main) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
 
   if (args.length === 0 || args.includes('--help') || args.includes('-h')) {

package/src/saver.js

@@ -18,10 +18,11 @@
  * }
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { getProjectId } from './project-id.js';
+import { safeWriteFileSync, isMainModule } from './utils.js';
 
 const BRAIN_DIR = process.env.CC_BRAIN_DIR || join(homedir(), '.claude', 'brain');
 const PROJECT_ID = getProjectId();
@@ -71,9 +72,11 @@ function formatSection(title, data) {
   return lines.join('\n');
 }
 
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 function mergeContent(existing, updates, template) {
-  // For now, replace sections that are updated
-  // Future: smarter merging
   if (!existing) {
     existing = template || '';
   }
@@ -81,15 +84,17 @@ function mergeContent(existing, updates, template) {
   let result = existing;
 
   for (const [section, content] of Object.entries(updates)) {
-    const sectionHeader = `## ${section}`;
     const newContent = formatSection(section, content);
 
     if (!newContent) continue;
 
-    // Find and replace section, or append
-    const sectionRegex = new RegExp(`## ${section}[\\s\\S]*?(?=\\n## |$)`, 'g');
-    if (sectionRegex.test(result)) {
-      result = result.replace(sectionRegex, newContent + '\n\n');
+    // Anchor to line start with m flag, escape section name for regex safety
+    const sectionRegex = new RegExp(
+      `^## ${escapeRegex(section)}[\\s\\S]*?(?=\\n## |$)`, 'm'
+    );
+    const replaced = result.replace(sectionRegex, newContent + '\n\n');
+    if (replaced !== result) {
+      result = replaced;
     } else {
       result = result.trim() + '\n\n' + newContent + '\n';
     }
@@ -163,10 +168,43 @@ ${summary}
 `;
 }
 
+const VALID_KEYS = new Set(['t1_user', 't1_prefs', 't2', 't3']);
+
+function validateInputShape(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return ['Input must be a JSON object'];
+  }
+  const errors = [];
+  for (const key of Object.keys(input)) {
+    if (!VALID_KEYS.has(key)) {
+      errors.push(`Unknown key: "${key}" (valid: ${[...VALID_KEYS].join(', ')})`);
+    }
+  }
+  if (input.t1_user !== undefined && (typeof input.t1_user !== 'object' || Array.isArray(input.t1_user))) {
+    errors.push('t1_user must be an object');
+  }
+  if (input.t1_prefs !== undefined && (typeof input.t1_prefs !== 'object' || Array.isArray(input.t1_prefs))) {
+    errors.push('t1_prefs must be an object');
+  }
+  if (input.t2 !== undefined && (typeof input.t2 !== 'object' || Array.isArray(input.t2))) {
+    errors.push('t2 must be an object');
+  }
+  if (input.t3 !== undefined && typeof input.t3 !== 'string') {
+    errors.push('t3 must be a string');
+  }
+  return errors;
+}
+
 function validateAndPrepare(input, dryRun = false) {
   const changes = [];
   const errors = [];
 
+  // Validate input shape
+  const shapeErrors = validateInputShape(input);
+  if (shapeErrors.length > 0) {
+    return { changes: [], errors: shapeErrors };
+  }
+
   // T1 User
   if (input.t1_user) {
     const existing = readFile(PATHS.t1_user);
@@ -176,6 +214,9 @@ function validateAndPrepare(input, dryRun = false) {
     if (lines > LIMITS.t1_user) {
       errors.push(`t1_user exceeds limit: ${lines}/${LIMITS.t1_user} lines`);
     } else {
+      if (lines > LIMITS.t1_user * 0.8) {
+        console.warn(`Warning: t1_user at ${lines}/${LIMITS.t1_user} lines (${Math.round(lines / LIMITS.t1_user * 100)}%)`);
+      }
       changes.push({
         tier: 't1_user',
         path: PATHS.t1_user,
@@ -195,6 +236,9 @@ function validateAndPrepare(input, dryRun = false) {
     if (lines > LIMITS.t1_prefs) {
       errors.push(`t1_prefs exceeds limit: ${lines}/${LIMITS.t1_prefs} lines`);
     } else {
+      if (lines > LIMITS.t1_prefs * 0.8) {
+        console.warn(`Warning: t1_prefs at ${lines}/${LIMITS.t1_prefs} lines (${Math.round(lines / LIMITS.t1_prefs * 100)}%)`);
+      }
       changes.push({
         tier: 't1_prefs',
         path: PATHS.t1_prefs,
@@ -214,6 +258,9 @@ function validateAndPrepare(input, dryRun = false) {
     if (lines > LIMITS.t2) {
       errors.push(`t2 exceeds limit: ${lines}/${LIMITS.t2} lines`);
     } else {
+      if (lines > LIMITS.t2 * 0.8) {
+        console.warn(`Warning: t2 at ${lines}/${LIMITS.t2} lines (${Math.round(lines / LIMITS.t2 * 100)}%)`);
+      }
       changes.push({
         tier: 't2',
         path: PATHS.t2,
@@ -224,22 +271,21 @@ function validateAndPrepare(input, dryRun = false) {
     }
   }
 
-  // T3 Archive
+  // T3 Archive (each session gets its own file)
   if (input.t3) {
-    const date = new Date().toISOString().split('T')[0];
-    const archivePath = join(PATHS.t3_dir, `${date}.md`);
-    const existing = readFile(archivePath);
-    const updated = existing
-      ? existing + '\n---\n\n' + generateT3Content(input.t3)
-      : generateT3Content(input.t3);
+    const now = new Date();
+    const date = now.toISOString().split('T')[0];
+    const time = now.toTimeString().split(' ')[0].replace(/:/g, '');
+    const archivePath = join(PATHS.t3_dir, `${date}-${time}.md`);
+    const updated = generateT3Content(input.t3);
 
     changes.push({
       tier: 't3',
       path: archivePath,
-      before: existing,
+      before: null,
       after: updated,
       lines: countLines(updated),
-      isNew: !existing
+      isNew: true
     });
   }
 
@@ -255,18 +301,18 @@ function showDiff(change) {
   } else if (!change.before) {
     console.log(`│ Status: CREATE`);
   } else {
-    console.log(`│ Status: UPDATE`);
+    const beforeLines = countLines(change.before);
+    console.log(`│ Status: UPDATE (${beforeLines} → ${change.lines} lines)`);
   }
 
   console.log('├──────────────────────────────');
 
-  // Show content preview (first 10 lines)
-  const preview = change.after.split('\n').slice(0, 10);
+  const preview = change.after.split('\n').slice(0, 15);
   for (const line of preview) {
     console.log(`│ ${line}`);
   }
-  if (change.lines > 10) {
-    console.log(`│ ... (${change.lines - 10} more lines)`);
+  if (change.lines > 15) {
+    console.log(`│ ... (${change.lines - 15} more lines)`);
   }
 
   console.log('└──────────────────────────────');
@@ -280,13 +326,13 @@ function applyChanges(changes) {
       mkdirSync(dir, { recursive: true });
     }
 
-    writeFileSync(change.path, change.after);
+    safeWriteFileSync(change.path, change.after);
     console.log(`Saved: ${change.tier} → ${change.path}`);
   }
 }
 
 // CLI
-if (import.meta.main) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
 
   if (args.includes('--help') || args.includes('-h')) {

package/src/utils.js

@@ -0,0 +1,54 @@
+import { writeFileSync, renameSync, unlinkSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Atomic file write: write to temp file then rename.
+ * Handles Windows limitation where rename fails if target exists.
+ */
+export function safeWriteFileSync(filePath, content) {
+  const resolved = resolve(filePath);
+  const tmp = `${resolved}.tmp.${process.pid}`;
+
+  try {
+    writeFileSync(tmp, content);
+
+    // On Windows, renameSync fails if target exists — remove first
+    if (process.platform === 'win32' && existsSync(resolved)) {
+      unlinkSync(resolved);
+    }
+
+    renameSync(tmp, resolved);
+  } catch (err) {
+    // Clean up temp file on failure
+    try { unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * Cross-runtime check for whether a module is the main entry point.
+ * Works in both Node and Bun.
+ */
+export function isMainModule(importMetaUrl) {
+  // Bun sets import.meta.main
+  if (typeof globalThis.Bun !== 'undefined') {
+    // When called from the main module in Bun, we compare resolved paths
+    try {
+      const modulePath = fileURLToPath(importMetaUrl);
+      const mainPath = process.argv[1];
+      return resolve(modulePath) === resolve(mainPath);
+    } catch {
+      return false;
+    }
+  }
+
+  // Node: compare resolved file paths
+  try {
+    const modulePath = fileURLToPath(importMetaUrl);
+    const mainPath = process.argv[1];
+    return resolve(modulePath) === resolve(mainPath);
+  } catch {
+    return false;
+  }
+}