cc-brain 0.1.0

package/src/archive.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * Archive Management
+ * List, prune, and manage T3 archive entries
+ *
+ * Usage:
+ *   bun src/archive.js list                     # List archive entries
+ *   bun src/archive.js stats                    # Show archive statistics
+ *   bun src/archive.js prune --keep 20          # Keep last 20 entries
+ *   bun src/archive.js prune --older-than 90d   # Delete entries older than 90 days
+ *   bun src/archive.js auto-prune               # Auto-prune (90 days), returns deleted list
+ */
+
+import { existsSync, readdirSync, statSync, unlinkSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getProjectId } from './project-id.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');
+
+function getArchiveEntries() {
+  if (!existsSync(ARCHIVE_DIR)) {
+    return [];
+  }
+
+  return readdirSync(ARCHIVE_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => {
+      const path = join(ARCHIVE_DIR, f);
+      const stat = statSync(path);
+      return {
+        name: f,
+        path,
+        date: stat.mtime,
+        size: stat.size
+      };
+    })
+    .sort((a, b) => b.date - a.date); // Newest first
+}
+
+function listArchive() {
+  const entries = getArchiveEntries();
+
+  if (entries.length === 0) {
+    console.log('Archive is empty.');
+    return;
+  }
+
+  console.log(`Archive: ${ARCHIVE_DIR}\n`);
+  for (const entry of entries) {
+    const date = entry.date.toISOString().split('T')[0];
+    const size = (entry.size / 1024).toFixed(1) + 'kb';
+    console.log(`  ${date}  ${size.padStart(8)}  ${entry.name}`);
+  }
+  console.log(`\nTotal: ${entries.length} entries`);
+}
+
+function showStats() {
+  const entries = getArchiveEntries();
+
+  if (entries.length === 0) {
+    console.log('Archive is empty.');
+    return;
+  }
+
+  const totalSize = entries.reduce((sum, e) => sum + e.size, 0);
+  const oldest = entries[entries.length - 1];
+  const newest = entries[0];
+
+  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(`Oldest:    ${oldest.date.toISOString().split('T')[0]} (${oldest.name})`);
+  console.log(`Newest:    ${newest.date.toISOString().split('T')[0]} (${newest.name})`);
+}
+
+function pruneByCount(keep) {
+  const entries = getArchiveEntries();
+  const toDelete = entries.slice(keep);
+
+  if (toDelete.length === 0) {
+    console.log(`Nothing to prune (${entries.length} entries, keeping ${keep})`);
+    return [];
+  }
+
+  for (const entry of toDelete) {
+    unlinkSync(entry.path);
+    console.log(`Deleted: ${entry.name}`);
+  }
+
+  console.log(`\nPruned ${toDelete.length} entries, kept ${keep}`);
+  return toDelete.map(e => e.name);
+}
+
+function pruneByAge(days) {
+  const entries = getArchiveEntries();
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+
+  const toDelete = entries.filter(e => e.date < cutoff);
+
+  if (toDelete.length === 0) {
+    console.log(`Nothing to prune (no entries older than ${days} days)`);
+    return [];
+  }
+
+  for (const entry of toDelete) {
+    unlinkSync(entry.path);
+    console.log(`Deleted: ${entry.name}`);
+  }
+
+  console.log(`\nPruned ${toDelete.length} entries older than ${days} days`);
+  return toDelete.map(e => e.name);
+}
+
+function autoPrune(days = 90, silent = false) {
+  const entries = getArchiveEntries();
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+
+  const toDelete = entries.filter(e => e.date < cutoff);
+
+  if (toDelete.length === 0) {
+    return [];
+  }
+
+  for (const entry of toDelete) {
+    unlinkSync(entry.path);
+  }
+
+  if (!silent) {
+    console.log(`Auto-pruned ${toDelete.length} archive entries older than ${days} days:`);
+    for (const entry of toDelete) {
+      console.log(`  - ${entry.name}`);
+    }
+  }
+
+  return toDelete.map(e => e.name);
+}
+
+// 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)');
+      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]
+
+Commands:
+  list                      List all archive entries
+  stats                     Show archive statistics
+  prune --keep <n>          Keep only the last n entries
+  prune --older-than <n>d   Delete entries older than n days
+  auto-prune [days]         Auto-prune entries older than days (default: 90)
+
+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);
+}
+
+// Export for use as module
+export { getArchiveEntries, autoPrune, ARCHIVE_DIR };

