cognitive-core 0.1.0 → 0.2.0

package/dist/memory/knowledge-bank.js

@@ -0,0 +1,1048 @@
+import { readFile, writeFile, readdir, mkdir, unlink, access } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { inferLayerFromRelation, createObservation } from '../types/knowledge.js';
+import { KnowledgeGraphManager } from './knowledge-graph.js';
+import { CoherenceChecker } from './coherence.js';
+import { parseKnowledgeNote, serializeKnowledgeNote, } from '../utils/frontmatter.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 {
+    graph;
+    memoryDir;
+    bankConfig;
+    initialized = false;
+    searchProvider = new TextSimilaritySearchProvider();
+    coherenceChecker = new CoherenceChecker();
+    // Directory paths (resolved on init)
+    observationsDir = '';
+    entitiesDir = '';
+    domainsDir = '';
+    inboxDir = '';
+    indexDir = '';
+    constructor(memoryDir, config) {
+        this.memoryDir = memoryDir;
+        this.bankConfig = config;
+        this.graph = new KnowledgeGraphManager(this.bankConfig.graph);
+    }
+    // =========================================================================
+    // Lifecycle
+    // =========================================================================
+    async init() {
+        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() {
+        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) {
+        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;
+                    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() {
+        return this.coherenceChecker;
+    }
+    /**
+     * Update an existing entity note by appending a section.
+     */
+    async updateEntity(entityId, update) {
+        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) {
+        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) {
+        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) {
+        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() {
+        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() {
+        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() {
+        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, options) {
+        await this.init();
+        const neighborNodes = this.graph.neighbors(noteId, options);
+        const matches = [];
+        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) {
+        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',
+        }));
+    }
+    // =========================================================================
+    // Stats
+    // =========================================================================
+    async getStats() {
+        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 = {};
+        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, options) {
+        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 = [];
+        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, options) {
+        await this.init();
+        const surfacingConfig = this.bankConfig.surfacing;
+        const maxNotes = options?.maxNotes ?? surfacingConfig.maxNotesPerTask;
+        const maxTokens = options?.maxTokens ?? surfacingConfig.maxTokensForKnowledge;
+        const matches = [];
+        const seenIds = new Set();
+        // 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 = { 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() {
+        await this.init();
+        let processed = 0;
+        let failed = 0;
+        let movedToObservations = 0;
+        let movedToEntities = 0;
+        let movedToDomains = 0;
+        let files;
+        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;
+                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() {
+        await this.init();
+        const { KnowledgeDefragmenter } = await import('./knowledge-defrag.js');
+        const defragmenter = new KnowledgeDefragmenter(this, this.bankConfig.defrag);
+        return defragmenter.defragment();
+    }
+    async applyExtraction(extraction) {
+        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, trajectoryId) {
+        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) {
+        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() {
+        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, options) {
+        await this.init();
+        const items = await source.load();
+        const results = [];
+        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, analysis, taskRunner) {
+        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, options) {
+        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 = [];
+        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() {
+        return this.searchProvider.name;
+    }
+    /**
+     * Replace the active search provider (strategy pattern).
+     */
+    setSearchProvider(provider) {
+        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.
+     */
+    async detectMinimem() {
+        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() {
+        return this.indexDir;
+    }
+    /**
+     * Check if defragmentation should be triggered.
+     */
+    async shouldDefragment() {
+        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.
+     */
+    async writeNote(note) {
+        // 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.
+     */
+    async scanDirectory(dir) {
+        const notes = [];
+        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.
+     */
+    async countFiles(dir) {
+        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/.
+     */
+    resolveNotePath(type, filename) {
+        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.
+     */
+    async moveInboxNote(note) {
+        const type = note.frontmatter.type;
+        const noteType = 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.
+     */
+    processRawInboxFile(content, filename) {
+        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' },
+        });
+    }
+    /**
+     * Convert a KnowledgeNote to a GraphNode.
+     */
+    /**
+     * Enforce a token budget on a list of matches.
+     * Always includes at least one match.
+     */
+    enforceTokenBudget(matches, maxTokens) {
+        const result = [];
+        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.
+     */
+    formatSingleNote(match, includeEvidence, includeLinks) {
+        const { note } = match;
+        const confidencePercent = Math.round(note.frontmatter.confidence * 100);
+        const lines = [];
+        // 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.
+     */
+    async getRelatedNotes(note) {
+        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;
+        });
+    }
+    noteToGraphNode(note) {
+        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,
+        };
+    }
+}
+//# sourceMappingURL=knowledge-bank.js.map