nano-brain 2026.7.13 → 2026.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nano-brain",
-  "version": "2026.7.13",
+  "version": "2026.8.0",
   "description": "Persistent memory and code intelligence for AI coding agents. Local MCP server with self-learning hybrid search (BM25 + vector + knowledge graph + LLM reranking), automatic session ingestion, codebase indexing, and 22 tools. Learns your preferences over time. Works with OpenCode, Claude, Cursor, Windsurf, and any MCP client.",
   "type": "module",
   "bin": {

package/src/cli/commands/cache.ts

@@ -0,0 +1,74 @@
+import { createStore, resolveProjectLabel } from '../../store.js';
+import * as crypto from 'crypto';
+import { log, cliOutput, cliError } from '../../logger.js';
+import type { GlobalOptions } from '../types.js';
+
+export async function handleCache(globalOpts: GlobalOptions, commandArgs: string[]): Promise<void> {
+  const subcommand = commandArgs[0];
+
+  if (!subcommand) {
+    cliError('Missing cache subcommand (clear, stats)');
+    process.exit(1);
+  }
+
+  log('cli', 'cache subcommand=' + subcommand);
+  const store = await createStore(globalOpts.dbPath);
+
+  switch (subcommand) {
+    case 'clear': {
+      let all = false;
+      let type: string | undefined;
+
+      for (const arg of commandArgs.slice(1)) {
+        if (arg === '--all') {
+          all = true;
+        } else if (arg.startsWith('--type=')) {
+          type = arg.substring(7);
+        }
+      }
+
+      if (type) {
+        const typeMap: Record<string, string> = { embed: 'qembed', expand: 'expand', rerank: 'rerank' };
+        if (!typeMap[type]) {
+          cliError(`Invalid cache type "${type}". Valid types: embed, expand, rerank`);
+          store.close();
+          process.exit(1);
+        }
+        type = typeMap[type];
+      }
+
+      let deleted: number;
+      if (all) {
+        deleted = store.clearCache(undefined, type);
+        cliOutput(`Cleared all cache entries${type ? ` of type ${type}` : ''} (${deleted} total)`);
+      } else {
+        const projectHash = crypto.createHash('sha256').update(process.cwd()).digest('hex').substring(0, 12);
+        deleted = store.clearCache(projectHash, type);
+        cliOutput(`Cleared ${deleted} cache entries for workspace ${resolveProjectLabel(projectHash)}${type ? ` (type: ${type})` : ''}`);
+      }
+      break;
+    }
+
+    case 'stats': {
+      const stats = store.getCacheStats();
+      if (stats.length === 0) {
+        cliOutput('No cache entries');
+      } else {
+        cliOutput('Cache Statistics:');
+        cliOutput('  Type        Project                         Count');
+        cliOutput('  ──────────  ──────────────────────────────  ─────');
+        for (const row of stats) {
+          cliOutput(`  ${row.type.padEnd(10)}  ${resolveProjectLabel(row.projectHash).padEnd(30)}  ${row.count}`);
+        }
+      }
+      break;
+    }
+
+    default:
+      cliError(`Unknown cache subcommand: ${subcommand}`);
+      store.close();
+      process.exit(1);
+  }
+
+  store.close();
+}

package/src/cli/commands/categorize-backfill.ts

@@ -0,0 +1,116 @@
+import { createStore } from '../../store.js';
+import { loadCollectionConfig } from '../../collections.js';
+import { createLLMProvider } from '../../llm-provider.js';
+import type { ConsolidationConfig } from '../../types.js';
+import * as crypto from 'crypto';
+import { log, cliOutput, cliError } from '../../logger.js';
+import type { GlobalOptions } from '../types.js';
+
+export async function handleCategorizeBackfill(globalOpts: GlobalOptions, commandArgs: string[]): Promise<void> {
+  let batchSize = 50;
+  let rateLimit = 10;
+  let dryRun = false;
+  let workspace: string | undefined;
+
+  for (const arg of commandArgs) {
+    if (arg.startsWith('--batch-size=')) {
+      batchSize = parseInt(arg.substring(13), 10);
+    } else if (arg.startsWith('--rate-limit=')) {
+      rateLimit = parseInt(arg.substring(13), 10);
+    } else if (arg === '--dry-run') {
+      dryRun = true;
+    } else if (arg.startsWith('--workspace=')) {
+      workspace = arg.substring(12);
+    }
+  }
+
+  log('cli', 'categorize-backfill batch=' + batchSize + ' rate=' + rateLimit + ' dry=' + dryRun);
+
+  const config = loadCollectionConfig(globalOpts.configPath);
+  if (!config?.consolidation) {
+    cliError('No consolidation config found. Set consolidation section in config.yml');
+    process.exit(1);
+  }
+
+  const consolidationConfig = config.consolidation as ConsolidationConfig;
+  const llmProvider = createLLMProvider(consolidationConfig);
+  if (!llmProvider) {
+    cliError('No LLM provider configured. Set consolidation.apiKey in config.yml or CONSOLIDATION_API_KEY env var');
+    process.exit(1);
+  }
+
+  const categorizationConfig = {
+    llm_enabled: config?.categorization?.llm_enabled ?? true,
+    confidence_threshold: config?.categorization?.confidence_threshold ?? 0.6,
+    max_content_length: config?.categorization?.max_content_length ?? 2000,
+  };
+
+  const store = await createStore(globalOpts.dbPath);
+  const projectHash = workspace
+    ? crypto.createHash('sha256').update(workspace).digest('hex').substring(0, 12)
+    : undefined;
+
+  const uncategorized = store.getUncategorizedDocuments(batchSize, projectHash);
+  const total = uncategorized.length;
+
+  if (total === 0) {
+    cliOutput('No uncategorized documents found.');
+    store.close();
+    return;
+  }
+
+  cliOutput(`Found ${total} uncategorized document(s)${dryRun ? ' (dry run)' : ''}`);
+
+  const tagCounts = new Map<string, number>();
+  let processed = 0;
+  let categorized = 0;
+  const delayMs = Math.ceil(1000 / rateLimit);
+
+  for (const doc of uncategorized) {
+    processed++;
+    const truncatedContent = doc.body.slice(0, categorizationConfig.max_content_length);
+
+    if (dryRun) {
+      cliOutput(`[${processed}/${total}] Would categorize: ${doc.path}`);
+      continue;
+    }
+
+    try {
+      const { categorizeMemory } = await import('../../llm-categorizer.js');
+      const tags = await categorizeMemory(truncatedContent, llmProvider, categorizationConfig);
+
+      if (tags.length > 0) {
+        store.insertTags(doc.id, tags);
+        categorized++;
+        for (const tag of tags) {
+          tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+        }
+      }
+
+      const tagStr = tags.length > 0 ? tags.join(', ') : '(no tags)';
+      cliOutput(`[${processed}/${total}] ${doc.path}: ${tagStr}`);
+
+      if (processed < total) {
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+      }
+    } catch (err) {
+      cliError(`[${processed}/${total}] Error categorizing ${doc.path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  store.close();
+
+  cliOutput('');
+  if (dryRun) {
+    cliOutput(`Dry run complete. Would process ${total} document(s).`);
+  } else {
+    cliOutput(`Categorization complete: ${categorized}/${processed} documents tagged`);
+    if (tagCounts.size > 0) {
+      cliOutput('Tag distribution:');
+      const sorted = [...tagCounts.entries()].sort((a, b) => b[1] - a[1]);
+      for (const [tag, count] of sorted) {
+        cliOutput(`  ${tag}: ${count}`);
+      }
+    }
+  }
+}

package/src/cli/commands/code-impact.ts

@@ -0,0 +1,106 @@
+import { openDatabase } from '../../store.js';
+import { SymbolGraph } from '../../symbol-graph.js';
+import * as crypto from 'crypto';
+import Database from 'better-sqlite3';
+import { log, cliOutput, cliError } from '../../logger.js';
+import type { GlobalOptions } from '../types.js';
+import { resolveDbPath } from '../utils.js';
+
+function warnIfEmptySymbolGraph(db: Database.Database, projectHash: string): boolean {
+  const count = db.prepare('SELECT COUNT(*) as cnt FROM code_symbols WHERE project_hash = ?').get(projectHash) as { cnt: number };
+  if (count.cnt === 0) {
+    cliError('⚠️  Symbol graph is empty. Run `npx nano-brain reindex` first.');
+    return true;
+  }
+  return false;
+}
+
+export async function handleCodeImpact(globalOpts: GlobalOptions, commandArgs: string[]): Promise<void> {
+  let target: string | undefined;
+  let direction: 'upstream' | 'downstream' = 'upstream';
+  let maxDepth = 5;
+  let minConfidence = 0;
+  let filePath: string | undefined;
+  let format: 'text' | 'json' = 'text';
+
+  for (const arg of commandArgs) {
+    if (arg.startsWith('--direction=')) {
+      const val = arg.substring(12);
+      if (val === 'upstream' || val === 'downstream') direction = val;
+    } else if (arg.startsWith('--max-depth=')) {
+      maxDepth = parseInt(arg.substring(12), 10);
+    } else if (arg.startsWith('--min-confidence=')) {
+      minConfidence = parseFloat(arg.substring(17));
+    } else if (arg.startsWith('--file=')) {
+      filePath = arg.substring(7);
+    } else if (arg === '--json') {
+      format = 'json';
+    } else if (!arg.startsWith('-')) {
+      target = arg;
+    }
+  }
+
+  if (!target) {
+    cliError('Usage: code-impact <symbol-name> [--direction=upstream|downstream] [--max-depth=N] [--min-confidence=N] [--file=<path>] [--json]');
+    process.exit(1);
+  }
+
+  log('cli', 'code-impact target=' + target + ' direction=' + direction + ' depth=' + maxDepth);
+  const workspaceRoot = process.cwd();
+  const projectHash = crypto.createHash('sha256').update(workspaceRoot).digest('hex').substring(0, 12);
+  const resolvedDbPath = resolveDbPath(globalOpts.dbPath, workspaceRoot);
+  const db = openDatabase(resolvedDbPath);
+
+  if (warnIfEmptySymbolGraph(db, projectHash)) {
+    db.close();
+    return;
+  }
+
+  const graph = new SymbolGraph(db);
+  const result = graph.handleImpact({ target, direction, maxDepth, minConfidence, filePath, projectHash });
+
+  if (format === 'json') {
+    cliOutput(JSON.stringify(result, null, 2));
+    db.close();
+    return;
+  }
+
+  if (!result.found) {
+    if (result.disambiguation) {
+      cliOutput(`Multiple symbols named "${target}". Use --file= to disambiguate:`);
+      for (const s of result.disambiguation) {
+        cliOutput(`  ${s.kind} ${s.name} — ${s.filePath}`);
+      }
+    } else {
+      cliOutput(`Symbol "${target}" not found.`);
+    }
+    db.close();
+    return;
+  }
+
+  const t = result.target!;
+  cliOutput(`Impact Analysis: ${t.kind} ${t.name} (${t.filePath})`);
+  cliOutput(`  Direction: ${direction}`);
+  cliOutput(`  Risk: ${result.risk}`);
+  cliOutput(`  Direct deps: ${result.summary.directDeps}, Total affected: ${result.summary.totalAffected}, Flows: ${result.summary.flowsAffected}`);
+  cliOutput('');
+
+  for (const [depth, symbols] of Object.entries(result.byDepth)) {
+    if (symbols.length > 0) {
+      cliOutput(`Depth ${depth} (${symbols.length}):`);
+      for (const s of symbols) {
+        cliOutput(`  ${s.kind} ${s.name} (${s.filePath}) [${s.edgeType}, confidence=${s.confidence}]`);
+      }
+    }
+  }
+
+  if (result.affectedFlows.length > 0) {
+    cliOutput('');
+    cliOutput(`Affected Flows (${result.affectedFlows.length}):`);
+    for (const f of result.affectedFlows) {
+      cliOutput(`  ${f.flowType}: ${f.label}`);
+    }
+  }
+
+  db.close();
+}

package/src/cli/commands/collection.ts

@@ -0,0 +1,85 @@
+import { loadCollectionConfig, addCollection, removeCollection, renameCollection, listCollections } from '../../collections.js';
+import { cliOutput, cliError } from '../../logger.js';
+import type { GlobalOptions } from '../types.js';
+
+export async function handleCollection(globalOpts: GlobalOptions, commandArgs: string[]): Promise<void> {
+  const subcommand = commandArgs[0];
+
+  if (!subcommand) {
+    cliError('Missing collection subcommand (add, remove, list, rename)');
+    process.exit(1);
+  }
+
+  switch (subcommand) {
+    case 'add': {
+      const name = commandArgs[1];
+      const collectionPath = commandArgs[2];
+      let pattern = '**/*.md';
+
+      for (const arg of commandArgs.slice(3)) {
+        if (arg.startsWith('--pattern=')) {
+          pattern = arg.substring(10);
+        }
+      }
+
+      if (!name || !collectionPath) {
+        cliError('Usage: collection add <name> <path> [--pattern=<glob>]');
+        process.exit(1);
+      }
+
+      addCollection(globalOpts.configPath, name, collectionPath, pattern);
+      cliOutput(`✅ Added collection "${name}"`);
+      break;
+    }
+
+    case 'remove': {
+      const name = commandArgs[1];
+      if (!name) {
+        cliError('Usage: collection remove <name>');
+        process.exit(1);
+      }
+
+      removeCollection(globalOpts.configPath, name);
+      cliOutput(`✅ Removed collection "${name}"`);
+      break;
+    }
+
+    case 'list': {
+      const config = loadCollectionConfig(globalOpts.configPath);
+      if (!config) {
+        cliOutput('No collections configured');
+        return;
+      }
+
+      const names = listCollections(config);
+      if (names.length === 0) {
+        cliOutput('No collections configured');
+      } else {
+        cliOutput('Collections:');
+        for (const name of names) {
+          const coll = config.collections?.[name];
+          cliOutput(`  ${name}: ${coll?.path} (${coll?.pattern || '**/*.md'})`);
+        }
+      }
+      break;
+    }
+
+    case 'rename': {
+      const oldName = commandArgs[1];
+      const newName = commandArgs[2];
+
+      if (!oldName || !newName) {
+        cliError('Usage: collection rename <old> <new>');
+        process.exit(1);
+      }
+
+      renameCollection(globalOpts.configPath, oldName, newName);
+      cliOutput(`✅ Renamed collection "${oldName}" to "${newName}"`);
+      break;
+    }
+
+    default:
+      cliError(`Unknown collection subcommand: ${subcommand}`);
+      process.exit(1);
+  }
+}

package/src/cli/commands/consolidate.ts

@@ -0,0 +1,49 @@
+import { createStore } from '../../store.js';
+import { loadCollectionConfig } from '../../collections.js';
+import { createLLMProvider } from '../../llm-provider.js';
+import { ConsolidationAgent } from '../../consolidation.js';
+import type { ConsolidationConfig } from '../../types.js';
+import { log, cliOutput, cliError } from '../../logger.js';
+import type { GlobalOptions } from '../types.js';
+
+export async function handleConsolidate(globalOpts: GlobalOptions, commandArgs: string[]): Promise<void> {
+  log('cli', 'consolidate');
+  const store = await createStore(globalOpts.dbPath);
+  const config = loadCollectionConfig(globalOpts.configPath);
+
+  if (!config?.consolidation?.enabled) {
+    cliOutput('Consolidation is not enabled. Set consolidation.enabled=true in config.yml');
+    store.close();
+    return;
+  }
+
+  try {
+    const consolidationConfig = config.consolidation as ConsolidationConfig;
+    const provider = createLLMProvider(consolidationConfig);
+
+    if (!provider) {
+      cliOutput('No API key configured. Set consolidation.apiKey in config.yml or CONSOLIDATION_API_KEY env var');
+      return;
+    }
+
+    const agent = new ConsolidationAgent(store, {
+      llmProvider: provider,
+      maxMemoriesPerCycle: consolidationConfig.max_memories_per_cycle,
+      minMemoriesThreshold: consolidationConfig.min_memories_threshold,
+      confidenceThreshold: consolidationConfig.confidence_threshold,
+    });
+
+    const results = await agent.runConsolidationCycle();
+
+    if (results.length === 0) {
+      cliOutput('No memories to consolidate');
+    } else {
+      cliOutput(`Consolidation complete: ${results.length} consolidation(s) created`);
+    }
+  } catch (err) {
+    cliError('Consolidation failed:', err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  } finally {
+    store.close();
+  }
+}

package/src/cli/commands/context.ts

@@ -0,0 +1,112 @@
+import { openDatabase } from '../../store.js';
+import { SymbolGraph } from '../../symbol-graph.js';
+import * as crypto from 'crypto';
+import Database from 'better-sqlite3';
+import { log, cliOutput, cliError } from '../../logger.js';
+import type { GlobalOptions } from '../types.js';
+import { resolveDbPath } from '../utils.js';
+
+function warnIfEmptySymbolGraph(db: Database.Database, projectHash: string): boolean {
+  const count = db.prepare('SELECT COUNT(*) as cnt FROM code_symbols WHERE project_hash = ?').get(projectHash) as { cnt: number };
+  if (count.cnt === 0) {
+    cliError('⚠️  Symbol graph is empty. Run `npx nano-brain reindex` first.');
+    return true;
+  }
+  return false;
+}
+
+export async function handleContext(globalOpts: GlobalOptions, commandArgs: string[]): Promise<void> {
+  let name: string | undefined;
+  let filePath: string | undefined;
+  let format: 'text' | 'json' = 'text';
+
+  for (const arg of commandArgs) {
+    if (arg.startsWith('--file=')) {
+      filePath = arg.substring(7);
+    } else if (arg === '--json') {
+      format = 'json';
+    } else if (!arg.startsWith('-')) {
+      name = arg;
+    }
+  }
+
+  if (!name) {
+    cliError('Usage: context <symbol-name> [--file=<path>] [--json]');
+    process.exit(1);
+  }
+
+  log('cli', 'context name=' + name + ' file=' + (filePath || ''));
+  const workspaceRoot = process.cwd();
+  const projectHash = crypto.createHash('sha256').update(workspaceRoot).digest('hex').substring(0, 12);
+  const resolvedDbPath = resolveDbPath(globalOpts.dbPath, workspaceRoot);
+  const db = openDatabase(resolvedDbPath);
+
+  if (warnIfEmptySymbolGraph(db, projectHash)) {
+    db.close();
+    return;
+  }
+
+  const graph = new SymbolGraph(db);
+  const result = graph.handleContext({ name, filePath, projectHash });
+
+  if (format === 'json') {
+    cliOutput(JSON.stringify(result, null, 2));
+    db.close();
+    return;
+  }
+
+  if (!result.found) {
+    if (result.disambiguation) {
+      cliOutput(`Multiple symbols named "${name}". Use --file= to disambiguate:`);
+      for (const s of result.disambiguation) {
+        cliOutput(`  ${s.kind} ${s.name} — ${s.filePath}:${s.startLine}`);
+      }
+    } else {
+      cliOutput(`Symbol "${name}" not found.`);
+    }
+    db.close();
+    return;
+  }
+
+  const sym = result.symbol!;
+  cliOutput(`${sym.kind} ${sym.name}`);
+  cliOutput(`  File: ${sym.filePath}:${sym.startLine}-${sym.endLine}`);
+  cliOutput(`  Exported: ${sym.exported ? 'yes' : 'no'}`);
+  if (result.clusterLabel) {
+    cliOutput(`  Cluster: ${result.clusterLabel}`);
+  }
+  cliOutput('');
+
+  if (result.incoming && result.incoming.length > 0) {
+    cliOutput(`Callers (${result.incoming.length}):`);
+    for (const e of result.incoming) {
+      cliOutput(`  ← ${e.kind} ${e.name} (${e.filePath}) [${e.edgeType}]`);
+    }
+    cliOutput('');
+  }
+
+  if (result.outgoing && result.outgoing.length > 0) {
+    cliOutput(`Callees (${result.outgoing.length}):`);
+    for (const e of result.outgoing) {
+      cliOutput(`  → ${e.kind} ${e.name} (${e.filePath}) [${e.edgeType}]`);
+    }
+    cliOutput('');
+  }
+
+  if (result.flows && result.flows.length > 0) {
+    cliOutput(`Flows (${result.flows.length}):`);
+    for (const f of result.flows) {
+      cliOutput(`  ${f.flowType}: ${f.label} (step ${f.stepIndex})`);
+    }
+    cliOutput('');
+  }
+
+  if (result.infrastructureSymbols && result.infrastructureSymbols.length > 0) {
+    cliOutput(`Infrastructure:`);
+    for (const s of result.infrastructureSymbols) {
+      cliOutput(`  [${s.operation}] ${s.type}: ${s.pattern}`);
+    }
+  }
+
+  db.close();
+}

package/src/cli/commands/detect-changes.ts

@@ -0,0 +1,82 @@
+import { openDatabase } from '../../store.js';
+import { SymbolGraph } from '../../symbol-graph.js';
+import * as crypto from 'crypto';
+import Database from 'better-sqlite3';
+import { log, cliOutput, cliError } from '../../logger.js';
+import type { GlobalOptions } from '../types.js';
+import { resolveDbPath } from '../utils.js';
+
+function warnIfEmptySymbolGraph(db: Database.Database, projectHash: string): boolean {
+  const count = db.prepare('SELECT COUNT(*) as cnt FROM code_symbols WHERE project_hash = ?').get(projectHash) as { cnt: number };
+  if (count.cnt === 0) {
+    cliError('⚠️  Symbol graph is empty. Run `npx nano-brain reindex` first.');
+    return true;
+  }
+  return false;
+}
+
+export async function handleDetectChanges(globalOpts: GlobalOptions, commandArgs: string[]): Promise<void> {
+  let scope: 'unstaged' | 'staged' | 'all' = 'all';
+  let format: 'text' | 'json' = 'text';
+
+  for (const arg of commandArgs) {
+    if (arg.startsWith('--scope=')) {
+      const val = arg.substring(8);
+      if (val === 'unstaged' || val === 'staged' || val === 'all') scope = val;
+    } else if (arg === '--json') {
+      format = 'json';
+    }
+  }
+
+  log('cli', 'detect-changes scope=' + scope);
+  const workspaceRoot = process.cwd();
+  const projectHash = crypto.createHash('sha256').update(workspaceRoot).digest('hex').substring(0, 12);
+  const resolvedDbPath = resolveDbPath(globalOpts.dbPath, workspaceRoot);
+  const db = openDatabase(resolvedDbPath);
+
+  if (warnIfEmptySymbolGraph(db, projectHash)) {
+    db.close();
+    return;
+  }
+
+  const graph = new SymbolGraph(db);
+  const result = graph.handleDetectChanges({ scope, workspaceRoot, projectHash });
+
+  if (format === 'json') {
+    cliOutput(JSON.stringify(result, null, 2));
+    db.close();
+    return;
+  }
+
+  if (result.changedFiles.length === 0) {
+    cliOutput('No changed files detected.');
+    db.close();
+    return;
+  }
+
+  cliOutput(`Risk Level: ${result.riskLevel}`);
+  cliOutput('');
+
+  cliOutput(`Changed Files (${result.changedFiles.length}):`);
+  for (const f of result.changedFiles) {
+    cliOutput(`  ${f}`);
+  }
+  cliOutput('');
+
+  if (result.changedSymbols.length > 0) {
+    cliOutput(`Changed Symbols (${result.changedSymbols.length}):`);
+    for (const s of result.changedSymbols) {
+      cliOutput(`  ${s.kind} ${s.name} (${s.filePath})`);
+    }
+    cliOutput('');
+  }
+
+  if (result.affectedFlows.length > 0) {
+    cliOutput(`Affected Flows (${result.affectedFlows.length}):`);
+    for (const f of result.affectedFlows) {
+      cliOutput(`  ${f.flowType}: ${f.label}`);
+    }
+  }
+
+  db.close();
+}