cognitive-core 0.2.4 → 0.3.1

package/src/memory/knowledge-bank.ts

@@ -1,1317 +0,0 @@
-import { readFile, writeFile, readdir, mkdir, unlink, access } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import type {
-  KnowledgeNote,
-  KnowledgeMatch,
-  KnowledgeStats,
-  EntityUpdate,
-  Contradiction,
-  ExtractedKnowledge,
-  InboxResult,
-  DefragResult,
-  DecayResult,
-  GraphLayerName,
-  PlaybookLink,
-} from '../types/knowledge.js';
-import { inferLayerFromRelation, createObservation } from '../types/knowledge.js';
-import type { Trajectory } from '../types/index.js';
-import type { TrajectorySource } from '../types/trajectory-source.js';
-import type { KnowledgeBankConfig } from '../types/config.js';
-import type { GraphNode } from '../types/knowledge-graph.js';
-import type { AgenticTaskRunner } from '../workspace/runner.js';
-import type { TrajectoryAnalyzer, AnalysisResult } from '../learning/analyzer.js';
-import { KnowledgeGraphManager } from './knowledge-graph.js';
-import { CoherenceChecker } from './coherence.js';
-import {
-  parseKnowledgeNote,
-  serializeKnowledgeNote,
-} from '../utils/frontmatter.js';
-import type { SearchProvider } from './search-provider.js';
-import { TextSimilaritySearchProvider } from './search-providers/text-similarity.js';
-
-/**
- * KnowledgeBank — Semantic memory store for facts, concepts, and relationships.
- *
- * Uses the filesystem as the universal primary index (minimem-compatible).
- * Maintains a multi-layer graph overlay as a derived index for relationship queries.
- *
- * Directory structure:
- *   {memoryDir}/
- *     knowledge/
- *       observations/   — atomic facts (k-*.md)
- *       entities/       — living entity docs ({entity}.md)
- *       domains/        — domain summaries ({domain}.md)
- *     inbox/            — unorganized agent-authored notes
- *     .knowledge/       — derived index files (graph, manifest)
- */
-export class KnowledgeBank {
-  public readonly graph: KnowledgeGraphManager;
-
-  private memoryDir: string;
-  private readonly bankConfig: KnowledgeBankConfig;
-  private initialized = false;
-  private searchProvider: SearchProvider = new TextSimilaritySearchProvider();
-  private coherenceChecker: CoherenceChecker = new CoherenceChecker();
-
-  // Directory paths (resolved on init)
-  private observationsDir = '';
-  private entitiesDir = '';
-  private domainsDir = '';
-  private inboxDir = '';
-  private indexDir = '';
-
-  constructor(memoryDir: string, config: KnowledgeBankConfig) {
-    this.memoryDir = memoryDir;
-    this.bankConfig = config;
-    this.graph = new KnowledgeGraphManager(this.bankConfig.graph);
-  }
-
-  // =========================================================================
-  // Lifecycle
-  // =========================================================================
-
-  async init(): Promise<void> {
-    if (this.initialized) return;
-
-    // Resolve directory paths.
-    // When minimemAware, nest under memory/knowledge/ so paths align with
-    // minimem's directory layout; otherwise use the original knowledge/ root.
-    const knowledgeBase = this.bankConfig.minimemAware
-      ? join(this.memoryDir, 'memory', 'knowledge')
-      : join(this.memoryDir, 'knowledge');
-
-    this.observationsDir = join(knowledgeBase, 'observations');
-    this.entitiesDir = join(knowledgeBase, 'entities');
-    this.domainsDir = join(knowledgeBase, 'domains');
-    this.inboxDir = join(this.memoryDir, 'inbox');
-    this.indexDir = join(this.memoryDir, '.knowledge');
-
-    // Create directory structure
-    await Promise.all([
-      mkdir(this.observationsDir, { recursive: true }),
-      mkdir(this.entitiesDir, { recursive: true }),
-      mkdir(this.domainsDir, { recursive: true }),
-      mkdir(this.inboxDir, { recursive: true }),
-      mkdir(this.indexDir, { recursive: true }),
-    ]);
-
-    // Load graph from disk
-    await this.graph.loadFromDisk(this.indexDir);
-
-    // Detect minimem and swap search provider if available
-    if (this.bankConfig.minimemAware) {
-      await this.detectMinimem();
-    }
-
-    this.initialized = true;
-  }
-
-  async close(): Promise<void> {
-    if (!this.initialized) return;
-    await this.graph.saveToDisk(this.indexDir);
-  }
-
-  // =========================================================================
-  // Write Operations
-  // =========================================================================
-
-  /**
-   * Create a new knowledge note and write it to disk.
-   * Runs coherence checking against existing notes — contradictions are flagged
-   * via metadata but the note is still stored.
-   * Updates the graph overlay in memory.
-   */
-  async addObservation(note: KnowledgeNote): Promise<string> {
-    await this.init();
-
-    // Run coherence check against related existing notes (if enabled)
-    if (this.bankConfig.coherenceChecking !== false) {
-      try {
-        const existing = await this.getRelatedNotes(note);
-        const coherence = await this.coherenceChecker.check(note, existing);
-
-        if (!coherence.isCoherent) {
-          // Flag contradictions in metadata but still store the note
-          const meta = (note.frontmatter as Record<string, unknown>);
-          meta['contradictions'] = coherence.contradictions.map(
-            (c) => c.existingNoteId
-          );
-          meta['coherenceEnergy'] = coherence.globalEnergy;
-        }
-      } catch {
-        // Coherence check is non-critical — don't block insertion
-      }
-    }
-
-    await this.writeNote(note);
-    this.graph.addNode(this.noteToGraphNode(note));
-    return note.frontmatter.id;
-  }
-
-  /**
-   * Get the last coherence result from the most recent addObservation call.
-   * Useful for downstream consumers to react to contradictions.
-   */
-  getCoherenceChecker(): CoherenceChecker {
-    return this.coherenceChecker;
-  }
-
-  /**
-   * Update an existing entity note by appending a section.
-   */
-  async updateEntity(entityId: string, update: EntityUpdate): Promise<void> {
-    await this.init();
-
-    const note = await this.getNote(entityId);
-    if (!note) {
-      throw new Error(`Entity note not found: ${entityId}`);
-    }
-
-    // Append the new section
-    const separator = '\n\n---\n\n';
-    const evidence = `*Source: trajectory ${update.trajectoryId}*`;
-    note.body = `${note.body}${separator}${update.section}\n\n${evidence}`;
-
-    // Update timestamp
-    note.frontmatter.updated = new Date().toISOString();
-
-    // Add trajectory to sources if not already present
-    if (!note.frontmatter.source.trajectories) {
-      note.frontmatter.source.trajectories = [];
-    }
-    if (
-      !note.frontmatter.source.trajectories.includes(update.trajectoryId)
-    ) {
-      note.frontmatter.source.trajectories.push(update.trajectoryId);
-    }
-
-    await this.writeNote(note);
-
-    // Update graph node
-    this.graph.addNode(this.noteToGraphNode(note));
-  }
-
-  // =========================================================================
-  // Read Operations
-  // =========================================================================
-
-  /**
-   * Get a note by ID. Scans all directories.
-   */
-  async getNote(id: string): Promise<KnowledgeNote | null> {
-    await this.init();
-
-    // Try each directory
-    for (const dir of [
-      this.observationsDir,
-      this.entitiesDir,
-      this.domainsDir,
-    ]) {
-      const notes = await this.scanDirectory(dir);
-      const found = notes.find((n) => n.frontmatter.id === id);
-      if (found) return found;
-    }
-
-    return null;
-  }
-
-  /**
-   * Get an entity note by entity name.
-   */
-  async getEntity(entityName: string): Promise<KnowledgeNote | null> {
-    await this.init();
-
-    const slug = entityName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
-    const filePath = join(this.entitiesDir, `${slug}.md`);
-
-    try {
-      const content = await readFile(filePath, 'utf-8');
-      const relativePath = relative(this.memoryDir, filePath);
-      return parseKnowledgeNote(content, relativePath);
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Get a domain summary by domain name.
-   */
-  async getDomainSummary(domain: string): Promise<KnowledgeNote | null> {
-    await this.init();
-
-    const slug = domain.toLowerCase().replace(/[^a-z0-9]+/g, '-');
-    const filePath = join(this.domainsDir, `${slug}.md`);
-
-    try {
-      const content = await readFile(filePath, 'utf-8');
-      const relativePath = relative(this.memoryDir, filePath);
-      return parseKnowledgeNote(content, relativePath);
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * List all known entity names (from entity note filenames).
-   */
-  async listEntities(): Promise<string[]> {
-    await this.init();
-
-    try {
-      const files = await readdir(this.entitiesDir);
-      return files
-        .filter((f) => f.endsWith('.md'))
-        .map((f) => f.replace('.md', ''));
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * List all known domain names (from domain summary filenames).
-   */
-  async listDomains(): Promise<string[]> {
-    await this.init();
-
-    try {
-      const files = await readdir(this.domainsDir);
-      return files
-        .filter((f) => f.endsWith('.md'))
-        .map((f) => f.replace('.md', ''));
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Get all notes across all directories.
-   */
-  async getAllNotes(): Promise<KnowledgeNote[]> {
-    await this.init();
-
-    const [observations, entities, domains] = await Promise.all([
-      this.scanDirectory(this.observationsDir),
-      this.scanDirectory(this.entitiesDir),
-      this.scanDirectory(this.domainsDir),
-    ]);
-
-    return [...observations, ...entities, ...domains];
-  }
-
-  // =========================================================================
-  // Graph Delegation
-  // =========================================================================
-
-  /**
-   * Get related notes via multi-layer graph traversal.
-   */
-  async getRelated(
-    noteId: string,
-    options?: {
-      depth?: number;
-      layers?: GraphLayerName[];
-      minWeight?: number;
-    }
-  ): Promise<KnowledgeMatch[]> {
-    await this.init();
-
-    const neighborNodes = this.graph.neighbors(noteId, options);
-    const matches: KnowledgeMatch[] = [];
-
-    for (const graphNode of neighborNodes) {
-      const note = await this.getNote(graphNode.id);
-      if (note) {
-        matches.push({
-          note,
-          score: graphNode.confidence,
-          matchType: 'graph',
-        });
-      }
-    }
-
-    return matches.sort((a, b) => b.score - a.score);
-  }
-
-  /**
-   * Get cross-system links to playbooks.
-   */
-  async getPlaybookLinks(noteId: string): Promise<PlaybookLink[]> {
-    await this.init();
-
-    const edges = this.graph.crossSystemLinks(noteId);
-    return edges
-      .filter((e) => e.crossSystem === 'playbook')
-      .map((e) => ({
-        noteId: e.from,
-        playbookId: e.to,
-        relation: 'supports' as const,
-      }));
-  }
-
-  // =========================================================================
-  // Stats
-  // =========================================================================
-
-  async getStats(): Promise<KnowledgeStats> {
-    await this.init();
-
-    const [observations, entities, domains, inbox] = await Promise.all([
-      this.countFiles(this.observationsDir),
-      this.countFiles(this.entitiesDir),
-      this.countFiles(this.domainsDir),
-      this.countFiles(this.inboxDir),
-    ]);
-
-    const graphStats = this.graph.getStats();
-
-    // Compute average confidence and domain breakdown
-    const allNotes = await this.getAllNotes();
-    let totalConfidence = 0;
-    let staleCount = 0;
-    const domainBreakdown: Record<string, number> = {};
-
-    for (const note of allNotes) {
-      totalConfidence += note.frontmatter.confidence;
-      if (note.frontmatter.tags.includes('stale')) staleCount++;
-      for (const domain of note.frontmatter.domain) {
-        domainBreakdown[domain] = (domainBreakdown[domain] ?? 0) + 1;
-      }
-    }
-
-    return {
-      observationCount: observations,
-      entityCount: entities,
-      domainCount: domains,
-      inboxCount: inbox,
-      graph: graphStats,
-      avgConfidence:
-        allNotes.length > 0 ? totalConfidence / allNotes.length : 0,
-      staleCount,
-      domainBreakdown,
-    };
-  }
-
-  // =========================================================================
-  // Search & Retrieval
-  // =========================================================================
-
-  /**
-   * Search knowledge notes by text similarity.
-   * Scores against note ID + body using Jaccard + n-gram similarity.
-   */
-  async search(
-    query: string,
-    options?: { domains?: string[]; maxResults?: number }
-  ): Promise<KnowledgeMatch[]> {
-    await this.init();
-
-    const allNotes = await this.getAllNotes();
-    const maxResults = options?.maxResults ?? 10;
-
-    // Filter by domains if specified
-    let candidates = allNotes;
-    if (options?.domains && options.domains.length > 0) {
-      candidates = allNotes.filter((note) =>
-        note.frontmatter.domain.some((d) => options.domains!.includes(d))
-      );
-    }
-
-    // Exclude stale notes
-    candidates = candidates.filter(
-      (note) => !note.frontmatter.tags.includes('stale')
-    );
-
-    // Delegate scoring to the search provider
-    const results = await this.searchProvider.search(query, candidates, { maxResults });
-
-    // Build a lookup for fast note retrieval by ID
-    const noteById = new Map(candidates.map((n) => [n.frontmatter.id, n]));
-
-    const matches: KnowledgeMatch[] = [];
-    for (const r of results) {
-      const note = noteById.get(r.noteId);
-      if (note) {
-        matches.push({
-          note,
-          score: r.score,
-          matchType: 'semantic',
-        });
-      }
-    }
-    return matches;
-  }
-
-  /**
-   * Get relevant knowledge for a task using 3-tier retrieval:
-   * 1. Domain summary match
-   * 2. Entity name match in task description
-   * 3. Semantic text similarity search
-   */
-  async getRelevantKnowledge(
-    task: { description: string; domain?: string },
-    options?: {
-      maxNotes?: number;
-      maxTokens?: number;
-      layers?: GraphLayerName[];
-    }
-  ): Promise<KnowledgeMatch[]> {
-    await this.init();
-
-    const surfacingConfig = this.bankConfig.surfacing;
-    const maxNotes = options?.maxNotes ?? surfacingConfig.maxNotesPerTask;
-    const maxTokens = options?.maxTokens ?? surfacingConfig.maxTokensForKnowledge;
-    const matches: KnowledgeMatch[] = [];
-    const seenIds = new Set<string>();
-
-    // Tier 1: Domain match
-    if (surfacingConfig.includeDomainSummaries && task.domain) {
-      const domainSummary = await this.getDomainSummary(task.domain);
-      if (domainSummary && !seenIds.has(domainSummary.frontmatter.id)) {
-        seenIds.add(domainSummary.frontmatter.id);
-        matches.push({
-          note: domainSummary,
-          score: 1.0,
-          matchType: 'domain',
-        });
-      }
-    }
-
-    // Tier 2: Entity match
-    if (surfacingConfig.includeEntityNotes) {
-      const entityNames = await this.listEntities();
-      const taskLower = task.description.toLowerCase();
-
-      for (const entitySlug of entityNames) {
-        const entityWords = entitySlug.replace(/-/g, ' ');
-        if (taskLower.includes(entitySlug) || taskLower.includes(entityWords)) {
-          if (seenIds.has(entitySlug)) continue;
-          const entityNote = await this.getEntity(entitySlug);
-          if (entityNote) {
-            seenIds.add(entityNote.frontmatter.id);
-            matches.push({
-              note: entityNote,
-              score: 0.9,
-              matchType: 'entity',
-            });
-          }
-        }
-      }
-    }
-
-    // Tier 3: Semantic match
-    const remainingSlots = maxNotes - matches.length;
-    if (remainingSlots > 0) {
-      const searchResults = await this.search(task.description, {
-        domains: task.domain ? [task.domain] : undefined,
-        maxResults: remainingSlots + matches.length,
-      });
-
-      for (const result of searchResults) {
-        if (seenIds.has(result.note.frontmatter.id)) continue;
-        seenIds.add(result.note.frontmatter.id);
-        matches.push(result);
-        if (matches.length >= maxNotes) break;
-      }
-    }
-
-    // Sort: domain > entity > semantic, then by score
-    matches.sort((a, b) => {
-      const typeOrder: Record<string, number> = { domain: 0, entity: 1, semantic: 2, graph: 3 };
-      const typeA = typeOrder[a.matchType ?? 'semantic'];
-      const typeB = typeOrder[b.matchType ?? 'semantic'];
-      if (typeA !== typeB) return typeA - typeB;
-      return b.score - a.score;
-    });
-
-    // Enforce limits
-    const limited = matches.slice(0, maxNotes);
-    return this.enforceTokenBudget(limited, maxTokens);
-  }
-
-  /**
-   * Process inbox files: classify, move to correct directory, add to graph.
-   * Files with valid frontmatter are classified by type field.
-   * Files without valid frontmatter get heuristic classification as observations.
-   */
-  async processInbox(): Promise<InboxResult> {
-    await this.init();
-
-    let processed = 0;
-    let failed = 0;
-    let movedToObservations = 0;
-    let movedToEntities = 0;
-    let movedToDomains = 0;
-
-    let files: string[];
-    try {
-      files = (await readdir(this.inboxDir)).filter((f) => f.endsWith('.md'));
-    } catch {
-      return { processed, failed, movedToObservations, movedToEntities, movedToDomains };
-    }
-
-    for (const file of files) {
-      const absPath = join(this.inboxDir, file);
-      try {
-        const content = await readFile(absPath, 'utf-8');
-        const relativePath = `inbox/${file}`;
-        const parsed = parseKnowledgeNote(content, relativePath);
-
-        let note: KnowledgeNote;
-        if (parsed && parsed.frontmatter.type) {
-          // Valid frontmatter — use its type
-          note = parsed;
-        } else {
-          // No valid frontmatter — apply heuristic classification
-          note = this.processRawInboxFile(content, file);
-        }
-
-        // Move to correct directory based on type
-        const result = await this.moveInboxNote(note);
-        if (result === 'observation') movedToObservations++;
-        else if (result === 'entity') movedToEntities++;
-        else if (result === 'domain-summary') movedToDomains++;
-
-        // Add to graph
-        this.graph.addNode(this.noteToGraphNode(note));
-
-        // Remove from inbox
-        await unlink(absPath);
-        processed++;
-      } catch {
-        failed++;
-      }
-    }
-
-    return { processed, failed, movedToObservations, movedToEntities, movedToDomains };
-  }
-
-  /**
-   * Run the full 7-step defragmentation cycle via KnowledgeDefragmenter.
-   */
-  async defragment(): Promise<DefragResult> {
-    await this.init();
-    const { KnowledgeDefragmenter } = await import('./knowledge-defrag.js');
-    const defragmenter = new KnowledgeDefragmenter(
-      this,
-      this.bankConfig.defrag
-    );
-    return defragmenter.defragment();
-  }
-
-  async applyExtraction(extraction: ExtractedKnowledge): Promise<void> {
-    await this.init();
-
-    // 1. Add new observations
-    for (const obs of extraction.observations) {
-      await this.addObservation(obs);
-    }
-
-    // 2. Apply entity updates (skip if entity doesn't exist)
-    for (const update of extraction.entityUpdates) {
-      try {
-        await this.updateEntity(update.entityId, update);
-      } catch {
-        // Entity doesn't exist yet — skip
-      }
-    }
-
-    // 3. Record contradictions
-    for (const contradiction of extraction.contradictions) {
-      await this.recordContradiction(contradiction);
-    }
-
-    // 4. Add graph edges for new links
-    for (const link of extraction.links) {
-      const layer = inferLayerFromRelation(link.relation);
-      const graphLayer = this.graph.getLayer(layer);
-      if (!graphLayer) continue;
-
-      graphLayer.addEdge({
-        from: link.from,
-        to: link.to,
-        relation: link.relation,
-        weight: link.weight ?? 0.5,
-        created: new Date().toISOString(),
-      });
-    }
-
-    // 5. Add playbook cross-system links
-    for (const pbLink of extraction.playbookLinks) {
-      const semanticLayer = this.graph.getLayer('semantic');
-      if (!semanticLayer) continue;
-
-      semanticLayer.addEdge({
-        from: pbLink.noteId,
-        to: pbLink.playbookId,
-        relation: pbLink.relation,
-        weight: 0.5,
-        created: new Date().toISOString(),
-        crossSystem: 'playbook',
-      });
-    }
-  }
-
-  /**
-   * Reinforce a knowledge note with new evidence from a trajectory.
-   * Uses EMA to increase confidence: newConf = (1 - alpha) * oldConf + alpha * 1.0
-   */
-  async reinforce(noteId: string, trajectoryId: string): Promise<void> {
-    await this.init();
-
-    const note = await this.getNote(noteId);
-    if (!note) {
-      throw new Error(`Cannot reinforce: note not found: ${noteId}`);
-    }
-
-    const alpha = this.bankConfig.confidence.reinforcementAlpha;
-    note.frontmatter.confidence =
-      (1 - alpha) * note.frontmatter.confidence + alpha * 1.0;
-
-    // Add trajectory to source (no duplicates)
-    if (!note.frontmatter.source.trajectories) {
-      note.frontmatter.source.trajectories = [];
-    }
-    if (!note.frontmatter.source.trajectories.includes(trajectoryId)) {
-      note.frontmatter.source.trajectories.push(trajectoryId);
-    }
-
-    // Update timestamp
-    note.frontmatter.updated = new Date().toISOString();
-
-    await this.writeNote(note);
-    this.graph.addNode(this.noteToGraphNode(note));
-  }
-
-  async recordContradiction(contradiction: Contradiction): Promise<void> {
-    await this.init();
-
-    const penalty = this.bankConfig.confidence.contradictionPenalty;
-
-    // Add the new observation if it hasn't been added already
-    const existingNew = await this.getNote(contradiction.newObservation.frontmatter.id);
-    if (!existingNew) {
-      await this.addObservation(contradiction.newObservation);
-    }
-
-    // Add a 'contradicts' edge in the entity layer
-    const entityLayer = this.graph.getLayer('entity');
-    if (entityLayer) {
-      entityLayer.addEdge({
-        from: contradiction.newObservation.frontmatter.id,
-        to: contradiction.existingNoteId,
-        relation: 'contradicts',
-        weight: 0.8,
-        created: new Date().toISOString(),
-      });
-    }
-
-    // Load the existing note for confidence updates
-    const existingNote = await this.getNote(contradiction.existingNoteId);
-
-    if (contradiction.resolution === 'supersede') {
-      // Old note gets full penalty, new note supersedes
-      if (existingNote) {
-        existingNote.frontmatter.confidence = Math.max(
-          0,
-          existingNote.frontmatter.confidence - penalty
-        );
-        await this.writeNote(existingNote);
-        this.graph.addNode(this.noteToGraphNode(existingNote));
-      }
-
-      contradiction.newObservation.frontmatter.supersedes = contradiction.existingNoteId;
-      await this.writeNote(contradiction.newObservation);
-
-      // Add temporal 'supersedes' edge
-      const temporalLayer = this.graph.getLayer('temporal');
-      if (temporalLayer) {
-        temporalLayer.addEdge({
-          from: contradiction.newObservation.frontmatter.id,
-          to: contradiction.existingNoteId,
-          relation: 'supersedes',
-          weight: 1.0,
-          created: new Date().toISOString(),
-        });
-      }
-    } else if (contradiction.resolution === 'coexist') {
-      // Both notes get half penalty
-      const halfPenalty = penalty / 2;
-
-      if (existingNote) {
-        existingNote.frontmatter.confidence = Math.max(
-          0,
-          existingNote.frontmatter.confidence - halfPenalty
-        );
-        await this.writeNote(existingNote);
-        this.graph.addNode(this.noteToGraphNode(existingNote));
-      }
-
-      const newNote = await this.getNote(contradiction.newObservation.frontmatter.id);
-      if (newNote) {
-        newNote.frontmatter.confidence = Math.max(
-          0,
-          newNote.frontmatter.confidence - halfPenalty
-        );
-        await this.writeNote(newNote);
-        this.graph.addNode(this.noteToGraphNode(newNote));
-      }
-    } else if (contradiction.resolution === 'review') {
-      // No confidence change, tag both for review
-      if (existingNote) {
-        if (!existingNote.frontmatter.tags.includes('needs-review')) {
-          existingNote.frontmatter.tags.push('needs-review');
-          await this.writeNote(existingNote);
-          this.graph.addNode(this.noteToGraphNode(existingNote));
-        }
-      }
-
-      const newNote = await this.getNote(contradiction.newObservation.frontmatter.id);
-      if (newNote && !newNote.frontmatter.tags.includes('needs-review')) {
-        newNote.frontmatter.tags.push('needs-review');
-        await this.writeNote(newNote);
-        this.graph.addNode(this.noteToGraphNode(newNote));
-      }
-    }
-  }
-
-  /**
-   * Apply time-based confidence decay to all knowledge notes.
-   * Skips domain summaries, notes already tagged stale, and notes within the grace period.
-   */
-  async applyDecay(): Promise<DecayResult> {
-    await this.init();
-
-    const { dailyDecayRate, staleThreshold, decayGracePeriodDays } =
-      this.bankConfig.confidence;
-    const now = Date.now();
-    const msPerDay = 1000 * 60 * 60 * 24;
-
-    let decayed = 0;
-    let newlyStale = 0;
-    let alreadyStale = 0;
-
-    // Scan observations and entities (skip domain summaries)
-    const [observations, entities] = await Promise.all([
-      this.scanDirectory(this.observationsDir),
-      this.scanDirectory(this.entitiesDir),
-    ]);
-
-    for (const note of [...observations, ...entities]) {
-      // Skip already stale notes
-      if (note.frontmatter.tags.includes('stale')) {
-        alreadyStale++;
-        continue;
-      }
-
-      // Compute days since last update
-      const updatedMs = new Date(note.frontmatter.updated).getTime();
-      const daysSinceUpdated = (now - updatedMs) / msPerDay;
-
-      // Skip notes within grace period
-      if (daysSinceUpdated <= decayGracePeriodDays) {
-        continue;
-      }
-
-      // Apply exponential decay: newConf = oldConf * (1 - rate)^(days - grace)
-      const decayDays = daysSinceUpdated - decayGracePeriodDays;
-      const newConfidence =
-        note.frontmatter.confidence * Math.pow(1 - dailyDecayRate, decayDays);
-      note.frontmatter.confidence = Math.max(0, newConfidence);
-
-      // Mark as stale if below threshold
-      if (note.frontmatter.confidence < staleThreshold) {
-        if (!note.frontmatter.tags.includes('stale')) {
-          note.frontmatter.tags.push('stale');
-          newlyStale++;
-        }
-      }
-
-      // Write to disk without updating the 'updated' timestamp
-      await this.writeNote(note);
-      this.graph.addNode(this.noteToGraphNode(note));
-      decayed++;
-    }
-
-    return { decayed, newlyStale, alreadyStale };
-  }
-
-  // =========================================================================
-  // Extraction (Phase 2)
-  // =========================================================================
-
-  /**
-   * Extract knowledge from a trajectory source.
-   * Iterates all trajectories, runs extraction (agent or heuristic), and applies results.
-   */
-  async extractFrom(
-    source: TrajectorySource,
-    options?: {
-      taskRunner?: AgenticTaskRunner;
-      analyzer?: TrajectoryAnalyzer;
-    }
-  ): Promise<ExtractedKnowledge[]> {
-    await this.init();
-
-    const items = await source.load();
-    const results: ExtractedKnowledge[] = [];
-
-    for (const item of items) {
-      let analysis = item.analysis;
-      if (!analysis && options?.analyzer) {
-        analysis = await options.analyzer.analyze(item.trajectory);
-      }
-
-      const extraction = await this.extractFromTrajectory(
-        item.trajectory,
-        analysis,
-        options?.taskRunner
-      );
-      results.push(extraction);
-    }
-
-    return results;
-  }
-
-  /**
-   * Extract knowledge from a single trajectory.
-   * Uses the workspace template if a taskRunner is provided, otherwise falls back to heuristic.
-   * Applies the extraction to the knowledge bank.
-   */
-  async extractFromTrajectory(
-    trajectory: Trajectory,
-    analysis?: AnalysisResult,
-    taskRunner?: AgenticTaskRunner
-  ): Promise<ExtractedKnowledge> {
-    await this.init();
-
-    // Compute analysis if not provided
-    const { createAnalyzer } = await import('../learning/analyzer.js');
-    const resolvedAnalysis = analysis ?? await createAnalyzer('simple').analyze(trajectory);
-
-    // Gather context for extraction
-    const existingEntities = await this.listEntities();
-    const relatedNotes = await this.getAllNotes();
-
-    // Try workspace-based extraction if taskRunner is available
-    if (taskRunner) {
-      try {
-        const { knowledgeExtractionTemplate } = await import(
-          '../workspace/templates/knowledge-extraction.js'
-        );
-        const result = await taskRunner.run(knowledgeExtractionTemplate, {
-          trajectory,
-          analysis: resolvedAnalysis,
-          existingEntities,
-          relatedNotes: relatedNotes.slice(0, 20),
-        });
-        const extraction = result.output;
-        await this.applyExtraction(extraction);
-        return extraction;
-      } catch (error) {
-        console.error(
-          'Workspace-based knowledge extraction failed, falling back to heuristic:',
-          error instanceof Error ? error.message : error
-        );
-      }
-    }
-
-    // Heuristic fallback
-    const { KnowledgeExtractor } = await import(
-      '../learning/knowledge-extractor.js'
-    );
-    const extractor = new KnowledgeExtractor();
-    const extraction = extractor.extract(trajectory, resolvedAnalysis, {
-      existingEntities,
-    });
-    await this.applyExtraction(extraction);
-    return extraction;
-  }
-
-  /**
-   * Format knowledge notes as a markdown section for agent prompt injection.
-   * Groups by type: domain summaries → entities → observations.
-   */
-  formatKnowledgeForPrompt(
-    notes: KnowledgeMatch[],
-    options?: {
-      maxTokens?: number;
-      includeEvidence?: boolean;
-      includeLinks?: boolean;
-    }
-  ): string {
-    if (notes.length === 0) return '';
-
-    const includeEvidence =
-      options?.includeEvidence ?? this.bankConfig.surfacing.includeEvidence;
-    const includeLinks =
-      options?.includeLinks ?? this.bankConfig.surfacing.includeLinks;
-    const maxTokens =
-      options?.maxTokens ?? this.bankConfig.surfacing.maxTokensForKnowledge;
-
-    const sections: string[] = [];
-    sections.push('## Relevant Knowledge\n');
-
-    // Group by type
-    const domainSummaries = notes.filter(
-      (m) => m.note.frontmatter.type === 'domain-summary'
-    );
-    const entities = notes.filter(
-      (m) => m.note.frontmatter.type === 'entity'
-    );
-    const observations = notes.filter(
-      (m) => m.note.frontmatter.type === 'observation'
-    );
-
-    let tokenCount = 0;
-
-    for (const group of [domainSummaries, entities, observations]) {
-      for (const match of group) {
-        const noteSection = this.formatSingleNote(
-          match,
-          includeEvidence,
-          includeLinks
-        );
-        const sectionTokens = Math.ceil(noteSection.length / 4);
-
-        if (tokenCount + sectionTokens > maxTokens && sections.length > 1) {
-          break;
-        }
-
-        sections.push(noteSection);
-        tokenCount += sectionTokens;
-      }
-    }
-
-    return sections.join('\n');
-  }
-
-  // =========================================================================
-  // Search Provider
-  // =========================================================================
-
-  /**
-   * Get the name of the active search provider.
-   */
-  getSearchProviderName(): string {
-    return this.searchProvider.name;
-  }
-
-  /**
-   * Replace the active search provider (strategy pattern).
-   */
-  setSearchProvider(provider: SearchProvider): void {
-    this.searchProvider = provider;
-  }
-
-  // =========================================================================
-  // Internal Helpers
-  // =========================================================================
-
-  /**
-   * Detect whether minimem is available and set up the MinimemSearchProvider.
-   *
-   * Detection checks (in order):
-   * 1. Look for a `.minimem/` directory under memoryDir
-   * 2. Look for a `MEMORY.md` file under memoryDir
-   * 3. Create a Minimem instance and wire MinimemSearchProvider
-   *
-   * Falls back to TextSimilaritySearchProvider on any failure.
-   */
-  private async detectMinimem(): Promise<void> {
-    try {
-      // Check for minimem markers
-      const minimemDir = join(this.memoryDir, '.minimem');
-      const memoryMd = join(this.memoryDir, 'MEMORY.md');
-
-      let hasMinimemMarker = false;
-      try {
-        await access(minimemDir);
-        hasMinimemMarker = true;
-      } catch {
-        try {
-          await access(memoryMd);
-          hasMinimemMarker = true;
-        } catch {
-          // No minimem markers found
-        }
-      }
-
-      if (!hasMinimemMarker) return;
-
-      // minimem is a direct dependency — use normal dynamic import
-      try {
-        const { Minimem } = await import('minimem');
-        const minimemInstance = await Minimem.create({
-          memoryDir: this.memoryDir,
-          embedding: { provider: 'auto' },
-        });
-
-        const { MinimemSearchProvider } = await import(
-          './search-providers/minimem.js'
-        );
-        this.searchProvider = new MinimemSearchProvider(minimemInstance);
-      } catch {
-        // minimem initialization failed — keep text-similarity fallback
-      }
-    } catch {
-      // Detection failed — keep text-similarity fallback
-    }
-  }
-
-  /**
-   * Get the index directory path (for defragmenter).
-   */
-  getIndexDir(): string {
-    return this.indexDir;
-  }
-
-  /**
-   * Check if defragmentation should be triggered.
-   */
-  async shouldDefragment(): Promise<boolean> {
-    await this.init();
-    const inboxCount = await this.countFiles(this.inboxDir);
-    return inboxCount >= this.bankConfig.defrag.minInboxItems;
-  }
-
-  /**
-   * Resolve a note's file path and write it to disk.
-   */
-  private async writeNote(note: KnowledgeNote): Promise<void> {
-    // Resolve the file path: when minimemAware, remap knowledge/ → memory/knowledge/
-    if (
-      this.bankConfig.minimemAware &&
-      note.filePath.startsWith('knowledge/') &&
-      !note.filePath.startsWith('memory/knowledge/')
-    ) {
-      note.filePath = `memory/${note.filePath}`;
-    }
-
-    const absPath = join(this.memoryDir, note.filePath);
-    const dir = absPath.substring(0, absPath.lastIndexOf('/'));
-    await mkdir(dir, { recursive: true });
-    const content = serializeKnowledgeNote(note);
-    await writeFile(absPath, content, 'utf-8');
-  }
-
-  /**
-   * Scan a directory for .md files and parse them as KnowledgeNotes.
-   * Skips files with invalid/missing frontmatter.
-   */
-  private async scanDirectory(dir: string): Promise<KnowledgeNote[]> {
-    const notes: KnowledgeNote[] = [];
-
-    try {
-      const files = await readdir(dir);
-      for (const file of files) {
-        if (!file.endsWith('.md')) continue;
-
-        try {
-          const absPath = join(dir, file);
-          const content = await readFile(absPath, 'utf-8');
-          const relativePath = relative(this.memoryDir, absPath);
-          const note = parseKnowledgeNote(content, relativePath);
-          if (note) notes.push(note);
-        } catch {
-          // Skip files that can't be read
-        }
-      }
-    } catch {
-      // Directory doesn't exist yet
-    }
-
-    return notes;
-  }
-
-  /**
-   * Count .md files in a directory.
-   */
-  private async countFiles(dir: string): Promise<number> {
-    try {
-      const files = await readdir(dir);
-      return files.filter((f) => f.endsWith('.md')).length;
-    } catch {
-      return 0;
-    }
-  }
-
-  /**
-   * Resolve the relative path for a note based on its type and filename.
-   * When minimemAware, paths are nested under memory/knowledge/ instead of knowledge/.
-   */
-  private resolveNotePath(
-    type: 'observation' | 'entity' | 'domain-summary',
-    filename: string
-  ): string {
-    const knowledgePrefix = this.bankConfig.minimemAware
-      ? 'memory/knowledge'
-      : 'knowledge';
-
-    if (type === 'entity') {
-      return `${knowledgePrefix}/entities/${filename}`;
-    } else if (type === 'domain-summary') {
-      return `${knowledgePrefix}/domains/${filename}`;
-    }
-    return `${knowledgePrefix}/observations/${filename}`;
-  }
-
-  /**
-   * Move an inbox note to the correct directory based on its type.
-   * Updates the note's filePath accordingly.
-   */
-  private async moveInboxNote(
-    note: KnowledgeNote
-  ): Promise<'observation' | 'entity' | 'domain-summary'> {
-    const type = note.frontmatter.type;
-    const noteType: 'observation' | 'entity' | 'domain-summary' =
-      type === 'entity' ? 'entity' : type === 'domain-summary' ? 'domain-summary' : 'observation';
-
-    const filename = `${note.frontmatter.id}.md`;
-    note.filePath = this.resolveNotePath(noteType, filename);
-    await this.writeNote(note);
-
-    return noteType;
-  }
-
-  /**
-   * Create a KnowledgeNote from a raw inbox file with no valid frontmatter.
-   * Applies heuristic: observation type, agent-authored origin, agentAuthoredInitial confidence.
-   */
-  private processRawInboxFile(content: string, filename: string): KnowledgeNote {
-    const id = filename.replace('.md', '');
-    const title = id.replace(/[-_]/g, ' ');
-
-    return createObservation({
-      id,
-      title,
-      body: content,
-      domain: [],
-      entities: [],
-      tags: ['inbox-processed'],
-      confidence: this.bankConfig.confidence.agentAuthoredInitial,
-      source: { origin: 'agent-authored' as const },
-    });
-  }
-
-  /**
-   * Convert a KnowledgeNote to a GraphNode.
-   */
-  /**
-   * Enforce a token budget on a list of matches.
-   * Always includes at least one match.
-   */
-  private enforceTokenBudget(
-    matches: KnowledgeMatch[],
-    maxTokens: number
-  ): KnowledgeMatch[] {
-    const result: KnowledgeMatch[] = [];
-    let usedTokens = 0;
-
-    for (const match of matches) {
-      const noteTokens = Math.ceil(match.note.body.length / 4);
-      if (usedTokens + noteTokens > maxTokens && result.length > 0) {
-        break;
-      }
-      result.push(match);
-      usedTokens += noteTokens;
-    }
-
-    return result;
-  }
-
-  /**
-   * Format a single knowledge note for prompt injection.
-   */
-  private formatSingleNote(
-    match: KnowledgeMatch,
-    includeEvidence: boolean,
-    includeLinks: boolean
-  ): string {
-    const { note } = match;
-    const confidencePercent = Math.round(note.frontmatter.confidence * 100);
-    const lines: string[] = [];
-
-    // Title line with type-appropriate heading
-    if (note.frontmatter.type === 'domain-summary') {
-      lines.push(
-        `### ${note.frontmatter.domain[0] ?? 'General'} Overview (${confidencePercent}% confidence)`
-      );
-    } else if (note.frontmatter.type === 'entity') {
-      const entityName = note.frontmatter.entities[0] ?? note.frontmatter.id;
-      lines.push(
-        `### About ${entityName} (${confidencePercent}% confidence)`
-      );
-    } else {
-      lines.push(
-        `### ${note.frontmatter.id} (${confidencePercent}% confidence)`
-      );
-    }
-
-    // Body content — skip leading markdown heading
-    let bodyContent = note.body;
-    const firstLine = bodyContent.split('\n')[0];
-    if (firstLine.startsWith('#')) {
-      bodyContent = bodyContent.slice(firstLine.length).trim();
-    }
-    if (bodyContent.length > 500) {
-      bodyContent = bodyContent.slice(0, 497) + '...';
-    }
-    lines.push(bodyContent);
-
-    // Evidence citations
-    if (includeEvidence && note.frontmatter.source.trajectories?.length) {
-      const trajectoryIds = note.frontmatter.source.trajectories.slice(0, 3);
-      lines.push(`\n*Evidence: ${trajectoryIds.join(', ')}*`);
-    }
-
-    // Graph links
-    if (includeLinks && note.frontmatter.links.length > 0) {
-      const linkSummary = note.frontmatter.links
-        .slice(0, 3)
-        .map((l) => `${l.relation} ${l.target}`)
-        .join(', ');
-      lines.push(`*Related: ${linkSummary}*`);
-    }
-
-    lines.push('');
-    return lines.join('\n');
-  }
-
-  /**
-   * Get notes related to the given note by entity or domain overlap.
-   * Used for coherence checking before insertion.
-   */
-  private async getRelatedNotes(note: KnowledgeNote): Promise<KnowledgeNote[]> {
-    const allNotes = await this.getAllNotes();
-
-    const noteEntities = new Set(note.frontmatter.entities);
-    const noteDomains = new Set(note.frontmatter.domain);
-
-    return allNotes.filter((existing) => {
-      if (existing.frontmatter.id === note.frontmatter.id) return false;
-
-      const hasEntityOverlap = existing.frontmatter.entities.some((e) =>
-        noteEntities.has(e)
-      );
-      if (hasEntityOverlap) return true;
-
-      const hasDomainOverlap = existing.frontmatter.domain.some((d) =>
-        noteDomains.has(d)
-      );
-      return hasDomainOverlap;
-    });
-  }
-
-  private noteToGraphNode(note: KnowledgeNote): GraphNode {
-    return {
-      id: note.frontmatter.id,
-      file: note.filePath,
-      type: note.frontmatter.type,
-      domains: note.frontmatter.domain,
-      entities: note.frontmatter.entities,
-      tags: note.frontmatter.tags,
-      confidence: note.frontmatter.confidence,
-      updated: note.frontmatter.updated,
-    };
-  }
-}