cognitive-core 0.1.0 → 0.2.0

package/tests/memory/knowledge-bank.test.ts

@@ -0,0 +1,705 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, readFile, readdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { KnowledgeBank } from '../../src/memory/knowledge-bank.js';
+import type { KnowledgeBankConfig } from '../../src/types/config.js';
+import {
+  createObservation,
+  createEntityNote,
+  createDomainSummary,
+} from '../../src/types/knowledge.js';
+import type { KnowledgeNote } from '../../src/types/knowledge.js';
+
+function defaultConfig(): KnowledgeBankConfig {
+  return {
+    enabled: true,
+    memoryDir: 'memory',
+    extraction: {
+      enabled: true,
+      useLlmExtraction: false,
+      minAttributionScore: 0.3,
+    },
+    defrag: {
+      minInboxItems: 5,
+      autoConsolidate: true,
+      consolidationThreshold: 3,
+      autoRegenerateSummaries: true,
+      llmSummaryGeneration: false,
+      autoResolveContradictions: false,
+    },
+    confidence: {
+      extractedInitial: 0.3,
+      agentAuthoredInitial: 0.5,
+      reinforcementAlpha: 0.1,
+      contradictionPenalty: 0.3,
+      dailyDecayRate: 0.001,
+      staleThreshold: 0.2,
+      decayGracePeriodDays: 90,
+    },
+    graph: {
+      enabledLayers: ['semantic'],
+      inferTemporalEdges: true,
+      inferCausalEdges: true,
+      inferEntityEdges: true,
+      domainSplitThreshold: 500,
+      sqlitePromotionThreshold: 10000,
+    },
+    surfacing: {
+      includeDomainSummaries: true,
+      includeEntityNotes: true,
+      maxNotesPerTask: 5,
+      maxTokensForKnowledge: 2000,
+      includeEvidence: true,
+      includeLinks: false,
+    },
+    minimemAware: false,
+  };
+}
+
+function sampleObservation(id?: string): KnowledgeNote {
+  return createObservation({
+    id: id ?? 'k-test-obs',
+    title: 'Test Observation',
+    body: 'This is a test observation.',
+    domain: ['testing'],
+    entities: ['vitest'],
+    tags: ['unit-test'],
+    confidence: 0.7,
+    source: { origin: 'extracted', trajectories: ['t-123'] },
+    links: [{ target: 'k-other', relation: 'related-to' }],
+  });
+}
+
+describe('KnowledgeBank', () => {
+  let tmpDir: string;
+  let bank: KnowledgeBank;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'kb-test-'));
+    bank = new KnowledgeBank(tmpDir, defaultConfig());
+  });
+
+  afterEach(async () => {
+    try {
+      await bank.close();
+    } catch {
+      // ignore
+    }
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('init', () => {
+    it('creates directory structure on init', async () => {
+      await bank.init();
+
+      const dirs = await readdir(tmpDir, { recursive: true });
+      const dirNames = dirs.map(String);
+
+      expect(dirNames).toContain('knowledge');
+      expect(dirNames).toContain(join('knowledge', 'observations'));
+      expect(dirNames).toContain(join('knowledge', 'entities'));
+      expect(dirNames).toContain(join('knowledge', 'domains'));
+      expect(dirNames).toContain('inbox');
+      expect(dirNames).toContain('.knowledge');
+    });
+
+    it('is idempotent', async () => {
+      await bank.init();
+      await bank.init();
+      // Should not throw
+    });
+  });
+
+  describe('addObservation', () => {
+    it('writes a note to disk and returns its ID', async () => {
+      const note = sampleObservation();
+      const id = await bank.addObservation(note);
+
+      expect(id).toBe('k-test-obs');
+
+      // Verify file exists
+      const filePath = join(tmpDir, note.filePath);
+      const content = await readFile(filePath, 'utf-8');
+      expect(content).toContain('id: k-test-obs');
+      expect(content).toContain('Test Observation');
+    });
+
+    it('adds node to graph', async () => {
+      const note = sampleObservation();
+      await bank.addObservation(note);
+
+      const graphNode = bank.graph.getNode('k-test-obs');
+      expect(graphNode).toBeDefined();
+      expect(graphNode!.type).toBe('observation');
+      expect(graphNode!.domains).toEqual(['testing']);
+    });
+  });
+
+  describe('getNote', () => {
+    it('retrieves a note by ID', async () => {
+      const note = sampleObservation();
+      await bank.addObservation(note);
+
+      const retrieved = await bank.getNote('k-test-obs');
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.frontmatter.id).toBe('k-test-obs');
+      expect(retrieved!.body).toContain('Test Observation');
+    });
+
+    it('returns null for unknown ID', async () => {
+      await bank.init();
+      const result = await bank.getNote('nonexistent');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('getEntity / listEntities', () => {
+    it('retrieves an entity note by name', async () => {
+      const entity = createEntityNote({
+        entityName: 'Prisma',
+        body: 'ORM for Node.js',
+        domain: ['database'],
+        source: { origin: 'extracted' },
+      });
+      await bank.addObservation(entity);
+
+      const retrieved = await bank.getEntity('Prisma');
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.frontmatter.type).toBe('entity');
+    });
+
+    it('lists all entity names', async () => {
+      const entity1 = createEntityNote({
+        entityName: 'Prisma',
+        body: 'ORM',
+        domain: ['db'],
+        source: { origin: 'extracted' },
+      });
+      const entity2 = createEntityNote({
+        entityName: 'React',
+        body: 'UI lib',
+        domain: ['frontend'],
+        source: { origin: 'extracted' },
+      });
+
+      await bank.addObservation(entity1);
+      await bank.addObservation(entity2);
+
+      const entities = await bank.listEntities();
+      expect(entities).toContain('prisma');
+      expect(entities).toContain('react');
+    });
+
+    it('returns null for unknown entity', async () => {
+      await bank.init();
+      const result = await bank.getEntity('Unknown');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('getAllNotes', () => {
+    it('returns all notes across directories', async () => {
+      await bank.addObservation(sampleObservation('k-obs-1'));
+      await bank.addObservation(sampleObservation('k-obs-2'));
+
+      const entity = createEntityNote({
+        entityName: 'TestEntity',
+        body: 'Body',
+        domain: ['test'],
+        source: { origin: 'extracted' },
+      });
+      await bank.addObservation(entity);
+
+      const allNotes = await bank.getAllNotes();
+      expect(allNotes.length).toBeGreaterThanOrEqual(3);
+    });
+  });
+
+  describe('updateEntity', () => {
+    it('appends section to existing entity note', async () => {
+      const entity = createEntityNote({
+        entityName: 'Prisma',
+        body: 'Original content.',
+        domain: ['database'],
+        source: { origin: 'extracted' },
+      });
+      await bank.addObservation(entity);
+
+      await bank.updateEntity('prisma', {
+        entityId: 'prisma',
+        section: '## New Section\n\nAppended content.',
+        trajectoryId: 't-456',
+      });
+
+      const updated = await bank.getNote('prisma');
+      expect(updated).not.toBeNull();
+      expect(updated!.body).toContain('Original content.');
+      expect(updated!.body).toContain('## New Section');
+      expect(updated!.body).toContain('Appended content.');
+      expect(updated!.body).toContain('trajectory t-456');
+    });
+
+    it('adds trajectory to source', async () => {
+      const entity = createEntityNote({
+        entityName: 'Prisma',
+        body: 'Content.',
+        domain: ['database'],
+        source: { origin: 'extracted', trajectories: ['t-111'] },
+      });
+      await bank.addObservation(entity);
+
+      await bank.updateEntity('prisma', {
+        entityId: 'prisma',
+        section: 'Update',
+        trajectoryId: 't-222',
+      });
+
+      const updated = await bank.getNote('prisma');
+      expect(updated!.frontmatter.source.trajectories).toContain('t-111');
+      expect(updated!.frontmatter.source.trajectories).toContain('t-222');
+    });
+
+    it('throws for non-existent entity', async () => {
+      await bank.init();
+
+      await expect(
+        bank.updateEntity('nonexistent', {
+          entityId: 'nonexistent',
+          section: 'Update',
+          trajectoryId: 't-999',
+        })
+      ).rejects.toThrow('Entity note not found');
+    });
+  });
+
+  describe('getRelated', () => {
+    it('returns related notes via graph traversal', async () => {
+      const noteA = sampleObservation('k-a');
+      const noteB = sampleObservation('k-b');
+
+      await bank.addObservation(noteA);
+      await bank.addObservation(noteB);
+
+      // Manually add a semantic edge
+      bank.graph.getLayer('semantic')!.addEdge({
+        from: 'k-a',
+        to: 'k-b',
+        relation: 'related-to',
+        weight: 1.0,
+        created: new Date().toISOString(),
+      });
+
+      const related = await bank.getRelated('k-a');
+      expect(related.length).toBeGreaterThanOrEqual(1);
+      expect(related[0].note.frontmatter.id).toBe('k-b');
+      expect(related[0].matchType).toBe('graph');
+    });
+  });
+
+  describe('getStats', () => {
+    it('returns correct statistics', async () => {
+      await bank.addObservation(sampleObservation('k-s1'));
+      await bank.addObservation(sampleObservation('k-s2'));
+
+      const stats = await bank.getStats();
+
+      expect(stats.observationCount).toBe(2);
+      expect(stats.entityCount).toBe(0);
+      expect(stats.domainCount).toBe(0);
+      expect(stats.inboxCount).toBe(0);
+      expect(stats.avgConfidence).toBeCloseTo(0.7);
+      expect(stats.domainBreakdown.testing).toBe(2);
+      expect(stats.graph.enabledLayers).toContain('semantic');
+    });
+
+    it('returns zero stats when empty', async () => {
+      await bank.init();
+      const stats = await bank.getStats();
+
+      expect(stats.observationCount).toBe(0);
+      expect(stats.avgConfidence).toBe(0);
+    });
+  });
+
+  describe('close / persistence', () => {
+    it('saves graph to disk on close and reloads on init', async () => {
+      await bank.addObservation(sampleObservation('k-persist'));
+      await bank.close();
+
+      // Create a new bank instance pointing at same directory
+      const bank2 = new KnowledgeBank(tmpDir, defaultConfig());
+      await bank2.init();
+
+      // The note file should still be on disk
+      const note = await bank2.getNote('k-persist');
+      expect(note).not.toBeNull();
+
+      // The graph should have been loaded from disk
+      const graphNode = bank2.graph.getNode('k-persist');
+      expect(graphNode).toBeDefined();
+
+      await bank2.close();
+    });
+  });
+
+  // =========================================================================
+  // Search
+  // =========================================================================
+
+  describe('search', () => {
+    it('finds notes matching query text', async () => {
+      await bank.addObservation(
+        createObservation({
+          id: 'k-prisma-push',
+          title: 'Prisma push',
+          body: 'Prisma requires db push before migrate dev when schema has drifted',
+          domain: ['database'],
+          entities: ['prisma'],
+          tags: [],
+          source: { origin: 'extracted' },
+        })
+      );
+      await bank.addObservation(
+        createObservation({
+          id: 'k-react-hooks',
+          title: 'React hooks',
+          body: 'React hooks must be called at the top level of a component',
+          domain: ['frontend'],
+          entities: ['react'],
+          tags: [],
+          source: { origin: 'extracted' },
+        })
+      );
+
+      const results = await bank.search('prisma migrate database');
+      expect(results.length).toBeGreaterThanOrEqual(1);
+      expect(results[0].note.frontmatter.id).toBe('k-prisma-push');
+      expect(results[0].matchType).toBe('semantic');
+      expect(results[0].score).toBeGreaterThan(0);
+    });
+
+    it('filters by domain', async () => {
+      await bank.addObservation(
+        createObservation({
+          id: 'k-db-note',
+          title: 'DB fact',
+          body: 'Database optimization tip for better performance',
+          domain: ['database'],
+          entities: [],
+          tags: [],
+          source: { origin: 'extracted' },
+        })
+      );
+      await bank.addObservation(
+        createObservation({
+          id: 'k-ui-note',
+          title: 'UI fact',
+          body: 'UI optimization tip for better performance',
+          domain: ['frontend'],
+          entities: [],
+          tags: [],
+          source: { origin: 'extracted' },
+        })
+      );
+
+      const results = await bank.search('optimization', {
+        domains: ['database'],
+      });
+      expect(
+        results.every((r) =>
+          r.note.frontmatter.domain.includes('database')
+        )
+      ).toBe(true);
+    });
+
+    it('skips stale notes', async () => {
+      await bank.addObservation(
+        createObservation({
+          id: 'k-stale-note',
+          title: 'Stale knowledge',
+          body: 'This is outdated information about testing',
+          domain: ['testing'],
+          entities: [],
+          tags: ['stale'],
+          source: { origin: 'extracted' },
+        })
+      );
+
+      const results = await bank.search('testing');
+      expect(
+        results.find((r) => r.note.frontmatter.id === 'k-stale-note')
+      ).toBeUndefined();
+    });
+
+    it('respects maxResults', async () => {
+      for (let i = 0; i < 5; i++) {
+        await bank.addObservation(
+          createObservation({
+            id: `k-note-${i}`,
+            title: `Test observation ${i}`,
+            body: 'Common test content about testing patterns and approaches',
+            domain: ['testing'],
+            entities: [],
+            tags: [],
+            source: { origin: 'extracted' },
+          })
+        );
+      }
+
+      const results = await bank.search('test', { maxResults: 2 });
+      expect(results.length).toBeLessThanOrEqual(2);
+    });
+
+    it('returns empty array for empty bank', async () => {
+      await bank.init();
+      const results = await bank.search('anything');
+      expect(results).toEqual([]);
+    });
+  });
+
+  // =========================================================================
+  // Relevant Knowledge Retrieval
+  // =========================================================================
+
+  describe('getRelevantKnowledge', () => {
+    it('returns domain summary for matching domain (Tier 1)', async () => {
+      const summary = createDomainSummary({
+        domainName: 'database',
+        body: 'Overview of database knowledge including ORMs.',
+        source: { origin: 'extracted' },
+      });
+      await bank.addObservation(summary);
+
+      const results = await bank.getRelevantKnowledge({
+        description: 'Fix the database migration',
+        domain: 'database',
+      });
+
+      expect(
+        results.some((r) => r.note.frontmatter.type === 'domain-summary')
+      ).toBe(true);
+      expect(results[0].matchType).toBe('domain');
+    });
+
+    it('returns entity notes when task mentions entity name (Tier 2)', async () => {
+      const entity = createEntityNote({
+        entityName: 'Prisma',
+        body: 'Prisma is an ORM for Node.js.',
+        domain: ['database'],
+        source: { origin: 'extracted' },
+      });
+      await bank.addObservation(entity);
+
+      const results = await bank.getRelevantKnowledge({
+        description: 'Configure prisma for the new database',
+      });
+
+      expect(
+        results.some((r) => r.note.frontmatter.type === 'entity')
+      ).toBe(true);
+      expect(results.some((r) => r.matchType === 'entity')).toBe(true);
+    });
+
+    it('returns semantic matches from observations (Tier 3)', async () => {
+      await bank.addObservation(
+        createObservation({
+          id: 'k-migration-tip',
+          title: 'Migration tip',
+          body: 'Always run db push before migrate dev to avoid drift errors',
+          domain: ['database'],
+          entities: ['prisma'],
+          tags: [],
+          source: { origin: 'extracted' },
+        })
+      );
+
+      const results = await bank.getRelevantKnowledge({
+        description: 'Handle database migration drift',
+        domain: 'database',
+      });
+
+      expect(results.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('deduplicates across tiers', async () => {
+      const entity = createEntityNote({
+        entityName: 'Vitest',
+        body: 'Vitest is a test framework for TypeScript.',
+        domain: ['testing'],
+        source: { origin: 'extracted' },
+      });
+      await bank.addObservation(entity);
+
+      const results = await bank.getRelevantKnowledge({
+        description: 'Set up vitest for the project',
+        domain: 'testing',
+      });
+
+      const vistestIds = results.filter(
+        (r) => r.note.frontmatter.id === 'vitest'
+      );
+      expect(vistestIds.length).toBeLessThanOrEqual(1);
+    });
+
+    it('respects maxNotes limit', async () => {
+      for (let i = 0; i < 10; i++) {
+        await bank.addObservation(
+          createObservation({
+            id: `k-obs-${i}`,
+            title: `Testing pattern ${i}`,
+            body: `A useful testing pattern about testing approach number ${i}`,
+            domain: ['testing'],
+            entities: [],
+            tags: [],
+            source: { origin: 'extracted' },
+          })
+        );
+      }
+
+      const results = await bank.getRelevantKnowledge(
+        { description: 'Write tests for the module', domain: 'testing' },
+        { maxNotes: 3 }
+      );
+
+      expect(results.length).toBeLessThanOrEqual(3);
+    });
+
+    it('returns empty array for empty bank', async () => {
+      await bank.init();
+      const results = await bank.getRelevantKnowledge({
+        description: 'some task',
+      });
+      expect(results).toEqual([]);
+    });
+  });
+
+  // =========================================================================
+  // Format Knowledge For Prompt
+  // =========================================================================
+
+  describe('formatKnowledgeForPrompt', () => {
+    it('returns empty string for no notes', () => {
+      const result = bank.formatKnowledgeForPrompt([]);
+      expect(result).toBe('');
+    });
+
+    it('formats notes as markdown with heading', async () => {
+      const note = createObservation({
+        id: 'k-test',
+        title: 'Test fact',
+        body: 'Important fact about testing.',
+        domain: ['testing'],
+        entities: ['vitest'],
+        tags: [],
+        confidence: 0.85,
+        source: { origin: 'extracted', trajectories: ['t-123'] },
+      });
+
+      const result = bank.formatKnowledgeForPrompt([
+        { note, score: 0.7, matchType: 'semantic' },
+      ]);
+
+      expect(result).toContain('## Relevant Knowledge');
+      expect(result).toContain('85% confidence');
+      expect(result).toContain('Important fact about testing.');
+    });
+
+    it('groups by type: domain summaries, then entities, then observations', async () => {
+      const obs = createObservation({
+        id: 'k-obs',
+        title: 'Observation',
+        body: 'An observation note.',
+        domain: ['test'],
+        entities: [],
+        tags: [],
+        source: { origin: 'extracted' },
+      });
+      const entity = createEntityNote({
+        entityName: 'TestTool',
+        body: 'Entity note content.',
+        domain: ['test'],
+        source: { origin: 'extracted' },
+      });
+      const domain = createDomainSummary({
+        domainName: 'test',
+        body: 'Domain summary content.',
+        source: { origin: 'extracted' },
+      });
+
+      const result = bank.formatKnowledgeForPrompt([
+        { note: obs, score: 0.5, matchType: 'semantic' },
+        { note: entity, score: 0.7, matchType: 'entity' },
+        { note: domain, score: 1.0, matchType: 'domain' },
+      ]);
+
+      const domainIdx = result.indexOf('Overview');
+      const entityIdx = result.indexOf('About TestTool');
+      const obsIdx = result.indexOf('k-obs');
+
+      expect(domainIdx).toBeLessThan(entityIdx);
+      expect(entityIdx).toBeLessThan(obsIdx);
+    });
+
+    it('includes evidence when option is set', () => {
+      const note = createObservation({
+        id: 'k-ev',
+        title: 'Evidence note',
+        body: 'A note with evidence.',
+        domain: ['test'],
+        entities: [],
+        tags: [],
+        source: { origin: 'extracted', trajectories: ['t-111', 't-222'] },
+      });
+
+      const result = bank.formatKnowledgeForPrompt(
+        [{ note, score: 0.5, matchType: 'semantic' }],
+        { includeEvidence: true }
+      );
+
+      expect(result).toContain('t-111');
+      expect(result).toContain('t-222');
+    });
+
+    it('includes links when option is set', () => {
+      const note = createObservation({
+        id: 'k-link',
+        title: 'Link note',
+        body: 'A note with links.',
+        domain: ['test'],
+        entities: [],
+        tags: [],
+        source: { origin: 'extracted' },
+        links: [{ target: 'k-other', relation: 'related-to' }],
+      });
+
+      const result = bank.formatKnowledgeForPrompt(
+        [{ note, score: 0.5, matchType: 'semantic' }],
+        { includeLinks: true }
+      );
+
+      expect(result).toContain('related-to k-other');
+    });
+  });
+
+  describe('empty bank operations', () => {
+    it('processInbox returns zero counts on empty inbox', async () => {
+      await bank.init();
+      const result = await bank.processInbox();
+      expect(result.processed).toBe(0);
+    });
+
+    it('defragment runs on empty bank', async () => {
+      await bank.init();
+      const result = await bank.defragment();
+      expect(result.consolidated).toBe(0);
+      expect(result.graphRebuilt).toBe(true);
+    });
+
+    it('applyDecay returns zero counts on empty bank', async () => {
+      await bank.init();
+      const result = await bank.applyDecay();
+      expect(result.decayed).toBe(0);
+    });
+  });
+});