cognitive-core 0.1.0 → 0.2.0

package/src/memory/knowledge-bank.ts

@@ -0,0 +1,1317 @@
+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,
+    };
+  }
+}