package/src/loader.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * Brain Loader
+ * Runs on SessionStart - injects persistent memory into context
+ *
+ * TIERS:
+ *   T1 (always):    user.md, preferences.md         ~40 lines each
+ *   T2 (project):   projects/{id}/context.md        ~120 lines
+ *   T3 (on-demand): projects/{id}/archive/          never auto-loaded
+ *
+ * Features:
+ *   - Uses .brain-id for stable project identity
+ *   - Auto-prunes archive entries older than 90 days (with warning)
+ */
+
+import { readFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getProjectId, getProjectBrainPath } from './project-id.js';
+
+const BRAIN_DIR = process.env.CC_BRAIN_DIR || join(homedir(), '.claude', 'brain');
+const PROJECT_ID = getProjectId();
+const PROJECT_PATH = getProjectBrainPath();
+
+// Size limits (lines)
+const LIMITS = {
+  user: 40,
+  preferences: 40,
+  context: 120
+};
+
+// Auto-prune settings
+const AUTO_PRUNE_DAYS = 90;
+
+function readIfExists(path, limit = null) {
+  if (!existsSync(path)) return null;
+
+  let content = readFileSync(path, 'utf-8');
+
+  if (limit) {
+    const lines = content.split('\n');
+    if (lines.length > limit) {
+      content = lines.slice(0, limit).join('\n') + '\n... (truncated)';
+    }
+  }
+
+  return content;
+}
+
+function ensureProjectDir() {
+  const archiveDir = join(PROJECT_PATH, 'archive');
+
+  if (!existsSync(PROJECT_PATH)) {
+    mkdirSync(PROJECT_PATH, { recursive: true });
+  }
+  if (!existsSync(archiveDir)) {
+    mkdirSync(archiveDir, { recursive: true });
+  }
+}
+
+function autoPruneArchive() {
+  const archiveDir = join(PROJECT_PATH, 'archive');
+  if (!existsSync(archiveDir)) return [];
+
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - AUTO_PRUNE_DAYS);
+
+  const deleted = [];
+
+  try {
+    const files = readdirSync(archiveDir).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+      const path = join(archiveDir, file);
+      const stat = statSync(path);
+
+      if (stat.mtime < cutoff) {
+        unlinkSync(path);
+        deleted.push(file);
+      }
+    }
+  } catch (e) {
+    // Ignore errors during auto-prune
+  }
+
+  return deleted;
+}
+
+function loadBrain() {
+  ensureProjectDir();
+
+  // Auto-prune old archive entries
+  const pruned = autoPruneArchive();
+
+  const parts = [];
+
+  parts.push('<brain>');
+
+  // Show pruned files warning
+  if (pruned.length > 0) {
+    parts.push(`[Auto-pruned ${pruned.length} archive entries older than ${AUTO_PRUNE_DAYS} days: ${pruned.join(', ')}]\n`);
+  }
+
+  // ═══════════════════════════════════════════
+  // TIER 1: Always loaded (core understanding)
+  // ═══════════════════════════════════════════
+
+  const user = readIfExists(join(BRAIN_DIR, 'user.md'), LIMITS.user);
+  if (user && user.trim()) {
+    parts.push(user);
+  }
+
+  const prefs = readIfExists(join(BRAIN_DIR, 'preferences.md'), LIMITS.preferences);
+  if (prefs && prefs.trim()) {
+    parts.push(prefs);
+  }
+
+  // ═══════════════════════════════════════════
+  // 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);
+  }
+
+  // ═══════════════════════════════════════════
+  // 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.]`);
+    }
+  }
+
+  parts.push('</brain>');
+
+  return parts.join('\n');
+}
+
+const brain = loadBrain();
+
+// Only output if there's actual content
+if (brain.replace(/<\/?brain>/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

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+/**
+ * Project Identity
+ * Provides stable project ID that survives directory renames
+ *
+ * Priority:
+ * 1. .brain-id file in project root (UUID)
+ * 2. Fall back to directory name
+ *
+ * Usage:
+ *   bun src/project-id.js           # Output current project ID
+ *   bun src/project-id.js --init    # Create .brain-id if not exists
+ *   bun src/project-id.js --path    # Output project brain path
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const BRAIN_ID_FILE = join(PROJECT_DIR, '.brain-id');
+
+function getProjectId() {
+  // Check for .brain-id file
+  if (existsSync(BRAIN_ID_FILE)) {
+    return readFileSync(BRAIN_ID_FILE, 'utf-8').trim();
+  }
+
+  // Fall back to directory name
+  return PROJECT_DIR.split(/[/\\]/).pop();
+}
+
+function initBrainId() {
+  if (existsSync(BRAIN_ID_FILE)) {
+    const existing = readFileSync(BRAIN_ID_FILE, 'utf-8').trim();
+    console.log(`Already exists: ${BRAIN_ID_FILE}`);
+    console.log(`ID: ${existing}`);
+    return existing;
+  }
+
+  const id = randomUUID();
+  writeFileSync(BRAIN_ID_FILE, id + '\n');
+  console.log(`Created: ${BRAIN_ID_FILE}`);
+  console.log(`ID: ${id}`);
+  return id;
+}
+
+function getProjectBrainPath() {
+  const brainDir = process.env.CC_BRAIN_DIR || join(process.env.HOME || process.env.USERPROFILE, '.claude', 'brain');
+  return join(brainDir, 'projects', getProjectId());
+}
+
+// CLI (only when run directly)
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--init')) {
+    initBrainId();
+  } else if (args.includes('--path')) {
+    console.log(getProjectBrainPath());
+  } else if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: bun src/project-id.js [options]
+
+Options:
+  (none)    Output current project ID
+  --init    Create .brain-id file if not exists
+  --path    Output full path to project brain directory
+  --help    Show this help`);
+  } else {
+    console.log(getProjectId());
+  }
+}
+
+// Export for use as module
+export { getProjectId, initBrainId, getProjectBrainPath, BRAIN_ID_FILE };

package/src/recall.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+/**
+ * Archive Search (Recall)
+ * Grep-based search through T3 archive
+ *
+ * Usage:
+ *   bun src/recall.js "search term"     # Search archive for term
+ *   bun src/recall.js "regex.*pattern"  # Regex search
+ *   bun src/recall.js "term" --context  # Show surrounding context
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getProjectId } from './project-id.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 searchArchive(query, options = {}) {
+  const results = [];
+  const regex = new RegExp(query, 'gi');
+
+  // Search archive files
+  if (existsSync(ARCHIVE_DIR)) {
+    const files = readdirSync(ARCHIVE_DIR).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+      const path = join(ARCHIVE_DIR, file);
+      const content = readFileSync(path, 'utf-8');
+      const lines = content.split('\n');
+
+      const matches = [];
+      for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) {
+          const match = {
+            line: i + 1,
+            text: lines[i].trim(),
+            context: []
+          };
+
+          if (options.context) {
+            // Add surrounding lines
+            const start = Math.max(0, i - 2);
+            const end = Math.min(lines.length - 1, i + 2);
+            for (let j = start; j <= end; j++) {
+              if (j !== i) {
+                match.context.push({ line: j + 1, text: lines[j].trim() });
+              }
+            }
+          }
+
+          matches.push(match);
+        }
+      }
+
+      if (matches.length > 0) {
+        // Extract date from filename (e.g., 2025-01-31.md)
+        const dateMatch = file.match(/(\d{4}-\d{2}-\d{2})/);
+        const date = dateMatch ? dateMatch[1] : 'unknown';
+
+        results.push({
+          file,
+          date,
+          path,
+          matches,
+          matchCount: matches.length
+        });
+      }
+    }
+  }
+
+  // Also search current context.md
+  const contextPath = join(CONTEXT_DIR, 'context.md');
+  if (existsSync(contextPath)) {
+    const content = readFileSync(contextPath, 'utf-8');
+    const lines = content.split('\n');
+
+    const matches = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (regex.test(lines[i])) {
+        matches.push({
+          line: i + 1,
+          text: lines[i].trim()
+        });
+      }
+    }
+
+    if (matches.length > 0) {
+      results.unshift({
+        file: 'context.md',
+        date: 'current',
+        path: contextPath,
+        matches,
+        matchCount: matches.length
+      });
+    }
+  }
+
+  // Sort by match count (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;
+    return b.date.localeCompare(a.date);
+  });
+
+  return results;
+}
+
+function formatResults(results, query) {
+  if (results.length === 0) {
+    console.log(`No results found for: "${query}"`);
+    console.log(`\nArchive location: ${ARCHIVE_DIR}`);
+    return;
+  }
+
+  console.log(`Found ${results.reduce((sum, r) => sum + r.matchCount, 0)} matches in ${results.length} files for: "${query}"\n`);
+
+  for (const result of results) {
+    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'
+      );
+      console.log(`  L${match.line}: ${highlighted}`);
+
+      if (match.context && match.context.length > 0) {
+        for (const ctx of match.context) {
+          console.log(`     ${ctx.line}: ${ctx.text}`);
+        }
+      }
+    }
+    console.log('');
+  }
+}
+
+// CLI
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: bun src/recall.js <query> [options]
+
+Search the brain archive for past context and decisions.
+
+Arguments:
+  query            Search term or regex pattern
+
+Options:
+  --context        Show surrounding lines for each match
+  --json           Output results as JSON
+  --help           Show this help
+
+Examples:
+  bun src/recall.js "authentication"
+  bun src/recall.js "why.*choose" --context
+  bun src/recall.js "API" --json`);
+    process.exit(0);
+  }
+
+  const query = args.find(a => !a.startsWith('--'));
+  const showContext = args.includes('--context');
+  const jsonOutput = args.includes('--json');
+
+  if (!query) {
+    console.error('Error: search query required');
+    process.exit(1);
+  }
+
+  const results = searchArchive(query, { context: showContext });
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    formatResults(results, query);
+  }
+}
+
+// Export for use as module
+export { searchArchive, ARCHIVE_DIR };

package/src/saver-prompt.md

@@ -0,0 +1,81 @@
+# Brain Saver
+
+Save session context using the structured saver tool.
+
+## Memory Tiers
+
+```
+~/.claude/brain/
+│
+├── user.md                    ← T1: Who they are (40 lines max)
+├── preferences.md             ← T1: How they code (40 lines max)
+│
+└── projects/{id}/
+    ├── context.md             ← T2: Current state (120 lines max)
+    └── archive/               ← T3: History (unlimited)
+        └── {date}.md
+```
+
+## What to Save
+
+**T1 (rare)** - Only genuine new insights:
+- Communication style discoveries
+- Thinking patterns observed
+- Strong preferences revealed
+- Pet peeves encountered
+
+**T2 (common)** - Project state:
+- What the project is
+- Current focus/active work
+- Recent decisions + rationale
+- Key files and purposes
+- Blockers
+
+**T3 (optional)** - Significant sessions:
+- Major features implemented
+- Important decisions made
+- Problems solved
+
+## How to Save
+
+Build a JSON payload with only the tiers that have new information:
+
+```json
+{
+  "t1_user": {
+    "Section Name": ["item1", "item2"]
+  },
+  "t1_prefs": {
+    "Section Name": ["preference1"]
+  },
+  "t2": {
+    "what": "One-line description",
+    "focus": ["task1", "task2"],
+    "decisions": {
+      "Decision": "rationale"
+    },
+    "files": {
+      "path/file.js": "purpose"
+    }
+  },
+  "t3": "Summary of significant work."
+}
+```
+
+Preview with dry-run:
+```bash
+bun src/saver.js --dry-run --json '<payload>'
+```
+
+Apply changes:
+```bash
+bun src/saver.js --json '<payload>'
+```
+
+## Rules
+
+- REPLACE outdated info, don't append endlessly
+- Decisions need rationale (the "why")
+- Keep within size limits
+- Only save what helps future sessions
+- T1 updates should be rare and meaningful