@psiclawops/hypermem 0.5.0 → 0.5.1

package/dist/keystone-scorer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * hypermem Keystone Scorer
+ *
+ * Scores message candidates for inclusion in the Keystone History Slot (P2.1).
+ * A "keystone" is an older, high-signal message that provides critical context
+ * for the current conversation — decisions, specs, discoveries that happened
+ * before the recent history window.
+ *
+ * Scoring formula (weights sum to 1.0):
+ *   - episodeSignificance × 0.5  (was this message linked to a significant episode?)
+ *   - ftsRelevance × 0.3         (is it semantically relevant to the current prompt?)
+ *   - recencyFactor × 0.2        (how recent is it, relative to maxAgeHours?)
+ *
+ * Content-type bonus: messages classified as 'decision' or 'spec' get +0.1,
+ * capped at 1.0. These are the highest-value signals for context recall.
+ */
+export interface KeystoneCandidate {
+    messageId: number;
+    messageIndex: number;
+    role: string;
+    content: string;
+    timestamp: string;
+    /** Significance from the episodes table (NULL if no episode was linked). */
+    episodeSignificance: number | null;
+    /** FTS5 BM25 relevance rank, already normalized to [0, 1]. */
+    ftsRank: number;
+    /** Age in hours from now. */
+    ageHours: number;
+}
+export interface ScoredKeystone extends KeystoneCandidate {
+    score: number;
+}
+/**
+ * Score a single keystone candidate.
+ *
+ * @param candidate - The message candidate with its signals
+ * @param maxAgeHours - The age ceiling for the recency factor (messages older
+ *   than this get recencyFactor = 0, but are not excluded — they can still score
+ *   via significance + ftsRelevance).
+ * @returns Score in [0.0, 1.0]
+ */
+export declare function scoreKeystone(candidate: KeystoneCandidate, maxAgeHours: number): number;
+/**
+ * Score an array of candidates and sort by score descending.
+ *
+ * @param candidates - Raw candidates from the DB query
+ * @param maxAgeHours - Age ceiling for recency scoring (e.g. 720 = 30 days)
+ * @returns Candidates sorted by score DESC with score field attached
+ */
+export declare function rankKeystones(candidates: KeystoneCandidate[], maxAgeHours: number): ScoredKeystone[];
+//# sourceMappingURL=keystone-scorer.d.ts.map

package/dist/keystone-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-scorer.d.ts","sourceRoot":"","sources":["../src/keystone-scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,iBAAiB,EAC5B,WAAW,EAAE,MAAM,GAClB,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,iBAAiB,EAAE,EAC/B,WAAW,EAAE,MAAM,GAClB,cAAc,EAAE,CAIlB"}

package/dist/keystone-scorer.js

