@feelingmindful/thinking-graph 1.15.2 → 1.20.0

package/dist/storage/jsonl.d.ts

@@ -1,5 +1,6 @@
-import type { Node, Edge, Session, SkillRegistryEntry } from '../engine/types.js';
+import type { Node, Edge, Session, SkillRegistryEntry, ScoredNode, NodeType } from '../engine/types.js';
 import { InMemoryAdapter } from './memory.js';
+import type { HybridSearchOpts } from './adapter.js';
 export interface JSONLAdapterOpts {
     dir: string;
 }
@@ -10,12 +11,40 @@ export declare class JSONLAdapter extends InMemoryAdapter {
     private readonly skillsPath;
     private readonly embeddingsPath;
     private readonly vectorIndex;
+    private embedQueue;
+    private draining;
+    private drainPromise;
+    private readonly embedGen;
     constructor(opts: JSONLAdapterOpts);
     initialize(): Promise<void>;
     close(): Promise<void>;
+    /** Claim the next embed generation for an id (call at write time). */
+    private claimGen;
+    private embedAndStore;
+    private enqueueEmbed;
+    private startDrain;
+    private drainEmbedQueue;
+    /** Await all pending background embeddings (tests + graceful shutdown). */
+    flushEmbeds(): Promise<void>;
+    /**
+     * Rewrite nodes.jsonl from the in-memory survivors when append churn (from
+     * updateNode/reinforcement) has bloated it well past the live node count.
+     * Last-line-wins reload makes the dropped lines redundant; this just reclaims
+     * the space and keeps startup replay bounded.
+     */
+    private compactNodesIfBloated;
     private maybeRunSqliteMigration;
     insertNode(node: Node): Promise<void>;
+    updateNode(id: string, fields: Partial<Node>): Promise<void>;
+    findNearest(content: string, opts: {
+        type: NodeType;
+        projectId?: string;
+    }): Promise<{
+        id: string;
+        score: number;
+    } | null>;
     searchContent(query: string): Promise<Node[]>;
+    searchHybrid(opts: HybridSearchOpts): Promise<ScoredNode[]>;
     insertEdge(edge: Edge): Promise<boolean>;
     insertSession(session: Session): Promise<void>;
     updateSession(id: string, fields: Partial<Session>): Promise<void>;

package/dist/storage/jsonl.js

@@ -1,9 +1,37 @@
-import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
+import { readFileSync, appendFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { InMemoryAdapter } from './memory.js';
 import { embedText } from './embedding.js';
+import { fuseHybrid } from '../engine/fusion.js';
+import { tokenize } from '../engine/dedup.js';
+import { config } from '../config.js';
 import { VectorIndex } from './vector-index.js';
 import { migrateSqliteToJsonl } from './migrate-sqlite.js';
+// Hybrid recall tuning. Dense (semantic) is weighted above lexical so that
+// semantically-related nodes with no shared tokens still surface; lexical keeps
+// exact-term matches competitive. Channel weights are env-overridable via
+// config. DENSE_TOP_K caps the number of dense candidates kept (the cosine scan
+// itself is O(N) over the filtered set). DENSE_MIN_COSINE drops near-orthogonal
+// candidates so unrelated nodes are not pulled in (calibrated for bge-small).
+const DENSE_TOP_K = 50;
+const DENSE_MIN_COSINE = 0.25;
+const DENSE_WEIGHT = config.denseWeight;
+const LEXICAL_WEIGHT = config.lexicalWeight;
+// updateNode (used by node reinforcement on every duplicate learn) appends a new
+// line per write, so a hot-duplicate node accumulates dead lines. On reload, if
+// nodes.jsonl has grown well beyond the live node count, rewrite it from the
+// in-memory survivors to bound both disk size and replay cost.
+const COMPACTION_MIN_LINES = 200;
+const COMPACTION_FACTOR = 3;
+// Async embedding (opt-in). When THINKING_GRAPH_ASYNC_EMBED=true, insertNode
+// returns right after the durable JSONL append and embeds in the background, so
+// a burst of writes is not blocked on model inference. Any vector missing after
+// a crash is re-embedded on the next initialize() (self-healing). Default off
+// preserves synchronous embed-on-write (and keeps read-your-writes semantics).
+const ASYNC_EMBED = process.env.THINKING_GRAPH_ASYNC_EMBED === 'true';
+// When embeddings are disabled, embedText always returns null, so there is
+// nothing to defer or self-heal.
+const EMBEDDINGS_ENABLED = process.env.THINKING_GRAPH_EMBEDDINGS !== 'false';
 export class JSONLAdapter extends InMemoryAdapter {
     nodesPath;
     edgesPath;
@@ -11,6 +39,12 @@ export class JSONLAdapter extends InMemoryAdapter {
     skillsPath;
     embeddingsPath;
     vectorIndex = new VectorIndex();
+    embedQueue = [];
+    draining = false;
+    drainPromise = null;
+    // Per-id embed generation, claimed at write time. The latest write for an id
+    // wins, so a stale deferred embed can't clobber a newer inline updateNode.
+    embedGen = new Map();
     constructor(opts) {
         super();
         this.nodesPath = join(opts.dir, 'nodes.jsonl');
@@ -22,9 +56,12 @@ export class JSONLAdapter extends InMemoryAdapter {
     async initialize() {
         mkdirSync(join(this.nodesPath, '..'), { recursive: true });
         await this.maybeRunSqliteMigration();
+        let rawNodeLines = 0;
         for (const line of readLines(this.nodesPath)) {
             await super.insertNode(JSON.parse(line));
+            rawNodeLines++;
         }
+        await this.compactNodesIfBloated(rawNodeLines);
         for (const line of readLines(this.edgesPath)) {
             await super.insertEdge(JSON.parse(line));
         }
@@ -47,8 +84,100 @@ export class JSONLAdapter extends InMemoryAdapter {
             await super.insertSkill(sk);
         }
         this.vectorIndex.load(this.embeddingsPath);
+        // Self-heal: re-embed any node whose vector never landed (e.g. a crash
+        // before the async queue drained). No-op in sync mode / fully-embedded
+        // stores, and skipped entirely when embeddings are disabled (nothing to do).
+        if (ASYNC_EMBED && EMBEDDINGS_ENABLED) {
+            const all = (await this.queryNodes({ limit: Number.MAX_SAFE_INTEGER })).items;
+            for (const n of all) {
+                if (!this.vectorIndex.has(n.id))
+                    this.enqueueEmbed(n.id, n.content);
+            }
+        }
+    }
+    async close() {
+        await this.flushEmbeds();
+    }
+    // ─── Embedding (sync inline, or async background queue) ────────────────
+    /** Claim the next embed generation for an id (call at write time). */
+    claimGen(id) {
+        const gen = (this.embedGen.get(id) ?? 0) + 1;
+        this.embedGen.set(id, gen);
+        return gen;
+    }
+    async embedAndStore(id, content, gen) {
+        const vec = await embedText(content);
+        // Only write if this is still the latest write for the id — a stale deferred
+        // embed must not clobber a newer inline updateNode re-embed.
+        if (vec && this.embedGen.get(id) === gen) {
+            this.vectorIndex.append(this.embeddingsPath, id, vec);
+        }
+    }
+    enqueueEmbed(id, content) {
+        // Claim the generation now (write order), not when the drain later runs.
+        this.embedQueue.push({ id, content, gen: this.claimGen(id) });
+        this.startDrain();
+    }
+    startDrain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        this.drainPromise = this.drainEmbedQueue().finally(() => {
+            this.draining = false;
+            // Restart if anything was enqueued during the drain or in the tiny window
+            // before this handler ran — otherwise the item would sit undrained and
+            // flushEmbeds() could spin. The finally body is synchronous, so this
+            // check and the enqueue cannot interleave.
+            if (this.embedQueue.length > 0)
+                this.startDrain();
+        });
+    }
+    async drainEmbedQueue() {
+        // Take the current batch by swapping the array (O(1)) instead of shift()
+        // (O(n) each). Items enqueued during the batch land in the fresh array and
+        // are picked up by the next loop iteration.
+        while (this.embedQueue.length > 0) {
+            const batch = this.embedQueue;
+            this.embedQueue = [];
+            for (const { id, content, gen } of batch) {
+                // Skip if a newer write already superseded this one (generation moved on).
+                if (this.embedGen.get(id) !== gen)
+                    continue;
+                // Never let a single failed embed reject the un-awaited drain promise
+                // (would surface as an unhandledRejection) or abort the rest of the batch.
+                try {
+                    await this.embedAndStore(id, content, gen);
+                }
+                catch (err) {
+                    console.error('[thinking-graph] background embed failed:', err);
+                }
+            }
+        }
+    }
+    /** Await all pending background embeddings (tests + graceful shutdown). */
+    async flushEmbeds() {
+        while (this.draining || this.embedQueue.length > 0) {
+            if (this.drainPromise)
+                await this.drainPromise;
+            else
+                await Promise.resolve();
+        }
+    }
+    /**
+     * Rewrite nodes.jsonl from the in-memory survivors when append churn (from
+     * updateNode/reinforcement) has bloated it well past the live node count.
+     * Last-line-wins reload makes the dropped lines redundant; this just reclaims
+     * the space and keeps startup replay bounded.
+     */
+    async compactNodesIfBloated(rawLineCount) {
+        if (rawLineCount <= COMPACTION_MIN_LINES)
+            return;
+        const nodes = (await this.queryNodes({ limit: Number.MAX_SAFE_INTEGER })).items;
+        if (rawLineCount <= COMPACTION_FACTOR * Math.max(1, nodes.length))
+            return;
+        const body = nodes.map(n => JSON.stringify(n)).join('\n');
+        writeFileSync(this.nodesPath, body ? body + '\n' : '', 'utf-8');
     }
-    async close() { }
     async maybeRunSqliteMigration() {
         const dbPath = process.env.THINKING_GRAPH_PROJECT_DB;
         if (!dbPath)
@@ -78,9 +207,41 @@ export class JSONLAdapter extends InMemoryAdapter {
     async insertNode(node) {
         await super.insertNode(node);
         appendLine(this.nodesPath, node);
-        const vec = await embedText(node.content);
-        if (vec)
-            this.vectorIndex.append(this.embeddingsPath, node.id, vec);
+        // Durable write is done; embed inline (default) or defer to the background
+        // queue so the write returns without waiting on model inference. Nothing to
+        // do when embeddings are disabled.
+        if (!EMBEDDINGS_ENABLED)
+            return;
+        if (ASYNC_EMBED)
+            this.enqueueEmbed(node.id, node.content);
+        else
+            await this.embedAndStore(node.id, node.content, this.claimGen(node.id));
+    }
+    async updateNode(id, fields) {
+        await super.updateNode(id, fields);
+        // Persist the new version; on reload the last line for an id wins.
+        const updated = await super.getNode(id);
+        if (!updated)
+            return;
+        appendLine(this.nodesPath, updated);
+        // Re-embed when content changed so the vector index does not go stale for
+        // findNearest / hybrid recall. (Reinforcement updates metadata only, so this
+        // is skipped on the hot duplicate-learn path.) Kept inline even in async mode
+        // — content updates are rare, and an inline write wins the drain's has() skip.
+        if (fields.content !== undefined && EMBEDDINGS_ENABLED) {
+            await this.embedAndStore(id, updated.content, this.claimGen(id));
+        }
+    }
+    async findNearest(content, opts) {
+        const vec = await embedText(content);
+        if (!vec)
+            return null;
+        const candidates = this.filterNodes({ type: opts.type, projectId: opts.projectId });
+        if (candidates.length === 0)
+            return null;
+        const allow = new Set(candidates.map(n => n.id));
+        const [top] = this.vectorIndex.search(vec, 1, allow);
+        return top ? { id: top.id, score: top.score } : null;
     }
     async searchContent(query) {
         const vec = await embedText(query);
@@ -97,6 +258,36 @@ export class JSONLAdapter extends InMemoryAdapter {
         }
         return nodes;
     }
+    async searchHybrid(opts) {
+        const { nodes, lexical } = await this.lexicalCandidates(opts);
+        if (nodes.size === 0)
+            return [];
+        const lexicalOnly = () => Promise.resolve(fuseHybrid({ nodes, channels: [{ scores: lexical, weight: 1 }] }));
+        // A query that tokenizes to nothing (punctuation/whitespace only) has no
+        // lexical or semantic intent — skip the embed call and the dense channel.
+        if (tokenize(opts.query).length === 0)
+            return lexicalOnly();
+        const qVec = await embedText(opts.query);
+        if (!qVec) {
+            // Embeddings disabled or model failed to load: degrade to lexical-only.
+            // (A cold-but-loadable model blocks until ready, then returns a vector.)
+            return lexicalOnly();
+        }
+        // Filter BEFORE ranking (allow-set) so a scoped recall sees the top-K of
+        // in-filter survivors, not the global top-K intersected with the filter.
+        const dense = new Map();
+        for (const m of this.vectorIndex.search(qVec, DENSE_TOP_K, new Set(nodes.keys()))) {
+            if (m.score >= DENSE_MIN_COSINE)
+                dense.set(m.id, m.score);
+        }
+        return fuseHybrid({
+            nodes,
+            channels: [
+                { scores: dense, weight: DENSE_WEIGHT },
+                { scores: lexical, weight: LEXICAL_WEIGHT },
+            ],
+        });
+    }
     // ─── Edges ─────────────────────────────────────────────
     async insertEdge(edge) {
         const created = await super.insertEdge(edge);

package/dist/storage/memory.d.ts

@@ -1,5 +1,5 @@
-import type { Node, Edge, Session, SkillRegistryEntry, NodeQuery, PaginatedResult, EdgeType, ExportOpts, GraphExport, GraphStats } from '../engine/types.js';
-import type { StorageAdapter } from './adapter.js';
+import type { Node, Edge, Session, SkillRegistryEntry, NodeQuery, PaginatedResult, EdgeType, ScoredNode, ExportOpts, GraphExport, GraphStats } from '../engine/types.js';
+import type { StorageAdapter, HybridSearchOpts } from './adapter.js';
 export declare class InMemoryAdapter implements StorageAdapter {
     private nodes;
     private edges;
@@ -8,9 +8,22 @@ export declare class InMemoryAdapter implements StorageAdapter {
     initialize(): Promise<void>;
     close(): Promise<void>;
     insertNode(node: Node): Promise<void>;
+    updateNode(id: string, fields: Partial<Node>): Promise<void>;
     getNode(id: string): Promise<Node | null>;
+    /** Apply attribute + substring filters without sorting or paginating. */
+    protected filterNodes(query: NodeQuery): Node[];
     queryNodes(query: NodeQuery): Promise<PaginatedResult<Node>>;
     searchContent(text: string, limit?: number): Promise<Node[]>;
+    /**
+     * Gather attribute-filtered candidates plus a lexical (token-coverage) score
+     * per node. Shared by the in-memory lexical-only hybrid and the JSONL
+     * dense+lexical hybrid (which extends this class and adds a vector channel).
+     */
+    protected lexicalCandidates(opts: HybridSearchOpts): Promise<{
+        nodes: Map<string, Node>;
+        lexical: Map<string, number>;
+    }>;
+    searchHybrid(opts: HybridSearchOpts): Promise<ScoredNode[]>;
     insertEdge(edge: Edge): Promise<boolean>;
     getEdgesFrom(nodeId: string, type?: EdgeType): Promise<Edge[]>;
     getEdgesTo(nodeId: string, type?: EdgeType): Promise<Edge[]>;

package/dist/storage/memory.js

@@ -1,3 +1,10 @@
+import { lexicalScoreTokens, fuseHybrid } from '../engine/fusion.js';
+import { tokenize } from '../engine/dedup.js';
+// Score for a raw-substring-only match (no exact token overlap). Keeps the
+// hybrid lexical channel a strict superset of the legacy substring filter, so a
+// subword query like "auth" still surfaces "authentication" nodes. Ranked below
+// any genuine token-coverage match.
+const SUBSTRING_FLOOR = 0.5;
 export class InMemoryAdapter {
     nodes = new Map();
     edges = new Map();
@@ -9,10 +16,17 @@ export class InMemoryAdapter {
     async insertNode(node) {
         this.nodes.set(node.id, { ...node });
     }
+    async updateNode(id, fields) {
+        const node = this.nodes.get(id);
+        if (node) {
+            this.nodes.set(id, { ...node, ...fields, id: node.id });
+        }
+    }
     async getNode(id) {
         return this.nodes.get(id) ?? null;
     }
-    async queryNodes(query) {
+    /** Apply attribute + substring filters without sorting or paginating. */
+    filterNodes(query) {
         let results = [...this.nodes.values()];
         if (query.type) {
             const types = Array.isArray(query.type) ? query.type : [query.type];
@@ -31,6 +45,10 @@ export class InMemoryAdapter {
             const q = query.query.toLowerCase();
             results = results.filter(n => n.content.toLowerCase().includes(q));
         }
+        return results;
+    }
+    async queryNodes(query) {
+        const results = this.filterNodes(query);
         // Sort by createdAt desc
         results.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
         const totalCount = results.length;
@@ -45,6 +63,41 @@ export class InMemoryAdapter {
             .filter(n => n.content.toLowerCase().includes(q))
             .slice(0, limit);
     }
+    /**
+     * Gather attribute-filtered candidates plus a lexical (token-coverage) score
+     * per node. Shared by the in-memory lexical-only hybrid and the JSONL
+     * dense+lexical hybrid (which extends this class and adds a vector channel).
+     */
+    async lexicalCandidates(opts) {
+        // Attribute filter only (no substring) and unsorted — fuseHybrid re-ranks.
+        const candidates = this.filterNodes({
+            type: opts.type,
+            sessionId: opts.sessionId,
+            projectId: opts.projectId,
+            crossProject: opts.crossProject,
+            since: opts.since,
+        });
+        const queryTokens = new Set(tokenize(opts.query));
+        const rawQuery = opts.query.toLowerCase().trim();
+        const nodes = new Map();
+        const lexical = new Map();
+        for (const n of candidates) {
+            nodes.set(n.id, n);
+            let s = lexicalScoreTokens(queryTokens, n.content);
+            // Fall back to legacy substring matching so subword/partial-token queries
+            // are never a regression from the old substring-only recall.
+            if (s === 0 && rawQuery && n.content.toLowerCase().includes(rawQuery)) {
+                s = SUBSTRING_FLOOR;
+            }
+            if (s > 0)
+                lexical.set(n.id, s);
+        }
+        return { nodes, lexical };
+    }
+    async searchHybrid(opts) {
+        const { nodes, lexical } = await this.lexicalCandidates(opts);
+        return fuseHybrid({ nodes, channels: [{ scores: lexical, weight: 1 }] });
+    }
     // ─── Edges ─────────────────────────────────────────────
     async insertEdge(edge) {
         // Check for duplicate (same source, target, type)

package/dist/storage/sqlite.d.ts

@@ -14,6 +14,7 @@ export declare class SQLiteAdapter implements StorageAdapter {
     private get;
     private all;
     insertNode(node: Node): Promise<void>;
+    updateNode(id: string, fields: Partial<Node>): Promise<void>;
     getNode(id: string): Promise<Node | null>;
     queryNodes(query: NodeQuery): Promise<PaginatedResult<Node>>;
     searchContent(text: string, limit?: number): Promise<Node[]>;

package/dist/storage/sqlite.js

@@ -59,6 +59,32 @@ export class SQLiteAdapter {
             node.revisesThought ?? null,
         ]);
     }
+    // Supports only mutable content fields: content, metadata, updatedAt.
+    // (reinforceNode, the only runtime caller, updates just metadata + updatedAt;
+    // content is included for a general updateNode.) Other Node fields are
+    // intentionally not mutable here — this adapter is migration-only, and node
+    // identity/lineage fields (sessionId, projectId, thought*) are set once at
+    // insert. Extend the mapping if a real updateNode caller needs more.
+    async updateNode(id, fields) {
+        const sets = [];
+        const params = [];
+        if (fields.content !== undefined) {
+            sets.push('content = ?');
+            params.push(fields.content);
+        }
+        if (fields.metadata !== undefined) {
+            sets.push('metadata = ?');
+            params.push(JSON.stringify(fields.metadata));
+        }
+        if (fields.updatedAt !== undefined) {
+            sets.push('updated_at = ?');
+            params.push(fields.updatedAt);
+        }
+        if (sets.length > 0) {
+            params.push(id);
+            this.run(`UPDATE nodes SET ${sets.join(', ')} WHERE id = ?`, params);
+        }
+    }
     async getNode(id) {
         const row = this.get('SELECT * FROM nodes WHERE id = ?', [id]);
         return row ? this.rowToNode(row) : null;

package/dist/storage/vector-index.d.ts

@@ -6,6 +6,13 @@ export declare class VectorIndex {
     private readonly vectors;
     load(path: string): void;
     append(path: string, id: string, vec: Float32Array): void;
-    search(queryVec: Float32Array, topK: number): VectorMatch[];
+    /**
+     * Top-K by cosine (vectors are L2-normalized so dot == cosine). When `allow`
+     * is given, only those ids are scored — this filters BEFORE ranking, so a
+     * scoped recall sees the top-K of the in-filter survivors rather than the
+     * global top-K intersected with the filter (which would silently drop
+     * in-filter matches ranked beyond K globally).
+     */
+    search(queryVec: Float32Array, topK: number, allow?: Set<string>): VectorMatch[];
     has(id: string): boolean;
 }

package/dist/storage/vector-index.js

@@ -15,9 +15,18 @@ export class VectorIndex {
         this.vectors.set(id, vec);
         appendFileSync(path, JSON.stringify({ id, vec: Array.from(vec) }) + '\n', 'utf-8');
     }
-    search(queryVec, topK) {
+    /**
+     * Top-K by cosine (vectors are L2-normalized so dot == cosine). When `allow`
+     * is given, only those ids are scored — this filters BEFORE ranking, so a
+     * scoped recall sees the top-K of the in-filter survivors rather than the
+     * global top-K intersected with the filter (which would silently drop
+     * in-filter matches ranked beyond K globally).
+     */
+    search(queryVec, topK, allow) {
         const results = [];
         for (const [id, vec] of this.vectors) {
+            if (allow && !allow.has(id))
+                continue;
             results.push({ id, score: dot(queryVec, vec) });
         }
         results.sort((a, b) => b.score - a.score);

package/dist/tools/execute-skills.d.ts

@@ -32,21 +32,21 @@ export declare const executeSkillsSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         content: string;
         metadata?: Record<string, unknown> | undefined;
-        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        severity?: "high" | "critical" | "medium" | "low" | undefined;
         effort?: string | undefined;
         impact?: string | undefined;
     }, {
         content: string;
         metadata?: Record<string, unknown> | undefined;
-        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        severity?: "high" | "critical" | "medium" | "low" | undefined;
         effort?: string | undefined;
         impact?: string | undefined;
     }>, "many">>;
     sessionId: z.ZodOptional<z.ZodString>;
     projectId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    invocation: string;
     status: "completed" | "failed";
+    invocation: string;
     skill: string;
     stepNumber: number;
     plugin: string;
@@ -65,7 +65,7 @@ export declare const executeSkillsSchema: z.ZodObject<{
     techDebt?: {
         content: string;
         metadata?: Record<string, unknown> | undefined;
-        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        severity?: "high" | "critical" | "medium" | "low" | undefined;
         effort?: string | undefined;
         impact?: string | undefined;
     }[] | undefined;
@@ -75,10 +75,10 @@ export declare const executeSkillsSchema: z.ZodObject<{
     stepNumber: number;
     plugin: string;
     resultSummary: string;
+    status?: "completed" | "failed" | undefined;
     sessionId?: string | undefined;
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
-    status?: "completed" | "failed" | undefined;
     purpose?: string | undefined;
     planId?: string | undefined;
     runId?: string | undefined;
@@ -90,7 +90,7 @@ export declare const executeSkillsSchema: z.ZodObject<{
     techDebt?: {
         content: string;
         metadata?: Record<string, unknown> | undefined;
-        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        severity?: "high" | "critical" | "medium" | "low" | undefined;
         effort?: string | undefined;
         impact?: string | undefined;
     }[] | undefined;

package/dist/tools/learn.d.ts

@@ -32,7 +32,7 @@ export declare const learnSchema: z.ZodObject<{
     sessionId?: string | undefined;
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
-    severity?: "critical" | "high" | "medium" | "low" | undefined;
+    severity?: "high" | "critical" | "medium" | "low" | undefined;
     filePath?: string | undefined;
     lineRange?: [number, number] | undefined;
     relates?: {
@@ -49,7 +49,7 @@ export declare const learnSchema: z.ZodObject<{
     sessionId?: string | undefined;
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
-    severity?: "critical" | "high" | "medium" | "low" | undefined;
+    severity?: "high" | "critical" | "medium" | "low" | undefined;
     filePath?: string | undefined;
     lineRange?: [number, number] | undefined;
     relates?: {

package/dist/tools/learn.js

@@ -20,17 +20,22 @@ export const learnSchema = z.object({
     metadata: z.record(z.unknown()).optional(),
 });
 export async function learnHandler(graph, input, vault, projectSlug) {
-    // Check for duplicate
-    const existing = await graph.findSimilar(input.content, input.type, input.projectId);
-    if (existing) {
+    // Banded duplicate detection (normalized-exact → semantic cosine → Jaccard).
+    const dup = await graph.findDuplicate(input.content, input.type, input.projectId);
+    if (dup && (dup.band === 'exact' || dup.band === 'high')) {
+        // High-confidence duplicate: reinforce the existing node (records the merge,
+        // preserves the new phrasing) instead of silently dropping the new content.
+        await graph.reinforceNode(dup.node.id, input.content);
         return {
             content: [{
                     type: 'text',
                     text: JSON.stringify({
-                        nodeId: existing.id,
-                        type: existing.type,
+                        nodeId: dup.node.id,
+                        type: dup.node.type,
                         relatedCount: 0,
-                        duplicateOf: existing.id,
+                        duplicateOf: dup.node.id,
+                        merged: true,
+                        band: dup.band,
                     }),
                 }],
         };
@@ -57,8 +62,19 @@ export async function learnHandler(graph, input, vault, projectSlug) {
         projectId: input.projectId,
         metadata,
     });
-    // Create relationships
-    let relatedCount = 0;
+    // Borderline near-duplicate: keep the new node but link it to the near-dup so
+    // the relationship is captured rather than creating a silent parallel copy.
+    if (dup && dup.band === 'borderline') {
+        await graph.addEdge({
+            sourceId: node.id,
+            targetId: dup.node.id,
+            type: 'similar_to',
+            reasoning: `Near-duplicate (score ${dup.score.toFixed(2)})`,
+        });
+    }
+    // Create relationships. The auto-created similar_to edge (borderline path
+    // above) counts as a relationship produced by this call.
+    let relatedCount = dup?.band === 'borderline' ? 1 : 0;
     if (input.relates) {
         for (const rel of input.relates) {
             await graph.addEdge({
@@ -113,6 +129,7 @@ export async function learnHandler(graph, input, vault, projectSlug) {
                     type: node.type,
                     relatedCount,
                     duplicateOf: null,
+                    ...(dup?.band === 'borderline' && { nearDuplicateOf: dup.node.id, band: 'borderline' }),
                     ...(vaultPath && { vaultPath }),
                 }),
             }],