cognitive-core 0.2.4 → 0.3.1

package/dist/memory/knowledge-bank.js

@@ -1,15 +1,87 @@
-import { readFile, writeFile, readdir, mkdir, unlink, access } from 'node:fs/promises';
+import { readFile, writeFile, rename, readdir, mkdir, unlink, access } from 'node:fs/promises';
+import { logger } from '../utils/logger.js';
 import { join, relative } from 'node:path';
-import { inferLayerFromRelation, createObservation } from '../types/knowledge.js';
-import { KnowledgeGraphManager } from './knowledge-graph.js';
+import { createObservation, createEntityNote, inferLayerFromRelation } from '../types/knowledge.js';
 import { CoherenceChecker } from './coherence.js';
-import { parseKnowledgeNote, serializeKnowledgeNote, } from '../utils/frontmatter.js';
+import { parseKnowledgeNote, serializeKnowledgeNote } from '../utils/frontmatter.js';
 import { TextSimilaritySearchProvider } from './search-providers/text-similarity.js';
+import { EmbeddingSearchProvider } from './search-providers/embedding.js';
+import { HybridSearchProvider, } from './search-providers/hybrid.js';
+import { extractConversationFacts } from './extraction/conversation-extractor.js';
+/**
+ * Max stripped-body length for a note to count as a content-free index record.
+ * Defrag's index records carry only a one-line marker ("Entity record for X.
+ * Linked facts: N."). A content-bearing entity note — e.g. a consolidated note
+ * written by evolve() — has a real body and must stay retrievable.
+ */
+const INDEX_RECORD_BODY_MAX = 160;
+/**
+ * Max consolidated (entity-type content) notes allowed into a single retrieval
+ * window. A broad merge that matches by entity name would otherwise crowd out
+ * the precise atomic fact a single-hop question needs; capping keeps merges as
+ * supplements while aggregation/multi-hop still gets the few relevant ones.
+ */
+const MAX_CONSOLIDATED_NOTES = 2;
+/**
+ * An index-mode entity record: an `entity` note whose purpose is to anchor a
+ * set of atomic facts (via entity-layer links) rather than to carry content.
+ * Such records are excluded from retrievable content and used only as a
+ * relevance boost for their linked facts.
+ *
+ * The body gate is essential: without it, ANY entity note with an entity-layer
+ * link (including a consolidated merge with a rich body) would be treated as a
+ * content-free anchor and dropped from retrieval, discarding its content.
+ */
+function isEntityIndexRecord(note) {
+    if (note.frontmatter.type !== 'entity')
+        return false;
+    if (!note.frontmatter.links.some((l) => l.layer === 'entity'))
+        return false;
+    const body = note.body.replace(/^#\s.*(?:\n+|$)/, '').trim();
+    return body.length < INDEX_RECORD_BODY_MAX;
+}
+/** Lowercase word set for cheap lexical overlap (WS2c relevance excerpting). */
+function tokenSet(s) {
+    return new Set(s
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 2));
+}
+/**
+ * Build a query-relevant excerpt of a note body under a character budget.
+ * Multi-section notes (## headings) are ranked per section by lexical overlap
+ * with the query so the most relevant material survives truncation; otherwise
+ * falls back to head truncation. Small bodies are returned unchanged.
+ */
+function excerptForQuery(body, query, maxChars) {
+    if (body.length <= maxChars)
+        return body;
+    const sections = body.split(/\n(?=##\s)/);
+    if (sections.length <= 1)
+        return `${body.slice(0, maxChars)}…`;
+    const header = /^##\s/.test(sections[0]) ? '' : (sections.shift() ?? '');
+    const qTokens = tokenSet(query);
+    const scored = sections.map((s) => {
+        let overlap = 0;
+        for (const t of tokenSet(s))
+            if (qTokens.has(t))
+                overlap++;
+        return { s, overlap };
+    });
+    scored.sort((a, b) => b.overlap - a.overlap);
+    let out = header ? `${header.trim()}\n` : '';
+    for (const { s } of scored) {
+        if (out.length + s.length + 1 > maxChars)
+            continue;
+        out += `${s.trim()}\n`;
+    }
+    return out.trim() || `${body.slice(0, maxChars)}…`;
+}
 /**
  * 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}/
@@ -18,25 +90,28 @@ import { TextSimilaritySearchProvider } from './search-providers/text-similarity
  *       entities/       — living entity docs ({entity}.md)
  *       domains/        — domain summaries ({domain}.md)
  *     inbox/            — unorganized agent-authored notes
- *     .knowledge/       — derived index files (graph, manifest)
+ *     .knowledge/       — derived index files (manifest)
  */
 export class KnowledgeBank {
-    graph;
     memoryDir;
     bankConfig;
     initialized = false;
     searchProvider = new TextSimilaritySearchProvider();
     coherenceChecker = new CoherenceChecker();
+    /** Neural embedding provider for note retrieval (null ⇒ lexical floor). */
+    embedder = null;
+    /** True once an embedder is configured — takes precedence over minimem auto-detect. */
+    embeddingConfigured = false;
     // Directory paths (resolved on init)
     observationsDir = '';
     entitiesDir = '';
     domainsDir = '';
+    conventionsDir = '';
     inboxDir = '';
     indexDir = '';
     constructor(memoryDir, config) {
         this.memoryDir = memoryDir;
         this.bankConfig = config;
-        this.graph = new KnowledgeGraphManager(this.bankConfig.graph);
     }
     // =========================================================================
     // Lifecycle
@@ -53,6 +128,7 @@ export class KnowledgeBank {
         this.observationsDir = join(knowledgeBase, 'observations');
         this.entitiesDir = join(knowledgeBase, 'entities');
         this.domainsDir = join(knowledgeBase, 'domains');
+        this.conventionsDir = join(knowledgeBase, 'conventions');
         this.inboxDir = join(this.memoryDir, 'inbox');
         this.indexDir = join(this.memoryDir, '.knowledge');
         // Create directory structure
@@ -60,11 +136,10 @@ export class KnowledgeBank {
             mkdir(this.observationsDir, { recursive: true }),
             mkdir(this.entitiesDir, { recursive: true }),
             mkdir(this.domainsDir, { recursive: true }),
+            mkdir(this.conventionsDir, { 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();
@@ -74,7 +149,6 @@ export class KnowledgeBank {
     async close() {
         if (!this.initialized)
             return;
-        await this.graph.saveToDisk(this.indexDir);
     }
     // =========================================================================
     // Write Operations
@@ -83,10 +157,18 @@ export class KnowledgeBank {
      * 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();
+        // Assign a filePath when the caller leaves it empty (e.g. bootstrap notes)
+        if (!note.filePath) {
+            const noteType = note.frontmatter.type === 'entity'
+                ? 'entity'
+                : note.frontmatter.type === 'domain-summary'
+                    ? 'domain-summary'
+                    : 'observation';
+            note.filePath = this.resolveNotePath(noteType, `${note.frontmatter.id}.md`);
+        }
         // Run coherence check against related existing notes (if enabled)
         if (this.bankConfig.coherenceChecking !== false) {
             try {
@@ -104,7 +186,6 @@ export class KnowledgeBank {
             }
         }
         await this.writeNote(note);
-        this.graph.addNode(this.noteToGraphNode(note));
         return note.frontmatter.id;
     }
     /**
@@ -137,8 +218,6 @@ export class KnowledgeBank {
             note.frontmatter.source.trajectories.push(update.trajectoryId);
         }
         await this.writeNote(note);
-        // Update graph node
-        this.graph.addNode(this.noteToGraphNode(note));
     }
     // =========================================================================
     // Read Operations
@@ -149,11 +228,7 @@ export class KnowledgeBank {
     async getNote(id) {
         await this.init();
         // Try each directory
-        for (const dir of [
-            this.observationsDir,
-            this.entitiesDir,
-            this.domainsDir,
-        ]) {
+        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)
@@ -200,9 +275,7 @@ export class KnowledgeBank {
         await this.init();
         try {
             const files = await readdir(this.entitiesDir);
-            return files
-                .filter((f) => f.endsWith('.md'))
-                .map((f) => f.replace('.md', ''));
+            return files.filter((f) => f.endsWith('.md')).map((f) => f.replace('.md', ''));
         }
         catch {
             return [];
@@ -215,9 +288,7 @@ export class KnowledgeBank {
         await this.init();
         try {
             const files = await readdir(this.domainsDir);
-            return files
-                .filter((f) => f.endsWith('.md'))
-                .map((f) => f.replace('.md', ''));
+            return files.filter((f) => f.endsWith('.md')).map((f) => f.replace('.md', ''));
         }
         catch {
             return [];
@@ -228,48 +299,109 @@ export class KnowledgeBank {
      */
     async getAllNotes() {
         await this.init();
-        const [observations, entities, domains] = await Promise.all([
+        const [observations, entities, domains, conventions] = await Promise.all([
             this.scanDirectory(this.observationsDir),
             this.scanDirectory(this.entitiesDir),
             this.scanDirectory(this.domainsDir),
+            this.scanDirectory(this.conventionsDir),
         ]);
-        return [...observations, ...entities, ...domains];
+        return [...observations, ...entities, ...domains, ...conventions];
     }
     // =========================================================================
-    // Graph Delegation
+    // Convention Operations (PR-D3)
     // =========================================================================
     /**
-     * Get related notes via multi-layer graph traversal.
+     * Store a convention note.
+     * Uses addObservation as the underlying write path (coherence skip is safe
+     * here since conventions are user-authored, not extracted).
      */
-    async getRelated(noteId, options) {
+    async storeConvention(note) {
         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',
-                });
+        // Ensure conventions land in the conventions sub-directory
+        if (!note.filePath || !note.filePath.includes('conventions/')) {
+            note.filePath = this.resolveConventionPath(`${note.frontmatter.id}.md`);
+        }
+        await this.writeNote(note);
+        return note.frontmatter.id;
+    }
+    /**
+     * Upsert a convention by ID: if one with the same ID already exists,
+     * merge the evidence count and re-evaluate the binding threshold.
+     *
+     * Binding rules (PR-D3):
+     *   - 'instruction' type correction → binding immediately (evidenceCount=1 suffices)
+     *   - other types → binding when evidenceCount >= 2
+     *
+     * Returns the (possibly updated) note.
+     */
+    async upsertConvention(note) {
+        await this.init();
+        const existing = await this.getConventionById(note.frontmatter.id);
+        if (existing) {
+            // Merge evidence count
+            const existingEvidence = existing.frontmatter.evidenceCount ?? 1;
+            const newEvidence = note.frontmatter.evidenceCount ?? 1;
+            const mergedEvidence = existingEvidence + newEvidence;
+            existing.frontmatter.evidenceCount = mergedEvidence;
+            existing.frontmatter.updated = new Date().toISOString();
+            // Re-evaluate binding: instruction tags flip binding immediately;
+            // otherwise require >= 2 corroborating corrections.
+            const isInstruction = existing.frontmatter.tags.includes('instruction');
+            existing.frontmatter.binding = isInstruction || mergedEvidence >= 2;
+            existing.frontmatter.confidence = existing.frontmatter.binding ? 0.9 : 0.5;
+            // Merge tags from the incoming note
+            for (const tag of note.frontmatter.tags) {
+                if (!existing.frontmatter.tags.includes(tag)) {
+                    existing.frontmatter.tags.push(tag);
+                }
             }
+            await this.storeConvention(existing);
+            return existing;
         }
-        return matches.sort((a, b) => b.score - a.score);
+        await this.storeConvention(note);
+        return note;
+    }
+    /**
+     * Retrieve conventions filtered by scope and optionally by domain.
+     *
+     * Scope semantics:
+     *   - 'global' conventions are always returned regardless of requested scope.
+     *   - Other scopes are returned only when their scope matches the requested scope.
+     *
+     * Pass `repoOrDomain` to additionally filter 'repo' or 'domain' scoped conventions
+     * by a specific identifier stored in the note's domain array.
+     */
+    async getConventions(options) {
+        await this.init();
+        const all = await this.scanDirectory(this.conventionsDir);
+        return all.filter((note) => {
+            const noteScope = note.frontmatter.scope;
+            // Binding filter
+            if (options?.bindingOnly && !note.frontmatter.binding)
+                return false;
+            // No scope filter → return all
+            if (!options?.scope)
+                return true;
+            // Global conventions are always included
+            if (noteScope === 'global')
+                return true;
+            // Exact scope match required for non-global
+            if (noteScope !== options.scope)
+                return false;
+            // For repo/domain scopes, also filter by the specific identifier
+            if (options.repoOrDomain && (noteScope === 'repo' || noteScope === 'domain')) {
+                return note.frontmatter.domain.includes(options.repoOrDomain);
+            }
+            return true;
+        });
     }
     /**
-     * Get cross-system links to playbooks.
+     * Get a convention note by ID.
      */
-    async getPlaybookLinks(noteId) {
+    async getConventionById(id) {
         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',
-        }));
+        const notes = await this.scanDirectory(this.conventionsDir);
+        return notes.find((n) => n.frontmatter.id === id) ?? null;
     }
     // =========================================================================
     // Stats
@@ -282,7 +414,8 @@ export class KnowledgeBank {
             this.countFiles(this.domainsDir),
             this.countFiles(this.inboxDir),
         ]);
-        const graphStats = this.graph.getStats();
+        // convention count is available via getConventions() but not tracked in KnowledgeStats
+        // (KnowledgeStats is a shared interface — we don't widen it to avoid breaking changes)
         // Compute average confidence and domain breakdown
         const allNotes = await this.getAllNotes();
         let totalConfidence = 0;
@@ -301,7 +434,6 @@ export class KnowledgeBank {
             entityCount: entities,
             domainCount: domains,
             inboxCount: inbox,
-            graph: graphStats,
             avgConfidence: allNotes.length > 0 ? totalConfidence / allNotes.length : 0,
             staleCount,
             domainBreakdown,
@@ -325,8 +457,14 @@ export class KnowledgeBank {
         }
         // Exclude stale notes
         candidates = candidates.filter((note) => !note.frontmatter.tags.includes('stale'));
+        // Exclude index-mode entity records: they are content-free anchors (name +
+        // links to atomic facts) and must never be surfaced as retrievable content.
+        candidates = candidates.filter((note) => !isEntityIndexRecord(note));
         // Delegate scoring to the search provider
-        const results = await this.searchProvider.search(query, candidates, { maxResults });
+        const results = await this.searchProvider.search(query, candidates, {
+            maxResults,
+            domains: options?.domains,
+        });
         // Build a lookup for fast note retrieval by ID
         const noteById = new Map(candidates.map((n) => [n.frontmatter.id, n]));
         const matches = [];
@@ -343,82 +481,149 @@ export class KnowledgeBank {
         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
+     * Get relevant knowledge for a task.
+     *
+     * Retrieval is a single fused ranking rather than fixed tiers:
+     * - Domain summaries (when a domain is given) are pinned on top as high-level
+     *   context.
+     * - A wide pool of atomic fact/observation notes is retrieved semantically.
+     * - Entity records that match the query (index mode) do NOT inject content;
+     *   instead they add a score BOOST to their linked atomic facts, lifting
+     *   entity-relevant facts within the pool (see DESIGN WS2a/WS2b).
+     * - Legacy content-mode entity notes are still surfaced as `entity` matches.
+     * All non-domain candidates then compete on a single fused score.
      */
     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 boostWeight = surfacingConfig.entityBoostWeight ?? 0.15;
+        // Domain matches are pinned on top.
+        const domainMatches = [];
         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)) {
+            if (domainSummary) {
                 seenIds.add(domainSummary.frontmatter.id);
-                matches.push({
-                    note: domainSummary,
-                    score: 1.0,
-                    matchType: 'domain',
-                });
+                domainMatches.push({ note: domainSummary, score: 1.0, matchType: 'domain' });
             }
         }
-        // Tier 2: Entity match
+        // Entity pass: gather per-fact boosts (index records) and legacy content
+        // entity notes to surface directly.
+        //
+        // The boost is frequency-weighted (IDF-style): an entity linked to many facts
+        // (e.g. the conversation's main subject) is non-discriminative, so a flat
+        // boost would flood the pool with that entity's generic facts and drown the
+        // semantically-relevant ones. We scale the boost down by link count so a rare
+        // entity lifts its facts strongly while a ubiquitous one barely moves them.
+        const boostByFact = new Map();
+        const entityContentMatches = [];
         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',
-                        });
+                if (!(taskLower.includes(entitySlug) || taskLower.includes(entityWords)))
+                    continue;
+                const entityNote = await this.getEntity(entitySlug);
+                if (!entityNote)
+                    continue;
+                if (isEntityIndexRecord(entityNote)) {
+                    const links = entityNote.frontmatter.links.filter((l) => l.layer === 'entity');
+                    // n=1 → /1.58, n=8 → /3.3, n=100 → /6.6: dominant entities fade out.
+                    const w = boostWeight / Math.log2(links.length + 2);
+                    for (const l of links) {
+                        boostByFact.set(l.target, Math.max(boostByFact.get(l.target) ?? 0, w));
                     }
                 }
+                else if (!seenIds.has(entityNote.frontmatter.id)) {
+                    entityContentMatches.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))
+        // Semantic pool — retrieve wider than maxNotes so boosted facts can be
+        // lifted into the final window.
+        const poolSize = Math.max(maxNotes * 3, maxNotes + boostByFact.size, 12);
+        const searchResults = await this.search(task.description, {
+            domains: task.domain ? [task.domain] : undefined,
+            maxResults: poolSize,
+        });
+        const fused = searchResults.map((r) => {
+            const boost = boostByFact.get(r.note.frontmatter.id);
+            return boost ? { ...r, score: r.score + boost, matchType: 'entity' } : r;
+        });
+        // Combine non-domain candidates and rank by single fused score.
+        const rest = [];
+        const restSeen = new Set(seenIds);
+        for (const m of [...entityContentMatches, ...fused]) {
+            const id = m.note.frontmatter.id;
+            if (restSeen.has(id))
+                continue;
+            restSeen.add(id);
+            rest.push(m);
+        }
+        rest.sort((a, b) => b.score - a.score);
+        // 1-hop link expansion: pull in neighbors connected to the top matches by
+        // EXPLICIT non-index edges (the causal/temporal/semantic links written by
+        // evolve()), so a matched fact also surfaces the facts it was linked to —
+        // the pre-computed structure a multi-hop question needs. No-op for banks
+        // without such links (plain extraction/defrag only create entity-layer
+        // index links, which are skipped here since they are already handled by the
+        // boost pass above).
+        const expanded = await this.expandLinkedNeighbors(rest, restSeen);
+        if (expanded.length > 0) {
+            rest.push(...expanded);
+            rest.sort((a, b) => b.score - a.score);
+        }
+        // Fill the window from the ranked list, but cap consolidated (entity-type)
+        // notes so they supplement rather than evict atomic facts.
+        const budget = Math.max(0, maxNotes - domainMatches.length);
+        const selected = [];
+        let consolidatedCount = 0;
+        for (const m of rest) {
+            if (selected.length >= budget)
+                break;
+            if (m.note.frontmatter.type === 'entity') {
+                if (consolidatedCount >= MAX_CONSOLIDATED_NOTES)
                     continue;
-                seenIds.add(result.note.frontmatter.id);
-                matches.push(result);
-                if (matches.length >= maxNotes)
-                    break;
+                consolidatedCount++;
             }
+            selected.push(m);
         }
-        // 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);
+        const combined = [...domainMatches, ...selected];
+        return this.enforceTokenBudget(combined, maxTokens, task.description);
     }
     /**
-     * Process inbox files: classify, move to correct directory, add to graph.
+     * Gather the linked neighbors of the top-ranked matches (1 hop), following
+     * only explicit non-index edges. Each neighbor is scored as a discount of the
+     * seed that reached it, so it competes for a slot without outranking direct
+     * matches. Returns notes not already present in `seen`.
+     */
+    async expandLinkedNeighbors(ranked, seen) {
+        const EXPAND_SEEDS = 8;
+        const NEIGHBOR_DISCOUNT = 0.6;
+        const additions = [];
+        const added = new Set();
+        for (const seed of ranked.slice(0, EXPAND_SEEDS)) {
+            for (const link of seed.note.frontmatter.links) {
+                // Entity-layer (index) links are handled by the boost pass; skip them.
+                if (link.layer === 'entity')
+                    continue;
+                const target = link.target;
+                if (seen.has(target) || added.has(target))
+                    continue;
+                const note = await this.getNote(target);
+                if (!note || isEntityIndexRecord(note) || note.frontmatter.tags.includes('stale'))
+                    continue;
+                added.add(target);
+                additions.push({ note, score: seed.score * NEIGHBOR_DISCOUNT, matchType: 'graph' });
+            }
+        }
+        return additions;
+    }
+    /**
+     * Process inbox files: classify, move to correct directory.
      * Files with valid frontmatter are classified by type field.
      * Files without valid frontmatter get heuristic classification as observations.
      */
@@ -459,8 +664,6 @@ export class KnowledgeBank {
                     movedToEntities++;
                 else if (result === 'domain-summary')
                     movedToDomains++;
-                // Add to graph
-                this.graph.addNode(this.noteToGraphNode(note));
                 // Remove from inbox
                 await unlink(absPath);
                 processed++;
@@ -480,6 +683,107 @@ export class KnowledgeBank {
         const defragmenter = new KnowledgeDefragmenter(this, this.bankConfig.defrag);
         return defragmenter.defragment();
     }
+    /**
+     * Agentic memory evolution. Given an `evolver` (an agent- or LLM-backed
+     * function; see `createAgenticMemoryEvolver` / `createLlmMemoryEvolver`), take
+     * a snapshot of the bank, let the evolver propose a plan, then apply it via
+     * existing primitives:
+     * - `supersede` → recordContradiction (down-weight stale, point new note)
+     * - `merge`     → write a consolidated entity note linking the source facts
+     * - `link`      → add an explicit edge (esp. entity↔entity) for multi-hop
+     *
+     * The bank never learns HOW the plan was produced — the evolver is a plain
+     * function, keeping the memory layer free of the agent/workspace runtime.
+     */
+    async evolve(evolver) {
+        await this.init();
+        const notes = await this.getAllNotes();
+        const [entities, domains] = await Promise.all([this.listEntities(), this.listDomains()]);
+        const plan = await evolver({ notes, domains, entities });
+        return this.applyEvolutionPlan(plan);
+    }
+    /** Apply a {@link MemoryEvolutionPlan}. Referenced-but-missing note ids are skipped. */
+    async applyEvolutionPlan(plan) {
+        await this.init();
+        const result = { superseded: 0, merged: 0, linked: 0, skipped: 0 };
+        for (const action of plan.actions) {
+            switch (action.type) {
+                case 'supersede': {
+                    const superseding = await this.getNote(action.supersededById);
+                    const stale = await this.getNote(action.staleId);
+                    if (!superseding || !stale) {
+                        result.skipped++;
+                        break;
+                    }
+                    await this.recordContradiction({
+                        existingNoteId: action.staleId,
+                        newObservation: superseding,
+                        conflictDescription: action.reason || 'evolver: superseded',
+                        resolution: 'supersede',
+                    });
+                    result.superseded++;
+                    break;
+                }
+                case 'merge': {
+                    const sources = (await Promise.all(action.sourceIds.map((id) => this.getNote(id)))).filter((n) => n !== null);
+                    if (sources.length === 0) {
+                        result.skipped++;
+                        break;
+                    }
+                    const domain = action.domain ?? [
+                        ...new Set(sources.flatMap((n) => n.frontmatter.domain)),
+                    ];
+                    const entityNote = createEntityNote({
+                        entityName: action.entityName,
+                        body: action.body,
+                        domain,
+                        tags: ['evolved', 'consolidated'],
+                        source: { origin: 'agent-authored' },
+                        links: sources.map((n) => ({
+                            target: n.frontmatter.id,
+                            relation: 'part-of',
+                            layer: 'entity',
+                        })),
+                    });
+                    await this.addObservation(entityNote);
+                    result.merged++;
+                    break;
+                }
+                case 'link': {
+                    const applied = await this.addLink(action.from, action.to, action.relation);
+                    if (applied)
+                        result.linked++;
+                    else
+                        result.skipped++;
+                    break;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Add an explicit graph edge from one note to another (idempotent). Returns
+     * false if the source note does not exist. Entity↔entity edges added here are
+     * what let a single retrieval surface a pre-linked structure for multi-hop
+     * questions instead of forcing the answerer to re-derive the join.
+     */
+    async addLink(fromId, toId, relation) {
+        await this.init();
+        const from = await this.getNote(fromId);
+        if (!from)
+            return false;
+        const exists = from.frontmatter.links.some((l) => l.target === toId && l.relation === relation);
+        if (!exists) {
+            from.frontmatter.links.push({
+                target: toId,
+                relation,
+                layer: inferLayerFromRelation(relation),
+            });
+            from.frontmatter.updated = new Date().toISOString();
+            await this.writeNote(from);
+        }
+        return true;
+    }
     async applyExtraction(extraction) {
         await this.init();
         // 1. Add new observations
@@ -499,34 +803,22 @@ export class KnowledgeBank {
         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',
-            });
-        }
+    }
+    /**
+     * First-class ADD-only conversational extraction (see DESIGN WS3).
+     *
+     * Extracts atomic, coreference-resolved, dated, entity-tagged facts from
+     * dialogue turns and writes them as observations. The LLM is injected as a
+     * `complete` callback so the memory layer carries no model dependency; without
+     * one a deterministic heuristic is used. Returns the extracted knowledge that
+     * was applied.
+     */
+    async extractFromConversation(input, complete) {
+        await this.init();
+        const knownEntities = input.knownEntities ?? (await this.listEntities());
+        const extraction = await extractConversationFacts({ ...input, knownEntities }, complete);
+        await this.applyExtraction(extraction);
+        return extraction;
     }
     /**
      * Reinforce a knowledge note with new evidence from a trajectory.
@@ -539,8 +831,7 @@ export class KnowledgeBank {
             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;
+        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 = [];
@@ -551,7 +842,6 @@ export class KnowledgeBank {
         // Update timestamp
         note.frontmatter.updated = new Date().toISOString();
         await this.writeNote(note);
-        this.graph.addNode(this.noteToGraphNode(note));
     }
     async recordContradiction(contradiction) {
         await this.init();
@@ -561,17 +851,6 @@ export class KnowledgeBank {
         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') {
@@ -579,21 +858,9 @@ export class KnowledgeBank {
             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
@@ -601,13 +868,11 @@ export class KnowledgeBank {
             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') {
@@ -616,14 +881,12 @@ export class KnowledgeBank {
                 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));
             }
         }
     }
@@ -670,7 +933,6 @@ export class KnowledgeBank {
             }
             // Write to disk without updating the 'updated' timestamp
             await this.writeNote(note);
-            this.graph.addNode(this.noteToGraphNode(note));
             decayed++;
         }
         return { decayed, newlyStale, alreadyStale };
@@ -691,40 +953,39 @@ export class KnowledgeBank {
             if (!analysis && options?.analyzer) {
                 analysis = await options.analyzer.analyze(item.trajectory);
             }
-            const extraction = await this.extractFromTrajectory(item.trajectory, analysis, options?.taskRunner);
+            const extraction = await this.extractFromTrajectory(item.trajectory, analysis, options?.agenticExtractor);
             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.
+     * Uses the agentic extractor if provided (wire one up with the workspace
+     * layer's `createAgenticKnowledgeExtractor`), otherwise falls back to the
+     * heuristic extractor. Applies the extraction to the knowledge bank.
      */
-    async extractFromTrajectory(trajectory, analysis, taskRunner) {
+    async extractFromTrajectory(trajectory, analysis, agenticExtractor) {
         await this.init();
         // Compute analysis if not provided
         const { createAnalyzer } = await import('../learning/analyzer.js');
-        const resolvedAnalysis = analysis ?? await createAnalyzer('simple').analyze(trajectory);
+        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 agentic extraction if an extractor is available
+        if (agenticExtractor) {
             try {
-                const { knowledgeExtractionTemplate } = await import('../workspace/templates/knowledge-extraction.js');
-                const result = await taskRunner.run(knowledgeExtractionTemplate, {
+                const extraction = await agenticExtractor({
                     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);
+                logger.error('Agentic knowledge extraction failed, falling back to heuristic:', error instanceof Error ? error.message : error);
             }
         }
         // Heuristic fallback
@@ -781,6 +1042,44 @@ export class KnowledgeBank {
     setSearchProvider(provider) {
         this.searchProvider = provider;
     }
+    /**
+     * Attach a neural embedding provider. When set, knowledge-note retrieval
+     * defaults to a **hybrid** scorer ({@link HybridSearchProvider}: lexical
+     * TextSimilarity + embedding cosine, fused by balanced linear w=0.5 — the
+     * cross-benchmark best); pass `null` to revert to the lexical TextSimilarity
+     * floor.
+     *
+     * Why hybrid by default: on real memory-QA retrieval (LoCoMo) the hybrid beats
+     * BOTH pure embedding and pure lexical overall (+9pp over the best single
+     * channel) — embedding alone actually *lost* to lexical there because most
+     * questions share surface tokens with their evidence. See
+     * docs/DESIGN-memory-qa-benchmarks.md §4a. Set `mode: 'embedding'` for the
+     * pure-cosine path (e.g. paraphrase-heavy corpora; see amem §6.6).
+     *
+     * Precedence: an explicitly configured embedder wins over minimem
+     * auto-detection (see {@link detectMinimem}).
+     */
+    setEmbeddingProvider(provider, options) {
+        this.embedder = provider;
+        this.embeddingConfigured = provider !== null;
+        if (!provider) {
+            this.searchProvider = new TextSimilaritySearchProvider();
+            return;
+        }
+        const embedding = new EmbeddingSearchProvider(provider, { minScore: options?.minScore });
+        // Hybrid weight auto-tunes to the encoder (bge→0.2, all-MiniLM→0.5; §4f).
+        this.searchProvider =
+            (options?.mode ?? 'hybrid') === 'embedding'
+                ? embedding
+                : new HybridSearchProvider(new TextSimilaritySearchProvider(), embedding, {
+                    ...options?.hybrid,
+                    lexicalWeight: options?.hybrid?.lexicalWeight ?? provider.recommendedLexicalWeight ?? 0.5,
+                });
+    }
+    /** The attached embedding provider, if any. */
+    getEmbeddingProvider() {
+        return this.embedder;
+    }
     // =========================================================================
     // Internal Helpers
     // =========================================================================
@@ -795,6 +1094,9 @@ export class KnowledgeBank {
      * Falls back to TextSimilaritySearchProvider on any failure.
      */
     async detectMinimem() {
+        // An explicitly configured embedding provider takes precedence over minimem.
+        if (this.embeddingConfigured)
+            return;
         try {
             // Check for minimem markers
             const minimemDir = join(this.memoryDir, '.minimem');
@@ -861,7 +1163,14 @@ export class KnowledgeBank {
         const dir = absPath.substring(0, absPath.lastIndexOf('/'));
         await mkdir(dir, { recursive: true });
         const content = serializeKnowledgeNote(note);
-        await writeFile(absPath, content, 'utf-8');
+        // Atomic write: same-dir temp file + rename (atomic within a filesystem) so a
+        // crash mid-write never leaves a truncated note. Mirrors the procedural
+        // SKILL.md writer (procedural-skill.ts). The `.tmp` temp is hidden and skipped
+        // by scanDirectory (which only reads `.md`).
+        const fileName = absPath.substring(absPath.lastIndexOf('/') + 1);
+        const tmpPath = join(dir, `.${fileName}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+        await writeFile(tmpPath, content, 'utf-8');
+        await rename(tmpPath, absPath);
     }
     /**
      * Scan a directory for .md files and parse them as KnowledgeNotes.
@@ -909,9 +1218,7 @@ export class KnowledgeBank {
      * When minimemAware, paths are nested under memory/knowledge/ instead of knowledge/.
      */
     resolveNotePath(type, filename) {
-        const knowledgePrefix = this.bankConfig.minimemAware
-            ? 'memory/knowledge'
-            : 'knowledge';
+        const knowledgePrefix = this.bankConfig.minimemAware ? 'memory/knowledge' : 'knowledge';
         if (type === 'entity') {
             return `${knowledgePrefix}/entities/${filename}`;
         }
@@ -920,12 +1227,20 @@ export class KnowledgeBank {
         }
         return `${knowledgePrefix}/observations/${filename}`;
     }
+    /**
+     * Resolve the relative path for a convention note filename.
+     */
+    resolveConventionPath(filename) {
+        const knowledgePrefix = this.bankConfig.minimemAware ? 'memory/knowledge' : 'knowledge';
+        return `${knowledgePrefix}/conventions/${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;
+        // convention notes are not moved through inbox — they go via storeConvention
         const noteType = type === 'entity' ? 'entity' : type === 'domain-summary' ? 'domain-summary' : 'observation';
         const filename = `${note.frontmatter.id}.md`;
         note.filePath = this.resolveNotePath(noteType, filename);
@@ -950,22 +1265,30 @@ export class KnowledgeBank {
             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) {
+    enforceTokenBudget(matches, maxTokens, query) {
         const result = [];
         let usedTokens = 0;
         for (const match of matches) {
-            const noteTokens = Math.ceil(match.note.body.length / 4);
+            let body = match.note.body;
+            // Relevance-aware per-note excerpting: when a single note would consume a
+            // large share of the budget, keep the query-relevant sections rather than
+            // dropping the note or blindly head-truncating (WS2c). Only applies to
+            // oversized multi-section notes; atomic facts pass through untouched.
+            if (query) {
+                const perNoteCharBudget = Math.max(600, Math.floor((maxTokens * 4) / 2));
+                if (body.length > perNoteCharBudget) {
+                    body = excerptForQuery(body, query, perNoteCharBudget);
+                }
+            }
+            const noteTokens = Math.ceil(body.length / 4);
             if (usedTokens + noteTokens > maxTokens && result.length > 0) {
                 break;
             }
-            result.push(match);
+            result.push(body === match.note.body ? match : { ...match, note: { ...match.note, body } });
             usedTokens += noteTokens;
         }
         return result;
@@ -1003,7 +1326,7 @@ export class KnowledgeBank {
             const trajectoryIds = note.frontmatter.source.trajectories.slice(0, 3);
             lines.push(`\n*Evidence: ${trajectoryIds.join(', ')}*`);
         }
-        // Graph links
+        // Frontmatter links
         if (includeLinks && note.frontmatter.links.length > 0) {
             const linkSummary = note.frontmatter.links
                 .slice(0, 3)
@@ -1032,17 +1355,5 @@ export class KnowledgeBank {
             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