@@ -0,0 +1,52 @@
+/**
+ * hypermem Keystone Scorer
+ *
+ * Scores message candidates for inclusion in the Keystone History Slot (P2.1).
+ * A "keystone" is an older, high-signal message that provides critical context
+ * for the current conversation — decisions, specs, discoveries that happened
+ * before the recent history window.
+ *
+ * Scoring formula (weights sum to 1.0):
+ *   - episodeSignificance × 0.5  (was this message linked to a significant episode?)
+ *   - ftsRelevance × 0.3         (is it semantically relevant to the current prompt?)
+ *   - recencyFactor × 0.2        (how recent is it, relative to maxAgeHours?)
+ *
+ * Content-type bonus: messages classified as 'decision' or 'spec' get +0.1,
+ * capped at 1.0. These are the highest-value signals for context recall.
+ */
+import { classifyContentType } from './content-type-classifier.js';
+// ─── Scorer ──────────────────────────────────────────────────────
+/**
+ * Score a single keystone candidate.
+ *
+ * @param candidate - The message candidate with its signals
+ * @param maxAgeHours - The age ceiling for the recency factor (messages older
+ *   than this get recencyFactor = 0, but are not excluded — they can still score
+ *   via significance + ftsRelevance).
+ * @returns Score in [0.0, 1.0]
+ */
+export function scoreKeystone(candidate, maxAgeHours) {
+    const significance = candidate.episodeSignificance ?? 0.3;
+    const ftsRelevance = Math.min(1.0, Math.max(0, candidate.ftsRank));
+    const recencyFactor = Math.max(0, 1.0 - (candidate.ageHours / maxAgeHours));
+    let score = (significance * 0.5) + (ftsRelevance * 0.3) + (recencyFactor * 0.2);
+    // Content-type bonus: decisions and specs get +0.1 (capped at 1.0)
+    const contentType = classifyContentType(candidate.content);
+    if (contentType.type === 'decision' || contentType.type === 'spec') {
+        score = Math.min(1.0, score + 0.1);
+    }
+    return score;
+}
+/**
+ * Score an array of candidates and sort by score descending.
+ *
+ * @param candidates - Raw candidates from the DB query
+ * @param maxAgeHours - Age ceiling for recency scoring (e.g. 720 = 30 days)
+ * @returns Candidates sorted by score DESC with score field attached
+ */
+export function rankKeystones(candidates, maxAgeHours) {
+    return candidates
+        .map(c => ({ ...c, score: scoreKeystone(c, maxAgeHours) }))
+        .sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=keystone-scorer.js.map

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,110 @@
+/**
+ * hypermem Knowledge Graph
+ *
+ * DAG traversal over knowledge_links in library.db.
+ * Links connect entities across collections:
+ *   - fact ↔ fact (supersedes, contradicts, supports)
+ *   - fact ↔ knowledge (references, derived_from)
+ *   - knowledge ↔ knowledge (depends_on, extends)
+ *   - topic ↔ fact (covers)
+ *   - agent ↔ fact (authored_by)
+ *
+ * Traversal is bounded (max depth, max results) to prevent runaway queries.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export type EntityType = 'fact' | 'knowledge' | 'topic' | 'episode' | 'agent' | 'preference';
+export interface KnowledgeLink {
+    id: number;
+    fromType: EntityType;
+    fromId: number;
+    toType: EntityType;
+    toId: number;
+    linkType: string;
+    createdAt: string;
+}
+export interface GraphNode {
+    type: EntityType;
+    id: number;
+    depth: number;
+    linkType: string;
+    direction: 'outbound' | 'inbound';
+}
+export interface TraversalResult {
+    nodes: GraphNode[];
+    edges: KnowledgeLink[];
+    truncated: boolean;
+}
+export declare class KnowledgeGraph {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Create a directed link between two entities.
+     * Idempotent — unique constraint on (from_type, from_id, to_type, to_id, link_type).
+     */
+    addLink(fromType: EntityType, fromId: number, toType: EntityType, toId: number, linkType: string): KnowledgeLink;
+    /**
+     * Remove a specific link.
+     */
+    removeLink(fromType: EntityType, fromId: number, toType: EntityType, toId: number, linkType: string): boolean;
+    /**
+     * Remove all links involving an entity (both directions).
+     */
+    removeEntityLinks(type: EntityType, id: number): number;
+    /**
+     * Get outbound links from an entity.
+     */
+    getOutbound(type: EntityType, id: number, linkType?: string): KnowledgeLink[];
+    /**
+     * Get inbound links to an entity.
+     */
+    getInbound(type: EntityType, id: number, linkType?: string): KnowledgeLink[];
+    /**
+     * Get all links for an entity (both directions).
+     */
+    getLinks(type: EntityType, id: number): KnowledgeLink[];
+    /**
+     * Breadth-first traversal from a starting entity.
+     * Follows links in both directions up to maxDepth.
+     *
+     * @param startType - Entity type to start from
+     * @param startId - Entity ID to start from
+     * @param opts - Traversal options
+     * @returns Discovered nodes and edges
+     */
+    traverse(startType: EntityType, startId: number, opts?: {
+        maxDepth?: number;
+        maxResults?: number;
+        linkTypes?: string[];
+        direction?: 'outbound' | 'inbound' | 'both';
+        targetTypes?: EntityType[];
+    }): TraversalResult;
+    /**
+     * Find the shortest path between two entities.
+     * Uses BFS — returns null if no path exists within maxDepth.
+     */
+    findPath(fromType: EntityType, fromId: number, toType: EntityType, toId: number, maxDepth?: number): GraphNode[] | null;
+    /**
+     * Get the most connected entities (highest degree).
+     */
+    getMostConnected(opts?: {
+        type?: EntityType;
+        limit?: number;
+    }): Array<{
+        type: EntityType;
+        id: number;
+        degree: number;
+    }>;
+    /**
+     * Count links by type.
+     */
+    getLinkStats(): Array<{
+        linkType: string;
+        count: number;
+    }>;
+    /**
+     * Total link count.
+     */
+    getTotalLinks(): number;
+    private rowToLink;
+}
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-graph.js

