@feelingmindful/thinking-graph 1.15.1 → 1.20.0

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Centralized, env-overridable tuning for recall scoring. Flat schema so every
+ * weight/half-life lives in one place instead of scattered module constants.
+ * Values are read once at process start; override via environment variables.
+ */
+export declare const config: {
+    readonly denseWeight: number;
+    readonly lexicalWeight: number;
+    readonly recencyHalfLifeDays: number;
+    readonly recencyReward: number;
+    readonly importanceWeight: number;
+    readonly importanceHalfMerges: number;
+    readonly graphSeedCount: number;
+    readonly graphExpandLimit: number;
+};
+export type ScoringConfig = typeof config;

package/dist/config.js

@@ -0,0 +1,39 @@
+/**
+ * Centralized, env-overridable tuning for recall scoring. Flat schema so every
+ * weight/half-life lives in one place instead of scattered module constants.
+ * Values are read once at process start; override via environment variables.
+ */
+import { z } from 'zod';
+// Coercing parsers that fall back to the default on any invalid input (missing,
+// non-numeric, NaN/Infinity, or out of range) rather than throwing at startup.
+// Weights are finite and >= 0; half-life / half-merges must be > 0 (they are
+// denominators / decay constants).
+const nonneg = (def) => z.coerce.number().finite().nonnegative().catch(def);
+const positive = (def) => z.coerce.number().finite().positive().catch(def);
+const schema = z.object({
+    // Hybrid recall channel weights.
+    THINKING_GRAPH_DENSE_WEIGHT: nonneg(0.6),
+    THINKING_GRAPH_LEXICAL_WEIGHT: nonneg(0.4),
+    // Recency reward: score *= 1 + reward * exp(-age*ln2/halfLife).
+    THINKING_GRAPH_RECENCY_HALF_LIFE_DAYS: positive(14),
+    THINKING_GRAPH_RECENCY_REWARD: nonneg(0.2),
+    // Importance reward from reinforcement: score *= 1 + weight * m/(m+halfMerges),
+    // where m is the node's mergeCount (how often a duplicate reinforced it).
+    THINKING_GRAPH_IMPORTANCE_WEIGHT: nonneg(0.3),
+    THINKING_GRAPH_IMPORTANCE_HALF_MERGES: positive(3),
+    // Graph expansion (multi-hop recall): how many top content hits to seed the
+    // 1-hop typed-edge walk from, and how many neighbours to pull in.
+    THINKING_GRAPH_GRAPH_SEED_COUNT: positive(3),
+    THINKING_GRAPH_GRAPH_EXPAND_LIMIT: positive(10),
+});
+const env = schema.parse(process.env);
+export const config = {
+    denseWeight: env.THINKING_GRAPH_DENSE_WEIGHT,
+    lexicalWeight: env.THINKING_GRAPH_LEXICAL_WEIGHT,
+    recencyHalfLifeDays: env.THINKING_GRAPH_RECENCY_HALF_LIFE_DAYS,
+    recencyReward: env.THINKING_GRAPH_RECENCY_REWARD,
+    importanceWeight: env.THINKING_GRAPH_IMPORTANCE_WEIGHT,
+    importanceHalfMerges: env.THINKING_GRAPH_IMPORTANCE_HALF_MERGES,
+    graphSeedCount: env.THINKING_GRAPH_GRAPH_SEED_COUNT,
+    graphExpandLimit: env.THINKING_GRAPH_GRAPH_EXPAND_LIMIT,
+};

package/dist/engine/dedup.d.ts

@@ -2,4 +2,14 @@
  * Content deduplication using Jaccard similarity on word tokens.
  */
 export declare function tokenize(content: string): string[];
+export declare const DUP_COSINE_HIGH = 0.92;
+export declare const DUP_COSINE_BORDERLINE = 0.8;
+export declare const DUP_JACCARD_HIGH = 0.9;
+export declare const DUP_JACCARD_BORDERLINE = 0.75;
+/**
+ * Canonicalize content for exact-match dedup: casefold, unify unicode
+ * dashes/hyphens to '-', and collapse all whitespace runs. So trivially
+ * different renderings of the same fact compare equal.
+ */
+export declare function normalizeForExactMatch(content: string): string;
 export declare function similarity(a: string, b: string): number;

package/dist/engine/dedup.js

