nano-brain 2026.6.7 → 2026.6.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nano-brain",
-  "version": "2026.6.7",
+  "version": "2026.6.9",
   "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/bench.ts

@@ -2,6 +2,8 @@ import { createStore, computeHash, indexDocument } from './store.js';
 import { loadCollectionConfig } from './collections.js';
 import { createEmbeddingProvider, checkOllamaHealth, detectOllamaUrl } from './embeddings.js';
 import { hybridSearch } from './search.js';
+import { traverse, getRelatedDocuments } from './connection-graph.js';
+import { ConsolidationAgent } from './consolidation.js';
 import type { GlobalOptions } from './index.js';
 import type { Store } from './types.js';
 import * as fs from 'fs';
@@ -37,6 +39,11 @@ const DEFAULT_ITERATIONS: Record<string, number> = {
   embed: 5,
   cache: 20,
   store: 20,
+  connections: 10,
+  quality: 1,
+  scale: 1,
+  consolidation: 10,
+  memory: 1,
 };
 
 async function runBenchmark(
@@ -234,6 +241,672 @@ async function runStoreSuite(iterations: number, dbPath: string): Promise<BenchR
   return results;
 }
 
+async function runConnectionsSuite(iterations: number): Promise<BenchResult[]> {
+  const results: BenchResult[] = [];
+  const tempDbPath = path.join(os.tmpdir(), `nano-brain-bench-conn-${Date.now()}.sqlite`);
+  const store = await createStore(tempDbPath);
+
+  for (let i = 0; i < 100; i++) {
+    const content = `# Doc ${i}\n\nContent for document ${i} in connections benchmark.`;
+    const hash = computeHash(content);
+    store.insertContent(hash, content);
+    store.insertDocument({
+      collection: 'bench',
+      path: `/bench/conn-doc-${i}.md`,
+      title: `Connection Doc ${i}`,
+      hash,
+      createdAt: new Date().toISOString(),
+      modifiedAt: new Date().toISOString(),
+      active: true,
+      projectHash: 'bench',
+    });
+  }
+
+  results.push(
+    await runBenchmark('insertConnection (single)', () => {
+      store.insertConnection({
+      fromDocId: 1,
+      toDocId: 2,
+      relationshipType: 'related',
+      description: null,
+      strength: 0.8,
+      createdBy: 'user',
+      projectHash: 'bench',
+    });
+    }, iterations)
+  );
+
+  let batchCounter = 0;
+  results.push(
+    await runBenchmark('insertConnection (batch 100)', () => {
+      for (let i = 0; i < 100; i++) {
+        store.insertConnection({
+          fromDocId: (batchCounter * 100 + i) % 100 + 1,
+          toDocId: (batchCounter * 100 + i + 1) % 100 + 1,
+          relationshipType: 'related',
+          description: null,
+          strength: 0.7,
+          createdBy: 'user',
+          projectHash: 'bench',
+        });
+      }
+      batchCounter++;
+    }, iterations)
+  );
+
+  const doc0Conns = store.getConnectionsForDocument(100);
+  results.push(
+    await runBenchmark('getConnections (0 conns)', () => {
+      store.getConnectionsForDocument(100);
+    }, iterations)
+  );
+
+  for (let i = 0; i < 10; i++) {
+    store.insertConnection({
+      fromDocId: 50,
+      toDocId: 60 + i,
+      relationshipType: 'supports',
+      description: null,
+      strength: 0.9,
+      createdBy: 'user',
+      projectHash: 'bench',
+    });
+  }
+  results.push(
+    await runBenchmark('getConnections (10 conns)', () => {
+      store.getConnectionsForDocument(50);
+    }, iterations)
+  );
+
+  for (let i = 0; i < 40; i++) {
+    store.insertConnection({
+      fromDocId: 30,
+      toDocId: (i % 99) + 1,
+      relationshipType: 'extends',
+      description: null,
+      strength: 0.85,
+      createdBy: 'user',
+      projectHash: 'bench',
+    });
+  }
+  results.push(
+    await runBenchmark('getConnections (50 conns)', () => {
+      store.getConnectionsForDocument(30);
+    }, iterations)
+  );
+
+  results.push(
+    await runBenchmark('traverse depth=1', () => {
+      traverse(store, 1, { maxDepth: 1 });
+    }, iterations)
+  );
+
+  results.push(
+    await runBenchmark('traverse depth=2', () => {
+      traverse(store, 1, { maxDepth: 2 });
+    }, iterations)
+  );
+
+  results.push(
+    await runBenchmark('traverse depth=3', () => {
+      traverse(store, 1, { maxDepth: 3 });
+    }, iterations)
+  );
+
+  results.push(
+    await runBenchmark('getConnectionCount', () => {
+      store.getConnectionCount(1);
+    }, iterations)
+  );
+
+  const connToDelete = store.insertConnection({
+    fromDocId: 99,
+    toDocId: 98,
+    relationshipType: 'related',
+    description: null,
+    strength: 0.5,
+    createdBy: 'user',
+    projectHash: 'bench',
+  });
+  let deleteId = connToDelete;
+  results.push(
+    await runBenchmark('deleteConnection', () => {
+      store.deleteConnection(deleteId);
+      deleteId = store.insertConnection({
+        fromDocId: 99,
+        toDocId: 98,
+        relationshipType: 'related',
+        description: null,
+        strength: 0.5,
+        createdBy: 'user',
+        projectHash: 'bench',
+      });
+    }, iterations)
+  );
+
+  store.close();
+  try {
+    fs.unlinkSync(tempDbPath);
+    fs.unlinkSync(tempDbPath + '-wal');
+    fs.unlinkSync(tempDbPath + '-shm');
+  } catch {
+  }
+
+  return results;
+}
+
+async function runQualitySuite(
+  store: Store,
+  embedder: { embed(text: string): Promise<{ embedding: number[] }> } | null,
+  iterations: number
+): Promise<BenchResult[]> {
+  const results: BenchResult[] = [];
+  const tempDbPath = path.join(os.tmpdir(), `nano-brain-bench-quality-${Date.now()}.sqlite`);
+  const tempStore = await createStore(tempDbPath);
+
+  const topics = [
+    { name: 'authentication', keywords: ['JWT', 'token', 'login', 'session', 'OAuth', 'password', 'auth middleware', 'bearer', 'refresh token', 'credentials'] },
+    { name: 'database-optimization', keywords: ['index', 'query plan', 'slow query', 'N+1', 'connection pool', 'transaction', 'deadlock', 'vacuum', 'explain analyze', 'cache hit'] },
+    { name: 'error-handling', keywords: ['try catch', 'exception', 'error boundary', 'stack trace', 'retry logic', 'circuit breaker', 'fallback', 'graceful degradation', 'error code', 'validation'] },
+    { name: 'deployment', keywords: ['Docker', 'Kubernetes', 'CI/CD', 'rolling update', 'blue-green', 'canary', 'helm chart', 'container', 'orchestration', 'scaling'] },
+    { name: 'testing', keywords: ['unit test', 'integration test', 'mock', 'stub', 'fixture', 'coverage', 'assertion', 'test runner', 'snapshot', 'e2e'] },
+  ];
+
+  const docIndices: Record<string, number[]> = {};
+  let docId = 0;
+  for (const topic of topics) {
+    docIndices[topic.name] = [];
+    for (let i = 0; i < 10; i++) {
+      const content = `# ${topic.name} Document ${i}\n\n${topic.keywords.slice(0, 5 + i % 5).join(', ')}.\n\nThis document covers ${topic.name} concepts including ${topic.keywords[i % topic.keywords.length]}.`;
+      const hash = computeHash(content + docId);
+      tempStore.insertContent(hash, content);
+      tempStore.insertDocument({
+        collection: 'bench',
+        path: `/bench/${topic.name}-${i}.md`,
+        title: `${topic.name} ${i}`,
+        hash,
+        createdAt: new Date().toISOString(),
+        modifiedAt: new Date().toISOString(),
+        active: true,
+        projectHash: 'bench',
+      });
+      docIndices[topic.name].push(docId);
+      docId++;
+    }
+  }
+
+  const queries = [
+    { query: 'JWT token authentication middleware', relevant: docIndices['authentication'] },
+    { query: 'database query optimization index', relevant: docIndices['database-optimization'] },
+    { query: 'error handling try catch exception', relevant: docIndices['error-handling'] },
+    { query: 'Docker Kubernetes deployment', relevant: docIndices['deployment'] },
+    { query: 'unit test mock coverage', relevant: docIndices['testing'] },
+    { query: 'OAuth login session credentials', relevant: docIndices['authentication'] },
+    { query: 'slow query N+1 connection pool', relevant: docIndices['database-optimization'] },
+    { query: 'circuit breaker retry fallback', relevant: docIndices['error-handling'] },
+    { query: 'CI/CD rolling update canary', relevant: docIndices['deployment'] },
+    { query: 'integration test fixture assertion', relevant: docIndices['testing'] },
+  ];
+
+  let ftsPrecision = 0, ftsRecall = 0, ftsMrr = 0;
+  for (const q of queries) {
+    const ftsResults = tempStore.searchFTS(q.query, { limit: 10 });
+    const topIds = ftsResults.map(r => Number(r.id));
+    const relevantSet = new Set(q.relevant);
+
+    const top5Relevant = topIds.slice(0, 5).filter((id: number) => relevantSet.has(id)).length;
+    ftsPrecision += top5Relevant / 5;
+
+    const top10Relevant = topIds.filter((id: number) => relevantSet.has(id)).length;
+    ftsRecall += top10Relevant / q.relevant.length;
+
+    const firstRelevantRank = topIds.findIndex((id: number) => relevantSet.has(id));
+    ftsMrr += firstRelevantRank >= 0 ? 1 / (firstRelevantRank + 1) : 0;
+  }
+
+  results.push({
+    name: 'P@5 (FTS)',
+    iterations: 1,
+    meanMs: ftsPrecision / queries.length,
+    minMs: 0,
+    maxMs: 0,
+    opsPerSec: 0,
+  });
+
+  results.push({
+    name: 'Recall@10 (FTS)',
+    iterations: 1,
+    meanMs: ftsRecall / queries.length,
+    minMs: 0,
+    maxMs: 0,
+    opsPerSec: 0,
+  });
+
+  results.push({
+    name: 'MRR (FTS)',
+    iterations: 1,
+    meanMs: ftsMrr / queries.length,
+    minMs: 0,
+    maxMs: 0,
+    opsPerSec: 0,
+  });
+
+  if (embedder) {
+    let hybridPrecision = 0, hybridRecall = 0, hybridMrr = 0;
+    for (const q of queries) {
+      const hybridResults = await hybridSearch(tempStore, { query: q.query, limit: 10 }, { embedder });
+      const topIds = hybridResults.map((r: any) => Number(r.id));
+      const relevantSet = new Set(q.relevant);
+
+      const top5Relevant = topIds.slice(0, 5).filter((id: number) => relevantSet.has(id)).length;
+      hybridPrecision += top5Relevant / 5;
+
+      const top10Relevant = topIds.filter((id: number) => relevantSet.has(id)).length;
+      hybridRecall += top10Relevant / q.relevant.length;
+
+      const firstRelevantRank = topIds.findIndex((id: number) => relevantSet.has(id));
+      hybridMrr += firstRelevantRank >= 0 ? 1 / (firstRelevantRank + 1) : 0;
+    }
+
+    results.push({
+      name: 'P@5 (Hybrid)',
+      iterations: 1,
+      meanMs: hybridPrecision / queries.length,
+      minMs: 0,
+      maxMs: 0,
+      opsPerSec: 0,
+    });
+
+    results.push({
+      name: 'Recall@10 (Hybrid)',
+      iterations: 1,
+      meanMs: hybridRecall / queries.length,
+      minMs: 0,
+      maxMs: 0,
+      opsPerSec: 0,
+    });
+
+    results.push({
+      name: 'MRR (Hybrid)',
+      iterations: 1,
+      meanMs: hybridMrr / queries.length,
+      minMs: 0,
+      maxMs: 0,
+      opsPerSec: 0,
+    });
+  }
+
+  tempStore.close();
+  try {
+    fs.unlinkSync(tempDbPath);
+    fs.unlinkSync(tempDbPath + '-wal');
+    fs.unlinkSync(tempDbPath + '-shm');
+  } catch {
+  }
+
+  return results;
+}
+
+async function runScaleSuite(iterations: number): Promise<BenchResult[]> {
+  const results: BenchResult[] = [];
+  const scalePoints = [100, 500, 1000, 5000];
+
+  for (const n of scalePoints) {
+    const tempDbPath = path.join(os.tmpdir(), `nano-brain-bench-scale-${n}-${Date.now()}.sqlite`);
+    const store = await createStore(tempDbPath);
+
+    const insertStart = performance.now();
+    for (let i = 0; i < n; i++) {
+      const content = `# Scale Doc ${i}\n\nContent for scale testing at ${n} documents. Keywords: test benchmark performance scale.`;
+      const hash = computeHash(content + i + n);
+      store.insertContent(hash, content);
+      store.insertDocument({
+        collection: 'bench',
+        path: `/bench/scale-${n}-${i}.md`,
+        title: `Scale Doc ${i}`,
+        hash,
+        createdAt: new Date().toISOString(),
+        modifiedAt: new Date().toISOString(),
+        active: true,
+        projectHash: 'bench',
+      });
+    }
+    const insertEnd = performance.now();
+    const insertMs = insertEnd - insertStart;
+
+    results.push({
+      name: `insert @${n}`,
+      iterations: 1,
+      meanMs: insertMs,
+      minMs: insertMs,
+      maxMs: insertMs,
+      opsPerSec: n / (insertMs / 1000),
+    });
+
+    const searchTimes: number[] = [];
+    for (let i = 0; i < 5; i++) {
+      const start = performance.now();
+      store.searchFTS('benchmark performance', { limit: 10 });
+      searchTimes.push(performance.now() - start);
+    }
+    const avgSearchMs = searchTimes.reduce((a, b) => a + b, 0) / searchTimes.length;
+
+    results.push({
+      name: `FTS search @${n}`,
+      iterations: 5,
+      meanMs: avgSearchMs,
+      minMs: Math.min(...searchTimes),
+      maxMs: Math.max(...searchTimes),
+      opsPerSec: 1000 / avgSearchMs,
+    });
+
+    const healthTimes: number[] = [];
+    for (let i = 0; i < 5; i++) {
+      const start = performance.now();
+      store.getIndexHealth();
+      healthTimes.push(performance.now() - start);
+    }
+    const avgHealthMs = healthTimes.reduce((a, b) => a + b, 0) / healthTimes.length;
+
+    results.push({
+      name: `indexHealth @${n}`,
+      iterations: 5,
+      meanMs: avgHealthMs,
+      minMs: Math.min(...healthTimes),
+      maxMs: Math.max(...healthTimes),
+      opsPerSec: 1000 / avgHealthMs,
+    });
+
+    const rss = process.memoryUsage().rss / (1024 * 1024);
+    results.push({
+      name: `RSS @${n}`,
+      iterations: 1,
+      meanMs: rss,
+      minMs: rss,
+      maxMs: rss,
+      opsPerSec: 0,
+    });
+
+    store.close();
+    try {
+      fs.unlinkSync(tempDbPath);
+      fs.unlinkSync(tempDbPath + '-wal');
+      fs.unlinkSync(tempDbPath + '-shm');
+    } catch {
+    }
+  }
+
+  return results;
+}
+
+async function runConsolidationSuite(iterations: number): Promise<BenchResult[]> {
+  const results: BenchResult[] = [];
+  const tempDbPath = path.join(os.tmpdir(), `nano-brain-bench-consol-${Date.now()}.sqlite`);
+  const store = await createStore(tempDbPath);
+
+  for (let i = 0; i < 50; i++) {
+    const content = `# Memory ${i}\n\nThis is a memory document for consolidation benchmarking. Topic: ${i % 5 === 0 ? 'authentication' : i % 5 === 1 ? 'database' : i % 5 === 2 ? 'errors' : i % 5 === 3 ? 'deployment' : 'testing'}.`;
+    const hash = computeHash(content + i);
+    store.insertContent(hash, content);
+    store.insertDocument({
+      collection: 'memory',
+      path: `/memory/consol-${i}.md`,
+      title: `Memory ${i}`,
+      hash,
+      createdAt: new Date().toISOString(),
+      modifiedAt: new Date().toISOString(),
+      active: true,
+      projectHash: 'bench',
+    });
+  }
+
+  const mockLlmResponse = JSON.stringify([{
+    sourceIds: [1, 2, 3],
+    summary: 'test summary',
+    insight: 'test insight',
+    connections: [{ fromId: 1, toId: 2, relationship: 'supports', confidence: 0.9 }],
+    overallConfidence: 0.85,
+  }]);
+
+  const mockLlmProvider = {
+    complete: async (_prompt: string) => ({ text: mockLlmResponse, tokensUsed: 100 }),
+    model: 'mock',
+  };
+
+  const agent = new ConsolidationAgent(store, { llmProvider: mockLlmProvider });
+
+  const db = store.getDb();
+
+  results.push(
+    await runBenchmark('getUnconsolidatedMemories', () => {
+      db.prepare(`
+        SELECT d.id, d.title, d.path, d.hash, c.body 
+        FROM documents d 
+        JOIN content c ON d.hash = c.hash 
+        WHERE d.collection = 'memory' 
+          AND d.active = 1 
+          AND d.superseded_by IS NULL 
+        ORDER BY d.modified_at DESC 
+        LIMIT 20
+      `).all();
+    }, iterations)
+  );
+
+  const sampleMemories = [
+    { id: 1, title: 'Memory 1', path: '/memory/1.md', hash: 'h1', body: 'Sample body content for memory 1' },
+    { id: 2, title: 'Memory 2', path: '/memory/2.md', hash: 'h2', body: 'Sample body content for memory 2' },
+    { id: 3, title: 'Memory 3', path: '/memory/3.md', hash: 'h3', body: 'Sample body content for memory 3' },
+  ];
+
+  results.push(
+    await runBenchmark('buildConsolidationPrompt', () => {
+      const prompt = `You are a memory consolidation agent. Analyze the following memories and find connections between them.
+
+For each group of related memories, output a JSON object with:
+- sourceIds: array of memory IDs that are related
+- summary: a concise summary of the related memories
+- insight: a new insight derived from connecting these memories
+- connections: array of {fromId, toId, relationship, confidence} objects
+- overallConfidence: 0.0-1.0 rating of how confident you are in this consolidation
+
+Output a JSON array of consolidation objects. Only include consolidations with confidence >= 0.7.
+
+Memories:
+${sampleMemories.map(m => `[ID: ${m.id}] ${m.title}\n${m.body.substring(0, 500)}`).join('\n\n---\n\n')}
+
+Respond with ONLY a JSON array, no other text.`;
+    }, iterations)
+  );
+
+  results.push(
+    await runBenchmark('parseConsolidationResponse', () => {
+      const text = mockLlmResponse;
+      const jsonMatch = text.match(/\[[\s\S]*\]/);
+      if (jsonMatch) {
+        JSON.parse(jsonMatch[0]);
+      }
+    }, iterations)
+  );
+
+  results.push(
+    await runBenchmark('applyConsolidation', () => {
+      const result = {
+        sourceIds: [1, 2, 3],
+        summary: 'test summary',
+        insight: 'test insight',
+        connections: [] as Array<{ fromId: number; toId: number; relationship: string; confidence: number }>,
+        overallConfidence: 0.85,
+      };
+      db.prepare(`
+        INSERT INTO consolidations (source_ids, summary, insight, connections, confidence, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(
+        JSON.stringify(result.sourceIds),
+        result.summary,
+        result.insight,
+        JSON.stringify(result.connections),
+        result.overallConfidence,
+        new Date().toISOString()
+      );
+    }, iterations)
+  );
+
+  store.close();
+  try {
+    fs.unlinkSync(tempDbPath);
+    fs.unlinkSync(tempDbPath + '-wal');
+    fs.unlinkSync(tempDbPath + '-shm');
+  } catch {
+  }
+
+  return results;
+}
+
+async function runMemorySuite(iterations: number): Promise<BenchResult[]> {
+  const results: BenchResult[] = [];
+
+  const baselineRss = process.memoryUsage().rss / (1024 * 1024);
+  results.push({
+    name: 'baseline RSS',
+    iterations: 1,
+    meanMs: baselineRss,
+    minMs: baselineRss,
+    maxMs: baselineRss,
+    opsPerSec: 0,
+  });
+
+  const tempDbPath = path.join(os.tmpdir(), `nano-brain-bench-mem-${Date.now()}.sqlite`);
+  const store = await createStore(tempDbPath);
+
+  const insertDocs = async (count: number) => {
+    for (let i = 0; i < count; i++) {
+      const content = `# Memory Doc ${i}\n\nContent for memory benchmarking document ${i}. This is filler text to simulate real document sizes.`;
+      const hash = computeHash(content + Date.now() + i);
+      store.insertContent(hash, content);
+      store.insertDocument({
+        collection: 'bench',
+        path: `/bench/mem-${Date.now()}-${i}.md`,
+        title: `Memory Doc ${i}`,
+        hash,
+        createdAt: new Date().toISOString(),
+        modifiedAt: new Date().toISOString(),
+        active: true,
+        projectHash: 'bench',
+      });
+    }
+  };
+
+  await insertDocs(100);
+  const rss100 = process.memoryUsage().rss / (1024 * 1024);
+  results.push({
+    name: 'RSS after 100 docs',
+    iterations: 1,
+    meanMs: rss100,
+    minMs: rss100,
+    maxMs: rss100,
+    opsPerSec: 0,
+  });
+
+  await insertDocs(400);
+  const rss500 = process.memoryUsage().rss / (1024 * 1024);
+  results.push({
+    name: 'RSS after 500 docs',
+    iterations: 1,
+    meanMs: rss500,
+    minMs: rss500,
+    maxMs: rss500,
+    opsPerSec: 0,
+  });
+
+  await insertDocs(500);
+  const rss1000 = process.memoryUsage().rss / (1024 * 1024);
+  results.push({
+    name: 'RSS after 1000 docs',
+    iterations: 1,
+    meanMs: rss1000,
+    minMs: rss1000,
+    maxMs: rss1000,
+    opsPerSec: 0,
+  });
+
+  for (let i = 0; i < 100; i++) {
+    store.insertConnection({
+      fromDocId: (i % 100) + 1,
+      toDocId: ((i + 1) % 100) + 1,
+      relationshipType: 'related',
+      description: null,
+      strength: 0.8,
+      createdBy: 'user',
+      projectHash: 'bench',
+    });
+  }
+  const rss100Conns = process.memoryUsage().rss / (1024 * 1024);
+  results.push({
+    name: 'RSS after 100 conns',
+    iterations: 1,
+    meanMs: rss100Conns,
+    minMs: rss100Conns,
+    maxMs: rss100Conns,
+    opsPerSec: 0,
+  });
+
+  for (let i = 0; i < 400; i++) {
+    store.insertConnection({
+      fromDocId: (i % 100) + 1,
+      toDocId: ((i + 50) % 100) + 1,
+      relationshipType: 'supports',
+      description: null,
+      strength: 0.7,
+      createdBy: 'user',
+      projectHash: 'bench',
+    });
+  }
+  const rss500Conns = process.memoryUsage().rss / (1024 * 1024);
+  results.push({
+    name: 'RSS after 500 conns',
+    iterations: 1,
+    meanMs: rss500Conns,
+    minMs: rss500Conns,
+    maxMs: rss500Conns,
+    opsPerSec: 0,
+  });
+
+  const searchPromises = [];
+  for (let i = 0; i < 10; i++) {
+    searchPromises.push(Promise.resolve(store.searchFTS('memory benchmarking', { limit: 10 })));
+  }
+  await Promise.all(searchPromises);
+  const peakRss = process.memoryUsage().rss / (1024 * 1024);
+  results.push({
+    name: 'peak RSS',
+    iterations: 1,
+    meanMs: peakRss,
+    minMs: peakRss,
+    maxMs: peakRss,
+    opsPerSec: 0,
+  });
+
+  const heapGrowth = ((rss1000 - rss100) / 900) * 1024;
+  results.push({
+    name: 'heap growth rate (KB/doc)',
+    iterations: 1,
+    meanMs: heapGrowth,
+    minMs: heapGrowth,
+    maxMs: heapGrowth,
+    opsPerSec: 0,
+  });
+
+  store.close();
+  try {
+    fs.unlinkSync(tempDbPath);
+    fs.unlinkSync(tempDbPath + '-wal');
+    fs.unlinkSync(tempDbPath + '-shm');
+  } catch {
+  }
+
+  return results;
+}
+
 function formatHumanReadable(suiteResults: SuiteResults): string {
   const lines: string[] = [];
   lines.push('nano-brain Benchmark Results');
@@ -382,7 +1055,7 @@ export async function handleBench(globalOpts: GlobalOptions, commandArgs: string
 
   const suitesToRun = options.suite
     ? [options.suite]
-    : ['search', 'embed', 'cache', 'store'];
+    : ['search', 'embed', 'cache', 'store', 'connections', 'quality', 'scale', 'consolidation', 'memory'];
 
   for (const suite of suitesToRun) {
     const iterations = options.iterations || DEFAULT_ITERATIONS[suite] || 10;
@@ -408,6 +1081,26 @@ export async function handleBench(globalOpts: GlobalOptions, commandArgs: string
         suiteResults.store = await runStoreSuite(iterations, globalOpts.dbPath);
         break;
 
+      case 'connections':
+        suiteResults.connections = await runConnectionsSuite(iterations);
+        break;
+
+      case 'quality':
+        suiteResults.quality = await runQualitySuite(store, embedder, iterations);
+        break;
+
+      case 'scale':
+        suiteResults.scale = await runScaleSuite(iterations);
+        break;
+
+      case 'consolidation':
+        suiteResults.consolidation = await runConsolidationSuite(iterations);
+        break;
+
+      case 'memory':
+        suiteResults.memory = await runMemorySuite(iterations);
+        break;
+
       default:
         console.error(`Unknown suite: ${suite}`);
     }

package/src/connection-graph.ts

@@ -0,0 +1,50 @@
+import type { Store, MemoryConnection, MemoryConnectionRelationshipType } from './types.js';
+
+export function isValidRelationshipType(type: string): type is MemoryConnectionRelationshipType {
+  return (['supports', 'contradicts', 'extends', 'supersedes', 'related', 'caused_by', 'refines', 'implements'] as string[]).includes(type);
+}
+
+export interface TraversalNode {
+  docId: number;
+  depth: number;
+  path: MemoryConnection[];
+}
+
+export function traverse(
+  store: Store,
+  startDocId: number,
+  options?: { maxDepth?: number; relationshipTypes?: string[] }
+): TraversalNode[] {
+  const maxDepth = options?.maxDepth ?? 2;
+  const visited = new Set<number>();
+  const result: TraversalNode[] = [];
+  const queue: TraversalNode[] = [{ docId: startDocId, depth: 0, path: [] }];
+  visited.add(startDocId);
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (current.depth > 0) result.push(current);
+    if (current.depth >= maxDepth) continue;
+
+    const connections = store.getConnectionsForDocument(current.docId, {
+      relationshipType: options?.relationshipTypes?.length === 1 ? options.relationshipTypes[0] : undefined,
+    });
+
+    for (const conn of connections) {
+      if (options?.relationshipTypes && options.relationshipTypes.length > 1) {
+        if (!options.relationshipTypes.includes(conn.relationshipType)) continue;
+      }
+      const neighborId = conn.fromDocId === current.docId ? conn.toDocId : conn.fromDocId;
+      if (visited.has(neighborId)) continue;
+      visited.add(neighborId);
+      queue.push({ docId: neighborId, depth: current.depth + 1, path: [...current.path, conn] });
+    }
+  }
+
+  return result;
+}
+
+export function getRelatedDocuments(store: Store, docId: number, relationshipType?: string): number[] {
+  const connections = store.getConnectionsForDocument(docId, { relationshipType });
+  return connections.map(c => c.fromDocId === docId ? c.toDocId : c.fromDocId);
+}

package/src/consolidation.ts

@@ -169,6 +169,36 @@ Respond with ONLY a JSON array, no other text.`;
       result.overallConfidence,
       new Date().toISOString()
     );
+
+    if (result.connections.length > 0) {
+      const projectHashRow = result.sourceIds.length > 0
+        ? db.prepare('SELECT project_hash FROM documents WHERE id = ?').get(result.sourceIds[0]) as { project_hash: string } | undefined
+        : undefined;
+      const projectHash = projectHashRow?.project_hash ?? 'global';
+      let created = 0;
+      for (const conn of result.connections) {
+        if (!conn.fromId || !conn.toId || !conn.relationship) continue;
+        try {
+          if (this.store.getConnectionCount(conn.fromId) >= 50) continue;
+          this.store.insertConnection({
+            fromDocId: conn.fromId,
+            toDocId: conn.toId,
+            relationshipType: conn.relationship as any,
+            description: null,
+            strength: typeof conn.confidence === 'number' ? conn.confidence : result.overallConfidence,
+            createdBy: 'consolidation',
+            projectHash,
+          });
+          created++;
+        } catch (err) {
+          log('consolidation', 'Failed to create connection ' + conn.fromId + '->' + conn.toId + ': ' + (err instanceof Error ? err.message : String(err)), 'warn');
+        }
+      }
+      if (created > 0) {
+        log('consolidation', 'Created ' + created + ' memory connections from consolidation');
+      }
+    }
+
     log('consolidation', 'Applied consolidation for ' + result.sourceIds.length + ' memories, confidence=' + result.overallConfidence.toFixed(2));
   }
 

package/src/server.ts

@@ -11,7 +11,8 @@ import * as os from 'os';
 import * as crypto from 'crypto';
 import * as http from 'http';
 import type { Store, SearchResult, IndexHealth, Collection, StorageConfig, CodebaseConfig, EmbeddingConfig, WatcherConfig, SearchConfig, ConsolidationConfig, ProactiveConfig } from './types.js'
-import { DEFAULT_PROACTIVE_CONFIG } from './types.js'
+import { DEFAULT_PROACTIVE_CONFIG, VALID_RELATIONSHIP_TYPES } from './types.js'
+import { traverse, isValidRelationshipType } from './connection-graph.js';
 import { extractEntitiesFromMemory } from './entity-extraction.js'
 import { createLLMProvider } from './llm-provider.js';
 import { ConsolidationAgent } from './consolidation.js';
@@ -2549,6 +2550,160 @@ export function createMcpServer(deps: ServerDeps): McpServer {
       }
     }
   );
+
+  server.tool(
+    'memory_connections',
+    'Get all connections for a document. Shows how memories relate to each other.',
+    {
+      doc_id: z.string().describe('Document ID or path'),
+      relationship_type: z.string().optional().describe('Filter by type: supports, contradicts, extends, supersedes, related, caused_by, refines, implements'),
+      direction: z.enum(['incoming', 'outgoing', 'both']).optional().default('both').describe('Connection direction'),
+      workspace: z.string().optional().describe('Workspace path or hash. Required in daemon mode.'),
+    },
+    async ({ doc_id, relationship_type, direction, workspace }) => {
+      if (checkReady()) return WARMUP_ERROR;
+      log('mcp', 'memory_connections doc_id="' + doc_id + '" type="' + (relationship_type || '') + '"');
+
+      const wsResult = requireDaemonWorkspace(deps, workspace);
+      if ('error' in wsResult) {
+        return { content: [{ type: 'text', text: wsResult.error }], isError: true };
+      }
+
+      const doc = wsResult.store.findDocument(doc_id);
+      if (!doc) {
+        return { content: [{ type: 'text', text: 'Document not found: ' + doc_id }], isError: true };
+      }
+
+      if (relationship_type && !isValidRelationshipType(relationship_type)) {
+        return { content: [{ type: 'text', text: 'Invalid relationship type: ' + relationship_type + '. Valid: ' + VALID_RELATIONSHIP_TYPES.join(', ') }], isError: true };
+      }
+
+      const connections = wsResult.store.getConnectionsForDocument(doc.id, {
+        direction: direction as 'incoming' | 'outgoing' | 'both',
+        relationshipType: relationship_type,
+      });
+
+      if (connections.length === 0) {
+        return { content: [{ type: 'text', text: 'No connections found for ' + doc_id }] };
+      }
+
+      const lines: string[] = [`## Connections for ${doc.title} (${connections.length})\n`];
+      for (const conn of connections) {
+        const otherId = conn.fromDocId === doc.id ? conn.toDocId : conn.fromDocId;
+        const otherDoc = wsResult.store.findDocument(String(otherId));
+        const dir = conn.fromDocId === doc.id ? '→' : '←';
+        lines.push(`- ${dir} **${conn.relationshipType}** ${otherDoc?.title ?? 'doc#' + otherId} (strength: ${conn.strength.toFixed(2)}, by: ${conn.createdBy})`);
+        if (conn.description) lines.push(`  ${conn.description}`);
+      }
+
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+  );
+
+  server.tool(
+    'memory_traverse',
+    'Traverse the memory connection graph from a starting document. Finds related memories up to N hops away.',
+    {
+      start_doc_id: z.string().describe('Starting document ID or path'),
+      max_depth: z.number().optional().default(2).describe('Maximum traversal depth (default: 2)'),
+      relationship_types: z.array(z.string()).optional().describe('Only follow these relationship types'),
+      workspace: z.string().optional().describe('Workspace path or hash. Required in daemon mode.'),
+    },
+    async ({ start_doc_id, max_depth, relationship_types, workspace }) => {
+      if (checkReady()) return WARMUP_ERROR;
+      log('mcp', 'memory_traverse start="' + start_doc_id + '" depth=' + max_depth);
+
+      const wsResult = requireDaemonWorkspace(deps, workspace);
+      if ('error' in wsResult) {
+        return { content: [{ type: 'text', text: wsResult.error }], isError: true };
+      }
+
+      const doc = wsResult.store.findDocument(start_doc_id);
+      if (!doc) {
+        return { content: [{ type: 'text', text: 'Document not found: ' + start_doc_id }], isError: true };
+      }
+
+      if (relationship_types) {
+        for (const rt of relationship_types) {
+          if (!isValidRelationshipType(rt)) {
+            return { content: [{ type: 'text', text: 'Invalid relationship type: ' + rt + '. Valid: ' + VALID_RELATIONSHIP_TYPES.join(', ') }], isError: true };
+          }
+        }
+      }
+
+      const nodes = traverse(wsResult.store, doc.id, { maxDepth: max_depth, relationshipTypes: relationship_types });
+
+      if (nodes.length === 0) {
+        return { content: [{ type: 'text', text: 'No connected memories found within depth ' + max_depth }] };
+      }
+
+      const lines: string[] = [`## Graph traversal from: ${doc.title}\n`];
+      for (const node of nodes) {
+        const nodeDoc = wsResult.store.findDocument(String(node.docId));
+        const indent = '  '.repeat(node.depth);
+        const lastConn = node.path[node.path.length - 1];
+        lines.push(`${indent}[depth ${node.depth}] ${nodeDoc?.title ?? 'doc#' + node.docId} (via ${lastConn?.relationshipType ?? '?'})`);
+      }
+      lines.push(`\n**Total:** ${nodes.length} connected memories found`);
+
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+  );
+
+  server.tool(
+    'memory_connect',
+    'Create a connection between two memories. Defines how they relate to each other.',
+    {
+      from_doc_id: z.string().describe('Source document ID or path'),
+      to_doc_id: z.string().describe('Target document ID or path'),
+      relationship_type: z.string().describe('Type: supports, contradicts, extends, supersedes, related, caused_by, refines, implements'),
+      description: z.string().optional().describe('Description of the relationship'),
+      strength: z.number().optional().default(1.0).describe('Connection strength 0.0-1.0 (default: 1.0)'),
+      workspace: z.string().optional().describe('Workspace path or hash. Required in daemon mode.'),
+    },
+    async ({ from_doc_id, to_doc_id, relationship_type, description, strength, workspace }) => {
+      if (checkReady()) return WARMUP_ERROR;
+      log('mcp', 'memory_connect from="' + from_doc_id + '" to="' + to_doc_id + '" type="' + relationship_type + '"');
+
+      const wsResult = requireDaemonWorkspace(deps, workspace);
+      if ('error' in wsResult) {
+        return { content: [{ type: 'text', text: wsResult.error }], isError: true };
+      }
+
+      if (!isValidRelationshipType(relationship_type)) {
+        return { content: [{ type: 'text', text: 'Invalid relationship type: ' + relationship_type + '. Valid: ' + VALID_RELATIONSHIP_TYPES.join(', ') }], isError: true };
+      }
+
+      const fromDoc = wsResult.store.findDocument(from_doc_id);
+      if (!fromDoc) {
+        return { content: [{ type: 'text', text: 'Source document not found: ' + from_doc_id }], isError: true };
+      }
+
+      const toDoc = wsResult.store.findDocument(to_doc_id);
+      if (!toDoc) {
+        return { content: [{ type: 'text', text: 'Target document not found: ' + to_doc_id }], isError: true };
+      }
+
+      const count = wsResult.store.getConnectionCount(fromDoc.id);
+      if (count >= 50) {
+        return { content: [{ type: 'text', text: 'Connection limit reached (50) for document: ' + from_doc_id }], isError: true };
+      }
+
+      const id = wsResult.store.insertConnection({
+        fromDocId: fromDoc.id,
+        toDocId: toDoc.id,
+        relationshipType: relationship_type as any,
+        description: description ?? null,
+        strength: strength ?? 1.0,
+        createdBy: 'user',
+        projectHash: wsResult.projectHash,
+      });
+
+      return {
+        content: [{ type: 'text', text: `✅ Connection created (#${id}): ${fromDoc.title} —[${relationship_type}]→ ${toDoc.title}` }],
+      };
+    }
+  );
   
   return server;
 }

package/src/store.ts

@@ -80,7 +80,6 @@ export function createStore(dbPath: string): Store {
   
   const cached = storeCache.get(resolvedPath);
   if (cached) {
-    log('store', 'createStore cache hit for ' + resolvedPath, 'debug');
     return cached;
   }
   
@@ -346,7 +345,7 @@ export function createStore(dbPath: string): Store {
   
   // Schema versioning
   const currentVersion = (db.pragma('user_version') as Array<{ user_version: number }>)[0].user_version;
-  const TARGET_VERSION = 6;
+  const TARGET_VERSION = 8;
 
   if (currentVersion < 1) {
     db.exec(`
@@ -548,6 +547,29 @@ export function createStore(dbPath: string): Store {
     db.pragma(`user_version = 7`);
     log('store', 'Schema migrated to version 7 (entity pruning support)');
   }
+
+  if (currentVersion < 8) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_connections (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        from_doc_id INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+        to_doc_id INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+        relationship_type TEXT NOT NULL,
+        description TEXT,
+        strength REAL NOT NULL DEFAULT 1.0,
+        created_by TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        project_hash TEXT NOT NULL,
+        UNIQUE(from_doc_id, to_doc_id, relationship_type)
+      );
+      CREATE INDEX IF NOT EXISTS idx_mc_from ON memory_connections(from_doc_id);
+      CREATE INDEX IF NOT EXISTS idx_mc_to ON memory_connections(to_doc_id);
+      CREATE INDEX IF NOT EXISTS idx_mc_type ON memory_connections(relationship_type);
+      CREATE INDEX IF NOT EXISTS idx_mc_project ON memory_connections(project_hash);
+    `);
+    db.pragma(`user_version = 8`);
+    log('store', 'Schema migrated to version 8 (memory connections)');
+  }
   
   if (vecAvailable) {
     try {
@@ -596,6 +618,19 @@ export function createStore(dbPath: string): Store {
   const deactivateDocumentStmt = db.prepare(`
     UPDATE documents SET active = 0 WHERE collection = ? AND path = ?
   `);
+
+  const insertConnectionStmt = db.prepare(`
+    INSERT INTO memory_connections (from_doc_id, to_doc_id, relationship_type, description, strength, created_by, project_hash)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(from_doc_id, to_doc_id, relationship_type) DO UPDATE SET
+      description = excluded.description, strength = excluded.strength, created_by = excluded.created_by
+  `);
+  const getConnectionsFromStmt = db.prepare(`SELECT * FROM memory_connections WHERE from_doc_id = ? ORDER BY strength DESC`);
+  const getConnectionsToStmt = db.prepare(`SELECT * FROM memory_connections WHERE to_doc_id = ? ORDER BY strength DESC`);
+  const getConnectionsBothStmt = db.prepare(`SELECT * FROM memory_connections WHERE from_doc_id = ? OR to_doc_id = ? ORDER BY strength DESC`);
+  const getConnectionsByTypeStmt = db.prepare(`SELECT * FROM memory_connections WHERE (from_doc_id = ? OR to_doc_id = ?) AND relationship_type = ? ORDER BY strength DESC`);
+  const deleteConnectionStmt = db.prepare(`DELETE FROM memory_connections WHERE id = ?`);
+  const getConnectionCountStmt = db.prepare(`SELECT COUNT(*) as cnt FROM memory_connections WHERE from_doc_id = ? OR to_doc_id = ?`);
   
 
   
@@ -1197,7 +1232,7 @@ export function createStore(dbPath: string): Store {
     
     close() {
       if (_cached) {
-        log('store', 'close() skipped for cached store', 'debug');
+        // cached store — close is a no-op, real close happens via closeAllCachedStores()
         return;
       }
       try { db.pragma('wal_checkpoint(PASSIVE)'); } catch { /* ignore checkpoint errors */ }
@@ -2695,6 +2730,49 @@ export function createStore(dbPath: string): Store {
       params.push(limit);
       return db.prepare(sql).all(...params) as Array<{ id: number; path: string; body: string }>;
     },
+
+    insertConnection(conn) {
+      const result = insertConnectionStmt.run(
+        conn.fromDocId, conn.toDocId, conn.relationshipType,
+        conn.description ?? null, conn.strength, conn.createdBy, conn.projectHash
+      );
+      return Number(result.lastInsertRowid);
+    },
+
+    getConnectionsForDocument(docId, options) {
+      const dir = options?.direction ?? 'both';
+      const relType = options?.relationshipType;
+      let rows: any[];
+      if (relType) {
+        rows = getConnectionsByTypeStmt.all(docId, docId, relType);
+      } else if (dir === 'outgoing') {
+        rows = getConnectionsFromStmt.all(docId);
+      } else if (dir === 'incoming') {
+        rows = getConnectionsToStmt.all(docId);
+      } else {
+        rows = getConnectionsBothStmt.all(docId, docId);
+      }
+      return rows.map((r: any) => ({
+        id: r.id,
+        fromDocId: r.from_doc_id,
+        toDocId: r.to_doc_id,
+        relationshipType: r.relationship_type,
+        description: r.description,
+        strength: r.strength,
+        createdBy: r.created_by,
+        createdAt: r.created_at,
+        projectHash: r.project_hash,
+      }));
+    },
+
+    deleteConnection(id) {
+      deleteConnectionStmt.run(id);
+    },
+
+    getConnectionCount(docId) {
+      const row = getConnectionCountStmt.get(docId, docId) as { cnt: number } | undefined;
+      return row?.cnt ?? 0;
+    },
   };
   
   _cached = true;

package/src/types.ts

@@ -612,6 +612,26 @@ export interface RemoveWorkspaceResult {
   executionFlowsDeleted: number;
 }
 
+export type MemoryConnectionRelationshipType = 'supports' | 'contradicts' | 'extends' | 'supersedes' | 'related' | 'caused_by' | 'refines' | 'implements';
+
+export type MemoryConnectionCreatedBy = 'consolidation' | 'user' | 'extraction';
+
+export const VALID_RELATIONSHIP_TYPES: MemoryConnectionRelationshipType[] = [
+  'supports', 'contradicts', 'extends', 'supersedes', 'related', 'caused_by', 'refines', 'implements'
+];
+
+export interface MemoryConnection {
+  id: number;
+  fromDocId: number;
+  toDocId: number;
+  relationshipType: MemoryConnectionRelationshipType;
+  description: string | null;
+  strength: number;
+  createdBy: MemoryConnectionCreatedBy;
+  createdAt: string;
+  projectHash: string;
+}
+
 export interface Store {
   getDb(): import('better-sqlite3').Database;
   close(): void;
@@ -798,4 +818,9 @@ export interface Store {
   deduplicateEdges(entityId: number): void;
 
   getUncategorizedDocuments(limit: number, projectHash?: string): Array<{ id: number; path: string; body: string }>;
+
+  insertConnection(conn: Omit<MemoryConnection, 'id' | 'createdAt'>): number;
+  getConnectionsForDocument(docId: number, options?: { direction?: 'incoming' | 'outgoing' | 'both'; relationshipType?: string; projectHash?: string }): MemoryConnection[];
+  deleteConnection(id: number): void;
+  getConnectionCount(docId: number): number;
 }

package/src/watcher.ts

@@ -337,13 +337,12 @@ export function startWatcher(options: WatcherOptions): Watcher {
         watchedPaths.add(expandedPath)
       }
     }
-    if (codebaseConfig?.enabled && fs.existsSync(workspaceRoot)) {
-      pathsToWatch.push(workspaceRoot)
-      watchedPaths.add(workspaceRoot)
-      const excludePatterns = mergeExcludePatterns(codebaseConfig, workspaceRoot)
-      for (const pattern of excludePatterns) {
-        ignoredPatterns.push(globToChokidarMatcher(pattern))
-      }
+    // NOTE: We intentionally do NOT watch the workspace root for codebase changes.
+    // Large workspaces (e.g. 30+ subprojects, 8000+ dirs) exhaust OS file descriptor
+    // limits even with node_modules excluded. Codebase changes are picked up by the
+    // poll-based reindex cycle instead (pollIntervalMs, default 5min).
+    if (codebaseConfig?.enabled) {
+      log('watcher', 'Codebase watching uses poll-based reindex (not fs.watch) to avoid EMFILE on large workspaces')
     }
     const deduped: string[] = []
     for (const p of pathsToWatch) {