@@ -0,0 +1,305 @@
+/**
+ * hypermem Knowledge Graph
+ *
+ * DAG traversal over knowledge_links in library.db.
+ * Links connect entities across collections:
+ *   - fact ↔ fact (supersedes, contradicts, supports)
+ *   - fact ↔ knowledge (references, derived_from)
+ *   - knowledge ↔ knowledge (depends_on, extends)
+ *   - topic ↔ fact (covers)
+ *   - agent ↔ fact (authored_by)
+ *
+ * Traversal is bounded (max depth, max results) to prevent runaway queries.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+export class KnowledgeGraph {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ─── Link Management ───────────────────────────────────────
+    /**
+     * Create a directed link between two entities.
+     * Idempotent — unique constraint on (from_type, from_id, to_type, to_id, link_type).
+     */
+    addLink(fromType, fromId, toType, toId, linkType) {
+        const now = nowIso();
+        this.db.prepare(`
+      INSERT OR IGNORE INTO knowledge_links (from_type, from_id, to_type, to_id, link_type, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(fromType, fromId, toType, toId, linkType, now);
+        const row = this.db.prepare(`
+      SELECT * FROM knowledge_links
+      WHERE from_type = ? AND from_id = ? AND to_type = ? AND to_id = ? AND link_type = ?
+    `).get(fromType, fromId, toType, toId, linkType);
+        return this.rowToLink(row);
+    }
+    /**
+     * Remove a specific link.
+     */
+    removeLink(fromType, fromId, toType, toId, linkType) {
+        const result = this.db.prepare(`
+      DELETE FROM knowledge_links
+      WHERE from_type = ? AND from_id = ? AND to_type = ? AND to_id = ? AND link_type = ?
+    `).run(fromType, fromId, toType, toId, linkType);
+        return result.changes > 0;
+    }
+    /**
+     * Remove all links involving an entity (both directions).
+     */
+    removeEntityLinks(type, id) {
+        const r1 = this.db.prepare('DELETE FROM knowledge_links WHERE from_type = ? AND from_id = ?').run(type, id);
+        const r2 = this.db.prepare('DELETE FROM knowledge_links WHERE to_type = ? AND to_id = ?').run(type, id);
+        return r1.changes + r2.changes;
+    }
+    // ─── Direct Queries ────────────────────────────────────────
+    /**
+     * Get outbound links from an entity.
+     */
+    getOutbound(type, id, linkType) {
+        if (linkType) {
+            return this.db.prepare('SELECT * FROM knowledge_links WHERE from_type = ? AND from_id = ? AND link_type = ?').all(type, id, linkType).map(r => this.rowToLink(r));
+        }
+        return this.db.prepare('SELECT * FROM knowledge_links WHERE from_type = ? AND from_id = ?').all(type, id).map(r => this.rowToLink(r));
+    }
+    /**
+     * Get inbound links to an entity.
+     */
+    getInbound(type, id, linkType) {
+        if (linkType) {
+            return this.db.prepare('SELECT * FROM knowledge_links WHERE to_type = ? AND to_id = ? AND link_type = ?').all(type, id, linkType).map(r => this.rowToLink(r));
+        }
+        return this.db.prepare('SELECT * FROM knowledge_links WHERE to_type = ? AND to_id = ?').all(type, id).map(r => this.rowToLink(r));
+    }
+    /**
+     * Get all links for an entity (both directions).
+     */
+    getLinks(type, id) {
+        return this.db.prepare(`
+      SELECT * FROM knowledge_links
+      WHERE (from_type = ? AND from_id = ?) OR (to_type = ? AND to_id = ?)
+      ORDER BY created_at DESC
+    `).all(type, id, type, id).map(r => this.rowToLink(r));
+    }
+    // ─── Traversal ─────────────────────────────────────────────
+    /**
+     * Breadth-first traversal from a starting entity.
+     * Follows links in both directions up to maxDepth.
+     *
+     * @param startType - Entity type to start from
+     * @param startId - Entity ID to start from
+     * @param opts - Traversal options
+     * @returns Discovered nodes and edges
+     */
+    traverse(startType, startId, opts) {
+        const maxDepth = opts?.maxDepth ?? 3;
+        const maxResults = opts?.maxResults ?? 50;
+        const direction = opts?.direction ?? 'both';
+        const linkTypes = opts?.linkTypes;
+        const targetTypes = opts?.targetTypes;
+        const visited = new Set();
+        const nodes = [];
+        const edges = [];
+        let truncated = false;
+        // BFS queue: [type, id, depth]
+        const queue = [[startType, startId, 0]];
+        visited.add(`${startType}:${startId}`);
+        while (queue.length > 0 && nodes.length < maxResults) {
+            const [currentType, currentId, depth] = queue.shift();
+            if (depth >= maxDepth) {
+                if (depth > maxDepth)
+                    truncated = true;
+                continue;
+            }
+            // Get neighbors
+            const neighbors = [];
+            if (direction === 'outbound' || direction === 'both') {
+                const outbound = linkTypes
+                    ? this.getOutbound(currentType, currentId).filter(l => linkTypes.includes(l.linkType))
+                    : this.getOutbound(currentType, currentId);
+                for (const link of outbound) {
+                    const nodeType = link.toType;
+                    if (targetTypes && !targetTypes.includes(nodeType))
+                        continue;
+                    neighbors.push({
+                        node: {
+                            type: nodeType,
+                            id: link.toId,
+                            depth: depth + 1,
+                            linkType: link.linkType,
+                            direction: 'outbound',
+                        },
+                        link,
+                    });
+                }
+            }
+            if (direction === 'inbound' || direction === 'both') {
+                const inbound = linkTypes
+                    ? this.getInbound(currentType, currentId).filter(l => linkTypes.includes(l.linkType))
+                    : this.getInbound(currentType, currentId);
+                for (const link of inbound) {
+                    const nodeType = link.fromType;
+                    if (targetTypes && !targetTypes.includes(nodeType))
+                        continue;
+                    neighbors.push({
+                        node: {
+                            type: nodeType,
+                            id: link.fromId,
+                            depth: depth + 1,
+                            linkType: link.linkType,
+                            direction: 'inbound',
+                        },
+                        link,
+                    });
+                }
+            }
+            for (const { node, link } of neighbors) {
+                const key = `${node.type}:${node.id}`;
+                if (visited.has(key))
+                    continue;
+                visited.add(key);
+                if (nodes.length >= maxResults) {
+                    truncated = true;
+                    break;
+                }
+                nodes.push(node);
+                edges.push(link);
+                queue.push([node.type, node.id, node.depth]);
+            }
+        }
+        if (queue.length > 0)
+            truncated = true;
+        return { nodes, edges, truncated };
+    }
+    /**
+     * Find the shortest path between two entities.
+     * Uses BFS — returns null if no path exists within maxDepth.
+     */
+    findPath(fromType, fromId, toType, toId, maxDepth = 5) {
+        const visited = new Map();
+        const startKey = `${fromType}:${fromId}`;
+        const endKey = `${toType}:${toId}`;
+        visited.set(startKey, {
+            parent: null,
+            node: { type: fromType, id: fromId, depth: 0, linkType: 'start', direction: 'outbound' },
+        });
+        const queue = [[fromType, fromId, 0]];
+        while (queue.length > 0) {
+            const [currentType, currentId, depth] = queue.shift();
+            const currentKey = `${currentType}:${currentId}`;
+            if (currentKey === endKey) {
+                // Reconstruct path
+                const path = [];
+                let key = endKey;
+                while (key) {
+                    const entry = visited.get(key);
+                    if (!entry)
+                        break;
+                    path.unshift(entry.node);
+                    key = entry.parent;
+                }
+                return path;
+            }
+            if (depth >= maxDepth)
+                continue;
+            // Expand in both directions
+            const allLinks = this.getLinks(currentType, currentId);
+            for (const link of allLinks) {
+                let nextType;
+                let nextId;
+                let dir;
+                if (link.fromType === currentType && link.fromId === currentId) {
+                    nextType = link.toType;
+                    nextId = link.toId;
+                    dir = 'outbound';
+                }
+                else {
+                    nextType = link.fromType;
+                    nextId = link.fromId;
+                    dir = 'inbound';
+                }
+                const nextKey = `${nextType}:${nextId}`;
+                if (visited.has(nextKey))
+                    continue;
+                const node = {
+                    type: nextType,
+                    id: nextId,
+                    depth: depth + 1,
+                    linkType: link.linkType,
+                    direction: dir,
+                };
+                visited.set(nextKey, { parent: currentKey, node });
+                queue.push([nextType, nextId, depth + 1]);
+            }
+        }
+        return null; // No path found
+    }
+    // ─── Analytics ─────────────────────────────────────────────
+    /**
+     * Get the most connected entities (highest degree).
+     */
+    getMostConnected(opts) {
+        const limit = opts?.limit ?? 10;
+        const query = opts?.type
+            ? `
+        SELECT type, id, COUNT(*) as degree FROM (
+          SELECT from_type as type, from_id as id FROM knowledge_links WHERE from_type = ?
+          UNION ALL
+          SELECT to_type as type, to_id as id FROM knowledge_links WHERE to_type = ?
+        )
+        GROUP BY type, id
+        ORDER BY degree DESC
+        LIMIT ?
+      `
+            : `
+        SELECT type, id, COUNT(*) as degree FROM (
+          SELECT from_type as type, from_id as id FROM knowledge_links
+          UNION ALL
+          SELECT to_type as type, to_id as id FROM knowledge_links
+        )
+        GROUP BY type, id
+        ORDER BY degree DESC
+        LIMIT ?
+      `;
+        const rows = opts?.type
+            ? this.db.prepare(query).all(opts.type, opts.type, limit)
+            : this.db.prepare(query).all(limit);
+        return rows.map(r => ({
+            type: r.type,
+            id: r.id,
+            degree: r.degree,
+        }));
+    }
+    /**
+     * Count links by type.
+     */
+    getLinkStats() {
+        const rows = this.db.prepare('SELECT link_type, COUNT(*) as count FROM knowledge_links GROUP BY link_type ORDER BY count DESC').all();
+        return rows.map(r => ({
+            linkType: r.link_type,
+            count: r.count,
+        }));
+    }
+    /**
+     * Total link count.
+     */
+    getTotalLinks() {
+        const row = this.db.prepare('SELECT COUNT(*) as count FROM knowledge_links').get();
+        return row.count;
+    }
+    // ─── Helpers ───────────────────────────────────────────────
+    rowToLink(row) {
+        return {
+            id: row.id,
+            fromType: row.from_type,
+            fromId: row.from_id,
+            toType: row.to_type,
+            toId: row.to_id,
+            linkType: row.link_type,
+            createdAt: row.created_at,
+        };
+    }
+}
+//# sourceMappingURL=knowledge-graph.js.map

package/dist/knowledge-lint.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Knowledge Lint
+ *
+ * Health checks for the knowledge table:
+ *  1. Stale syntheses — decay confidence on old topic-synthesis entries
+ *  2. Orphan topics — topics with too few messages, stale > 48h
+ *  3. Coverage gaps — topics with many messages but no synthesis
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface LintResult {
+    staleDecayed: number;
+    orphansFound: number;
+    coverageGaps: string[];
+}
+/**
+ * Run lint checks on the knowledge table.
+ *
+ * 1. Stale syntheses: topic-synthesis entries where the source topic's
+ *    updated_at is older than LINT_STALE_DAYS and there are no new messages.
+ *    Marks these with confidence = 0.3.
+ *
+ * 2. Orphan topics: topics with message_count < 3 and updated_at older than 48h.
+ *    Logged but not synthesized.
+ *
+ * 3. Coverage gaps: topics with message_count >= 20 but no corresponding
+ *    knowledge entry (domain='topic-synthesis', key=topic.name).
+ */
+export declare function lintKnowledge(libraryDb: DatabaseSync): LintResult;
+//# sourceMappingURL=knowledge-lint.d.ts.map

package/dist/knowledge-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-lint.d.ts","sourceRoot":"","sources":["../src/knowledge-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,YAAY,GAAG,UAAU,CAuGjE"}

package/dist/knowledge-lint.js

@@ -0,0 +1,116 @@
+/**
+ * Knowledge Lint
+ *
+ * Health checks for the knowledge table:
+ *  1. Stale syntheses — decay confidence on old topic-synthesis entries
+ *  2. Orphan topics — topics with too few messages, stale > 48h
+ *  3. Coverage gaps — topics with many messages but no synthesis
+ */
+import { LINT_STALE_DAYS } from './topic-synthesizer.js';
+// ─── lintKnowledge ──────────────────────────────────────────────
+/**
+ * Run lint checks on the knowledge table.
+ *
+ * 1. Stale syntheses: topic-synthesis entries where the source topic's
+ *    updated_at is older than LINT_STALE_DAYS and there are no new messages.
+ *    Marks these with confidence = 0.3.
+ *
+ * 2. Orphan topics: topics with message_count < 3 and updated_at older than 48h.
+ *    Logged but not synthesized.
+ *
+ * 3. Coverage gaps: topics with message_count >= 20 but no corresponding
+ *    knowledge entry (domain='topic-synthesis', key=topic.name).
+ */
+export function lintKnowledge(libraryDb) {
+    const result = {
+        staleDecayed: 0,
+        orphansFound: 0,
+        coverageGaps: [],
+    };
+    // ── 1. Stale syntheses ─────────────────────────────────────────
+    // Find topic-synthesis knowledge entries whose source topic hasn't been
+    // updated in LINT_STALE_DAYS days.
+    try {
+        const staleSyntheses = libraryDb.prepare(`
+      SELECT k.id, k.source_ref, k.agent_id, k.key
+      FROM knowledge k
+      WHERE k.domain = 'topic-synthesis'
+        AND k.superseded_by IS NULL
+        AND k.updated_at < datetime('now', '-${LINT_STALE_DAYS} days')
+    `).all();
+        for (const entry of staleSyntheses) {
+            // Extract topic id from source_ref: "topic:<id>" or "topic:<id>:mc:<count>"
+            if (!entry.source_ref)
+                continue;
+            const match = entry.source_ref.match(/^topic:(\d+)/);
+            if (!match)
+                continue;
+            const topicId = parseInt(match[1], 10);
+            // Check if topic exists and is stale (no recent updates)
+            let topicRow;
+            try {
+                topicRow = libraryDb.prepare('SELECT updated_at, message_count FROM topics WHERE id = ?').get(topicId);
+            }
+            catch {
+                continue;
+            }
+            if (!topicRow)
+                continue;
+            // Check if topic is stale (updated_at older than LINT_STALE_DAYS)
+            const topicAge = libraryDb.prepare(`
+        SELECT CASE WHEN datetime(?) < datetime('now', '-${LINT_STALE_DAYS} days') THEN 1 ELSE 0 END AS is_stale
+      `).get(topicRow.updated_at);
+            if (topicAge.is_stale) {
+                // Decay confidence to 0.3
+                libraryDb.prepare('UPDATE knowledge SET confidence = 0.3, updated_at = datetime(\'now\') WHERE id = ?').run(entry.id);
+                result.staleDecayed++;
+            }
+        }
+    }
+    catch {
+        // Non-fatal — continue with other checks
+    }
+    // ── 2. Orphan topics ───────────────────────────────────────────
+    // Topics with message_count < 3 and updated_at > 48h ago
+    try {
+        const orphans = libraryDb.prepare(`
+      SELECT id, name, message_count, updated_at FROM topics
+      WHERE message_count < 3
+        AND updated_at < datetime('now', '-48 hours')
+    `).all();
+        result.orphansFound = orphans.length;
+        if (orphans.length > 0) {
+            console.log(`[lint] ${orphans.length} orphan topic(s) found (< 3 messages, stale > 48h): ${orphans.map(o => o.name).join(', ')}`);
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    // ── 3. Coverage gaps ───────────────────────────────────────────
+    // Topics with >= 20 messages but no synthesis in knowledge table
+    try {
+        const bigTopics = libraryDb.prepare(`
+      SELECT t.name, t.agent_id
+      FROM topics t
+      WHERE t.message_count >= 20
+    `).all();
+        for (const topic of bigTopics) {
+            const synthesis = libraryDb.prepare(`
+        SELECT id FROM knowledge
+        WHERE agent_id = ?
+          AND domain = 'topic-synthesis'
+          AND key = ?
+          AND superseded_by IS NULL
+        LIMIT 1
+      `).get(topic.agent_id, topic.name);
+            if (!synthesis) {
+                result.coverageGaps.push(topic.name);
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    return result;
+}
+//# sourceMappingURL=knowledge-lint.js.map