@@ -4,6 +4,25 @@
 export function tokenize(content) {
     return content.toLowerCase().split(/\W+/).filter(Boolean);
 }
+// Duplicate-detection bands. Cosine bands apply when an embedding index is
+// available; Jaccard bands are the offline fallback (token-overlap runs hotter
+// than cosine, so its thresholds differ).
+export const DUP_COSINE_HIGH = 0.92;
+export const DUP_COSINE_BORDERLINE = 0.80;
+export const DUP_JACCARD_HIGH = 0.9;
+export const DUP_JACCARD_BORDERLINE = 0.75;
+/**
+ * Canonicalize content for exact-match dedup: casefold, unify unicode
+ * dashes/hyphens to '-', and collapse all whitespace runs. So trivially
+ * different renderings of the same fact compare equal.
+ */
+export function normalizeForExactMatch(content) {
+    return content
+        .toLowerCase()
+        .replace(/[‐-―−]/g, '-') // hyphens, en/em dashes, minus → '-'
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 export function similarity(a, b) {
     const tokensA = new Set(tokenize(a));
     const tokensB = new Set(tokenize(b));

package/dist/engine/fusion.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Score fusion primitives for hybrid recall.
+ *
+ * Recall blends several ranking channels — dense vector similarity, lexical
+ * token coverage, and (later) graph signals. Each channel produces raw scores
+ * on its own scale, so we min-max normalize per channel, combine with weights,
+ * and apply a mild recency reward. These are pure functions with no I/O so the
+ * ranking math is unit-testable in isolation from storage and embeddings.
+ */
+import type { Node, ScoredNode } from './types.js';
+export interface FusionChannel {
+    scores: Map<string, number>;
+    weight: number;
+}
+export interface FuseHybridArgs {
+    /** Candidate nodes by id. Only ids present here are emitted. */
+    nodes: Map<string, Node>;
+    /** Raw (un-normalized) channels; each is min-max normalized internally. */
+    channels: FusionChannel[];
+    /** Recency reward coefficient applied as base * (1 + reward * recency). */
+    recencyReward?: number;
+    /** Recency half-life in days. */
+    halfLifeDays?: number;
+    /** Importance reward coefficient (reinforcement boost from mergeCount). */
+    importanceWeight?: number;
+    /** mergeCount at which the importance reward reaches half its maximum. */
+    importanceHalfMerges?: number;
+    /** Injectable clock for deterministic tests. */
+    now?: Date;
+}
+/**
+ * Reinforcement importance multiplier in [1, 1+weight). A node merged into more
+ * often (higher mergeCount) ranks higher, with saturating returns:
+ * m=0 → 1, m=halfMerges → 1 + weight/2, m→∞ → 1 + weight.
+ */
+export declare function importanceFactor(mergeCount: number, weight: number, halfMerges: number): number;
+/**
+ * Scale a map of raw scores to [0,1] via min-max. All-equal (or single) inputs
+ * map to 1 — they are equally relevant, normalized to the top of the channel.
+ */
+export declare function minMaxNormalize(scores: Map<string, number>): Map<string, number>;
+/**
+ * Weighted sum across channels over the union of ids. An id absent from a
+ * channel contributes 0 for that channel. Weights need not sum to 1.
+ */
+export declare function weightedFuse(channels: FusionChannel[]): Map<string, number>;
+/**
+ * Reciprocal Rank Fusion over ranked id lists. Score for an id is the sum of
+ * 1/(k + rank) across the lists it appears in, with 1-based rank. Rank-based,
+ * so it fuses lists whose raw scores are not comparable (e.g. cosine vs Jaccard).
+ */
+export declare function rrfFuse(rankedLists: string[][], k?: number): Map<string, number>;
+/**
+ * Exponential time-decay weight in (0,1]. 1 at age 0, 0.5 at one half-life.
+ * Future timestamps (negative age) are capped at 1.
+ */
+export declare function recencyWeight(createdAt: string, halfLifeDays?: number, now?: Date): number;
+/**
+ * Lexical relevance from a precomputed query-token set: the fraction of those
+ * tokens present in the content. Lets callers tokenize the query once and reuse
+ * the set across many candidates. 0 when the set is empty.
+ */
+export declare function lexicalScoreTokens(queryTokens: Set<string>, content: string): number;
+/**
+ * Lexical relevance as the fraction of distinct query tokens present in the
+ * content. 0 when nothing overlaps or the query is empty.
+ */
+export declare function lexicalScore(query: string, content: string): number;
+/**
+ * Fuse weighted channels into a single ranked list of scored nodes. Channels
+ * are min-max normalized, weighted-summed, then multiplied by a mild recency
+ * reward. Only ids present in `nodes` are emitted. Returns the full ranked list
+ * (caller paginates).
+ */
+export declare function fuseHybrid(args: FuseHybridArgs): ScoredNode[];

package/dist/engine/fusion.js

@@ -0,0 +1,144 @@
+/**
+ * Score fusion primitives for hybrid recall.
+ *
+ * Recall blends several ranking channels — dense vector similarity, lexical
+ * token coverage, and (later) graph signals. Each channel produces raw scores
+ * on its own scale, so we min-max normalize per channel, combine with weights,
+ * and apply a mild recency reward. These are pure functions with no I/O so the
+ * ranking math is unit-testable in isolation from storage and embeddings.
+ */
+import { tokenize } from './dedup.js';
+import { config } from '../config.js';
+const MS_PER_DAY = 86_400_000;
+const DEFAULT_HALF_LIFE_DAYS = 14;
+/**
+ * Reinforcement importance multiplier in [1, 1+weight). A node merged into more
+ * often (higher mergeCount) ranks higher, with saturating returns:
+ * m=0 → 1, m=halfMerges → 1 + weight/2, m→∞ → 1 + weight.
+ */
+export function importanceFactor(mergeCount, weight, halfMerges) {
+    // Guard against non-finite / non-positive inputs (bad config or corrupted
+    // metadata): no boost rather than NaN or a divide-by-zero.
+    if (!Number.isFinite(mergeCount) || mergeCount <= 0)
+        return 1;
+    if (!Number.isFinite(weight) || weight <= 0)
+        return 1;
+    if (!Number.isFinite(halfMerges) || halfMerges <= 0)
+        return 1;
+    return 1 + weight * (mergeCount / (mergeCount + halfMerges));
+}
+/**
+ * Scale a map of raw scores to [0,1] via min-max. All-equal (or single) inputs
+ * map to 1 — they are equally relevant, normalized to the top of the channel.
+ */
+export function minMaxNormalize(scores) {
+    if (scores.size === 0)
+        return new Map();
+    let min = Infinity;
+    let max = -Infinity;
+    for (const v of scores.values()) {
+        if (v < min)
+            min = v;
+        if (v > max)
+            max = v;
+    }
+    const range = max - min;
+    const out = new Map();
+    for (const [id, v] of scores) {
+        out.set(id, range === 0 ? 1 : (v - min) / range);
+    }
+    return out;
+}
+/**
+ * Weighted sum across channels over the union of ids. An id absent from a
+ * channel contributes 0 for that channel. Weights need not sum to 1.
+ */
+export function weightedFuse(channels) {
+    const out = new Map();
+    for (const { scores, weight } of channels) {
+        for (const [id, score] of scores) {
+            out.set(id, (out.get(id) ?? 0) + weight * score);
+        }
+    }
+    return out;
+}
+/**
+ * Reciprocal Rank Fusion over ranked id lists. Score for an id is the sum of
+ * 1/(k + rank) across the lists it appears in, with 1-based rank. Rank-based,
+ * so it fuses lists whose raw scores are not comparable (e.g. cosine vs Jaccard).
+ */
+export function rrfFuse(rankedLists, k = 60) {
+    const out = new Map();
+    for (const list of rankedLists) {
+        list.forEach((id, idx) => {
+            out.set(id, (out.get(id) ?? 0) + 1 / (k + idx + 1));
+        });
+    }
+    return out;
+}
+/**
+ * Exponential time-decay weight in (0,1]. 1 at age 0, 0.5 at one half-life.
+ * Future timestamps (negative age) are capped at 1.
+ */
+export function recencyWeight(createdAt, halfLifeDays = DEFAULT_HALF_LIFE_DAYS, now = new Date()) {
+    // A non-positive / non-finite half-life would invert or blow up the decay;
+    // treat it as "no decay" so the weight stays in (0,1].
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0)
+        return 1;
+    const ageDays = (now.getTime() - new Date(createdAt).getTime()) / MS_PER_DAY;
+    if (!Number.isFinite(ageDays) || ageDays <= 0)
+        return 1;
+    return Math.exp((-ageDays * Math.LN2) / halfLifeDays);
+}
+/**
+ * Lexical relevance from a precomputed query-token set: the fraction of those
+ * tokens present in the content. Lets callers tokenize the query once and reuse
+ * the set across many candidates. 0 when the set is empty.
+ */
+export function lexicalScoreTokens(queryTokens, content) {
+    if (queryTokens.size === 0)
+        return 0;
+    const contentTokens = new Set(tokenize(content));
+    let hits = 0;
+    for (const t of queryTokens) {
+        if (contentTokens.has(t))
+            hits++;
+    }
+    return hits / queryTokens.size;
+}
+/**
+ * Lexical relevance as the fraction of distinct query tokens present in the
+ * content. 0 when nothing overlaps or the query is empty.
+ */
+export function lexicalScore(query, content) {
+    return lexicalScoreTokens(new Set(tokenize(query)), content);
+}
+/**
+ * Fuse weighted channels into a single ranked list of scored nodes. Channels
+ * are min-max normalized, weighted-summed, then multiplied by a mild recency
+ * reward. Only ids present in `nodes` are emitted. Returns the full ranked list
+ * (caller paginates).
+ */
+export function fuseHybrid(args) {
+    const normalized = args.channels.map(c => ({
+        scores: minMaxNormalize(c.scores),
+        weight: c.weight,
+    }));
+    const fused = weightedFuse(normalized);
+    const reward = args.recencyReward ?? config.recencyReward;
+    const halfLife = args.halfLifeDays ?? config.recencyHalfLifeDays;
+    const importanceW = args.importanceWeight ?? config.importanceWeight;
+    const halfMerges = args.importanceHalfMerges ?? config.importanceHalfMerges;
+    const out = [];
+    for (const [id, base] of fused) {
+        const node = args.nodes.get(id);
+        if (!node)
+            continue;
+        const recency = recencyWeight(node.createdAt, halfLife, args.now);
+        const mergeCount = typeof node.metadata?.mergeCount === 'number' ? node.metadata.mergeCount : 0;
+        const importance = importanceFactor(mergeCount, importanceW, halfMerges);
+        out.push({ ...node, score: base * (1 + reward * recency) * importance });
+    }
+    out.sort((a, b) => b.score - a.score);
+    return out;
+}

package/dist/engine/graph.d.ts

@@ -1,5 +1,6 @@
-import type { StorageAdapter } from '../storage/adapter.js';
+import type { StorageAdapter, HybridSearchOpts } from '../storage/adapter.js';
 import type { Node, Edge, Session, NodeType, EdgeType, NodeQuery, PaginatedResult, NodeWithEdges, ExportOpts, GraphExport, HealthReport, SkillRegistryEntry } from './types.js';
+export type DuplicateBand = 'exact' | 'high' | 'borderline';
 export declare class ThinkingGraph {
     storage: StorageAdapter;
     private currentSessionId;
@@ -10,7 +11,34 @@ export declare class ThinkingGraph {
     getNode(id: string): Promise<Node | null>;
     findNodes(query: NodeQuery): Promise<PaginatedResult<Node>>;
     searchNodes(text: string, limit?: number): Promise<Node[]>;
+    /**
+     * Ranked hybrid recall: fuses semantic (dense vector) + lexical channels with
+     * a recency reward. Falls back to substring queryNodes when the storage
+     * adapter has no hybrid index. Items are ScoredNode (carry a `score`).
+     */
+    recallHybrid(opts: HybridSearchOpts & {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<Node>>;
     findSimilar(content: string, type: NodeType, projectId?: string, threshold?: number): Promise<Node | null>;
+    /**
+     * Banded duplicate detection for learn-time dedup:
+     *   L1 — normalized exact match (casefold/dash/whitespace) → band 'exact'
+     *   L2 — semantic cosine via the embedding index (Jaccard fallback offline):
+     *        >= HIGH → 'high' (auto-merge), >= BORDERLINE → 'borderline' (near-dup)
+     * Returns the best match and its band, or null when nothing is similar enough.
+     */
+    findDuplicate(content: string, type: NodeType, projectId?: string): Promise<{
+        node: Node;
+        band: DuplicateBand;
+        score: number;
+    } | null>;
+    /**
+     * Reinforce a node after a duplicate observation (non-silent merge): bump
+     * mergeCount/lastMergedAt and preserve a distinct merged variant (capped), so
+     * the merge is recorded and reversible rather than dropping the new content.
+     */
+    reinforceNode(id: string, variant?: string): Promise<void>;
     addEdge(input: Omit<Edge, 'id' | 'createdAt' | 'weight'> & {
         id?: string;
         weight?: number;
@@ -19,6 +47,12 @@ export declare class ThinkingGraph {
     }>;
     getEdges(nodeId: string, direction?: 'outgoing' | 'incoming' | 'both', type?: EdgeType): Promise<Edge[]>;
     traverse(startId: string, edgeType: EdgeType, depth?: number): Promise<Node[]>;
+    /**
+     * 1-hop typed-edge neighbours of the seed nodes, across all edge types and
+     * both directions, excluding the seeds themselves and deduped. Used to pull
+     * structurally-related context into multi-hop recall.
+     */
+    expandNeighbors(seedIds: string[], limit?: number): Promise<Node[]>;
     findContradictions(sessionId?: string): Promise<{
         a: Node;
         b: Node;

package/dist/engine/graph.js

@@ -1,6 +1,20 @@
 import { v4 as uuid } from 'uuid';
-import { similarity } from './dedup.js';
+import { similarity, normalizeForExactMatch, tokenize, DUP_COSINE_HIGH, DUP_COSINE_BORDERLINE, DUP_JACCARD_HIGH, DUP_JACCARD_BORDERLINE, } from './dedup.js';
 import { seedAll } from './seed.js';
+const MAX_MERGED_VARIANTS = 5;
+// Candidate cap for the L1 normalized-exact scan and the Jaccard fallback. The
+// cosine path (findNearest) scans the full in-filter set; only these two scans
+// are capped, so an exact/lexical duplicate of an older node can be missed once
+// a single type accumulates more than this many nodes.
+const DUP_CANDIDATE_LIMIT = 1000;
+/** Map a similarity score to a duplicate band, or null if below borderline. */
+function bandFor(score, high, borderline) {
+    if (score >= high)
+        return 'high';
+    if (score >= borderline)
+        return 'borderline';
+    return null;
+}
 export class ThinkingGraph {
     storage;
     currentSessionId = null;
@@ -41,6 +55,33 @@ export class ThinkingGraph {
     async searchNodes(text, limit = 20) {
         return this.storage.searchContent(text, limit);
     }
+    /**
+     * Ranked hybrid recall: fuses semantic (dense vector) + lexical channels with
+     * a recency reward. Falls back to substring queryNodes when the storage
+     * adapter has no hybrid index. Items are ScoredNode (carry a `score`).
+     */
+    async recallHybrid(opts) {
+        if (!this.storage.searchHybrid) {
+            return this.findNodes({
+                query: opts.query,
+                type: opts.type,
+                sessionId: opts.sessionId,
+                projectId: opts.projectId,
+                crossProject: opts.crossProject,
+                since: opts.since,
+                limit: opts.limit,
+                offset: opts.offset,
+            });
+        }
+        const scored = await this.storage.searchHybrid(opts);
+        const offset = opts.offset ?? 0;
+        const limit = opts.limit ?? 20;
+        return {
+            items: scored.slice(offset, offset + limit),
+            totalCount: scored.length,
+            hasMore: offset + limit < scored.length,
+        };
+    }
     async findSimilar(content, type, projectId, threshold = 0.9) {
         // Get candidates of the same type
         const candidates = await this.storage.queryNodes({
@@ -55,6 +96,78 @@ export class ThinkingGraph {
         }
         return null;
     }
+    /**
+     * Banded duplicate detection for learn-time dedup:
+     *   L1 — normalized exact match (casefold/dash/whitespace) → band 'exact'
+     *   L2 — semantic cosine via the embedding index (Jaccard fallback offline):
+     *        >= HIGH → 'high' (auto-merge), >= BORDERLINE → 'borderline' (near-dup)
+     * Returns the best match and its band, or null when nothing is similar enough.
+     */
+    async findDuplicate(content, type, projectId) {
+        // Degenerate content (empty / whitespace / punctuation-only) has no signal
+        // to dedup on — never match it. (Without this, two token-empty strings score
+        // similarity 1.0 and would auto-merge into an unrelated node.)
+        const norm = normalizeForExactMatch(content);
+        if (norm === '' || tokenize(content).length === 0)
+            return null;
+        const candidates = (await this.storage.queryNodes({ type, projectId, limit: DUP_CANDIDATE_LIMIT })).items;
+        if (candidates.length === 0)
+            return null;
+        // L1: normalized exact match
+        for (const c of candidates) {
+            if (normalizeForExactMatch(c.content) === norm) {
+                return { node: c, band: 'exact', score: 1 };
+            }
+        }
+        // L2a: semantic cosine when the embedding index can place this content.
+        if (this.storage.findNearest) {
+            const near = await this.storage.findNearest(content, { type, projectId });
+            if (near) {
+                const band = bandFor(near.score, DUP_COSINE_HIGH, DUP_COSINE_BORDERLINE);
+                if (band) {
+                    const node = await this.storage.getNode(near.id);
+                    if (node)
+                        return { node, band, score: near.score };
+                }
+                // cosine below borderline → fall through; Jaccard may still catch a
+                // lexical duplicate the embedder under-scored.
+            }
+        }
+        // L2b: Jaccard fallback — runs whenever cosine did not yield a confident
+        // band (embeddings disabled, candidate not embedded, or cosine too low).
+        let best = null;
+        for (const c of candidates) {
+            const s = similarity(content, c.content);
+            if (!best || s > best.score)
+                best = { node: c, score: s };
+        }
+        if (!best)
+            return null;
+        const band = bandFor(best.score, DUP_JACCARD_HIGH, DUP_JACCARD_BORDERLINE);
+        return band ? { node: best.node, band, score: best.score } : null;
+    }
+    /**
+     * Reinforce a node after a duplicate observation (non-silent merge): bump
+     * mergeCount/lastMergedAt and preserve a distinct merged variant (capped), so
+     * the merge is recorded and reversible rather than dropping the new content.
+     */
+    async reinforceNode(id, variant) {
+        const node = await this.storage.getNode(id);
+        if (!node)
+            return;
+        const meta = { ...node.metadata };
+        meta.mergeCount = (typeof meta.mergeCount === 'number' ? meta.mergeCount : 0) + 1;
+        meta.lastMergedAt = new Date().toISOString();
+        if (variant && normalizeForExactMatch(variant) !== normalizeForExactMatch(node.content)) {
+            const variants = Array.isArray(meta.mergedVariants) ? meta.mergedVariants : [];
+            const seen = normalizeForExactMatch(variant);
+            const known = variants.some(v => normalizeForExactMatch(v) === seen);
+            if (!known && variants.length < MAX_MERGED_VARIANTS) {
+                meta.mergedVariants = [...variants, variant];
+            }
+        }
+        await this.storage.updateNode(id, { metadata: meta, updatedAt: new Date().toISOString() });
+    }
     // ─── Edge operations ─────────────────────────────────
     async addEdge(input) {
         const edge = {
@@ -82,6 +195,39 @@ export class ThinkingGraph {
     async traverse(startId, edgeType, depth = 1) {
         return this.storage.traverseEdges(startId, edgeType, depth);
     }
+    /**
+     * 1-hop typed-edge neighbours of the seed nodes, across all edge types and
+     * both directions, excluding the seeds themselves and deduped. Used to pull
+     * structurally-related context into multi-hop recall.
+     */
+    async expandNeighbors(seedIds, limit = 10) {
+        const seen = new Set(seedIds);
+        const out = [];
+        const collect = async (edges, id) => {
+            for (const e of edges) {
+                const neighborId = e.sourceId === id ? e.targetId : e.sourceId;
+                if (seen.has(neighborId))
+                    continue;
+                seen.add(neighborId);
+                const node = await this.storage.getNode(neighborId);
+                if (node)
+                    out.push(node);
+                if (out.length >= limit)
+                    return;
+            }
+        };
+        // Fetch outgoing first, then incoming, checking the cap between each — so a
+        // high-degree node's incoming edges aren't fetched once the limit is met.
+        for (const id of seedIds) {
+            if (out.length >= limit)
+                break;
+            await collect(await this.storage.getEdgesFrom(id), id);
+            if (out.length >= limit)
+                break;
+            await collect(await this.storage.getEdgesTo(id), id);
+        }
+        return out;
+    }
     async findContradictions(sessionId) {
         const query = sessionId ? { sessionId } : {};
         const allNodes = await this.storage.queryNodes({ ...query, limit: 1000 });

package/dist/engine/intent.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lightweight, pure-regex query intent classification. Used to gate expensive
+ * recall stages (e.g. the graph-walk expansion) so single-entity lookups stay
+ * cheap and clean, while relationship/traversal queries get structural context.
+ */
+export interface QueryIntent {
+    /** Asks about relationships, causation, or traversal across nodes. */
+    multiHop: boolean;
+    /** Asks about history / sequence / evolution over time. */
+    narrative: boolean;
+    /** First-person framing ("my", "our", "we"). */
+    personal: boolean;
+}
+export declare function classifyIntent(query: string): QueryIntent;

package/dist/engine/intent.js

@@ -0,0 +1,19 @@
+/**
+ * Lightweight, pure-regex query intent classification. Used to gate expensive
+ * recall stages (e.g. the graph-walk expansion) so single-entity lookups stay
+ * cheap and clean, while relationship/traversal queries get structural context.
+ */
+// Relationship / causation / traversal cues.
+const MULTIHOP_RE = /\b(relate[ds]?|related to|relationship|depend(s|ed|ency|encies)?|because|cause[ds]?|causes|lead(s|ing)? to|result(s|ed)? in|connect(s|ed|ion|ions)?|chain|affect(s|ed)?|impact(s|ed)?|influence[ds]?|between|downstream|upstream|trace|tied to|linked)\b/i;
+// History / sequence / evolution cues.
+const NARRATIVE_RE = /\b(history|timeline|evolution|evolved?|over time|how did|journey|progress(ion)?|sequence|chronolog\w*|previously|originally)\b/i;
+// First-person cues (token-boundary to avoid matching inside words).
+const PERSONAL_RE = /\b(i|i'm|i've|me|my|mine|we|we're|we've|us|our|ours)\b/i;
+export function classifyIntent(query) {
+    const q = query ?? '';
+    return {
+        multiHop: MULTIHOP_RE.test(q),
+        narrative: NARRATIVE_RE.test(q),
+        personal: PERSONAL_RE.test(q),
+    };
+}

package/dist/engine/types.d.ts

@@ -69,6 +69,10 @@ export interface PaginatedResult<T> {
     totalCount: number;
     hasMore: boolean;
 }
+export interface ScoredNode extends Node {
+    /** Fused relevance score from hybrid recall (higher is more relevant). */
+    score: number;
+}
 export interface NodeWithEdges extends Node {
     edges: {
         type: EdgeType;

package/dist/storage/adapter.d.ts

@@ -1,11 +1,40 @@
-import type { Node, Edge, Session, SkillRegistryEntry, NodeQuery, PaginatedResult, EdgeType, ExportOpts, GraphExport, GraphStats } from '../engine/types.js';
+import type { Node, Edge, Session, SkillRegistryEntry, NodeQuery, PaginatedResult, EdgeType, NodeType, ScoredNode, ExportOpts, GraphExport, GraphStats } from '../engine/types.js';
+/** Attribute filters for a hybrid (semantic + lexical) recall. */
+export interface HybridSearchOpts {
+    query: string;
+    type?: NodeType | NodeType[];
+    sessionId?: string;
+    projectId?: string;
+    crossProject?: boolean;
+    since?: string;
+}
 export interface 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>;
     queryNodes(query: NodeQuery): Promise<PaginatedResult<Node>>;
     searchContent(text: string, limit?: number): Promise<Node[]>;
+    /**
+     * Highest-cosine same-type (and same-project, when given) node for `content`.
+     * Optional: adapters without an embedding index omit it (callers fall back to
+     * Jaccard similarity). Returns null when no embedding is available or no node
+     * matches the filter.
+     */
+    findNearest?(content: string, opts: {
+        type: NodeType;
+        projectId?: string;
+    }): Promise<{
+        id: string;
+        score: number;
+    } | null>;
+    /**
+     * Ranked hybrid recall fusing semantic (dense vector) and lexical channels
+     * with a recency reward. Optional: adapters without an embedding index may
+     * omit it (callers fall back to queryNodes substring search).
+     */
+    searchHybrid?(opts: HybridSearchOpts): Promise<ScoredNode[]>;
     insertEdge(edge: Edge): Promise<boolean>;
     getEdgesFrom(nodeId: string, type?: EdgeType): Promise<Edge[]>;
     getEdgesTo(nodeId: string, type?: EdgeType): Promise<Edge[]>;