@psiclawops/hypermem 0.7.0 → 0.8.0

package/dist/index.js

@@ -4,7 +4,7 @@
  * @module @psiclawops/hypermem
  *
  * Architecture:
- *   L1: Redis       — hot session working memory
+ *   L1: CacheLayer  — SQLite `:memory:` hot session working memory
  *   L2: messages.db — per-agent conversation log (rotatable)
  *   L3: vectors.db  — per-agent semantic search index (reconstructable)
  *   L4: library.db  — fleet-wide structured knowledge (crown jewel)
@@ -12,6 +12,7 @@
 export { ENGINE_VERSION, MIN_NODE_VERSION, MIN_REDIS_VERSION, SQLITE_VEC_VERSION, MAIN_SCHEMA_VERSION, LIBRARY_SCHEMA_VERSION_EXPORT, HYPERMEM_COMPAT_VERSION, SCHEMA_COMPAT } from './version.js';
 export { DatabaseManager } from './db.js';
 export { MessageStore } from './message-store.js';
+export { ToolArtifactStore } from './tool-artifact-store.js';
 export { FactStore } from './fact-store.js';
 export { KnowledgeStore } from './knowledge-store.js';
 export { TopicStore } from './topic-store.js';
@@ -20,14 +21,28 @@ export { PreferenceStore } from './preference-store.js';
 export { FleetStore } from './fleet-store.js';
 export { SystemStore } from './system-store.js';
 export { WorkStore } from './work-store.js';
-export { ensureContextSchema, getActiveContext, getOrCreateActiveContext, updateContextHead, archiveContext, rotateSessionContext } from './context-store.js';
+export { ensureContextSchema, getActiveContext, getOrCreateActiveContext, updateContextHead, archiveContext, rotateSessionContext, getContextById, getArchivedContexts, getArchivedContext, getContextLineage, getForkChildren } from './context-store.js';
 export { DesiredStateStore } from './desired-state-store.js';
 export { ExpertiseStore } from './expertise-store.js';
 export { evictStaleContent, DEFAULT_EVICTION_CONFIG } from './image-eviction.js';
 export { KnowledgeGraph } from './knowledge-graph.js';
 export { RateLimiter, createRateLimitedEmbedder } from './rate-limiter.js';
 export { CacheLayer } from './cache.js';
-export { Compositor, applyToolGradientToWindow, canPersistReshapedHistory, OPENCLAW_BOOTSTRAP_FILES } from './compositor.js';
+export { TRIM_SOFT_TARGET, TRIM_GROWTH_THRESHOLD, TRIM_HEADROOM_FRACTION, TRIM_BUDGET_POLICY, resolveTrimBudgets, } from './budget-policy.js';
+// ── Phase C0.2: Canonical degradation contracts ───────────────────────────────
+export { 
+// Reason enum + all values
+DEGRADATION_REASONS, DEGRADATION_LIMITS, isDegradationReason, isReplayState, 
+// Tool-chain stub
+formatToolChainStub, parseToolChainStub, isToolChainStub, 
+// Artifact reference
+formatArtifactRef, parseArtifactRef, isArtifactRef, 
+// Replay marker
+formatReplayMarker, parseReplayMarker, isReplayMarker, 
+// Generic detector
+isDegradedContent, } from './degradation.js';
+export { REPLAY_RECOVERY_POLICY, decideReplayRecovery, isColdRedisReplay, isReplayRecovered, } from './replay-recovery.js';
+export { Compositor, applyToolGradientToWindow, canPersistReshapedHistory, OPENCLAW_BOOTSTRAP_FILES, resolveToolChainEjections } from './compositor.js';
 export { TRIGGER_REGISTRY, TRIGGER_REGISTRY_VERSION, TRIGGER_REGISTRY_HASH, DEFAULT_TRIGGERS, matchTriggers, } from './trigger-registry.js';
 export { ensureCompactionFenceSchema, updateCompactionFence, getCompactionFence, getCompactionEligibility, getCompactableMessages, } from './compaction-fence.js';
 export { verifyPreservation, verifyPreservationFromVectors, } from './preservation-gate.js';
@@ -66,12 +81,14 @@ import { KnowledgeGraph } from './knowledge-graph.js';
 import { DesiredStateStore } from './desired-state-store.js';
 import { CacheLayer } from './cache.js';
 import { Compositor } from './compositor.js';
+import { getArchivedContexts } from './context-store.js';
 import { VectorStore } from './vector-store.js';
 import { userMessageToNeutral, fromProviderFormat } from './provider-translator.js';
 import { stripMessageMetadata } from './topic-detector.js';
 import { DocChunkStore } from './doc-chunk-store.js';
 import { WorkspaceSeeder } from './seed.js';
 import { crossAgentQuery, buildOrgRegistryFromDb } from './cross-agent.js';
+import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 const DEFAULT_CONFIG = {
@@ -80,7 +97,7 @@ const DEFAULT_CONFIG = {
     cache: {
         keyPrefix: 'hm:',
         sessionTTL: 14400, // 4 hours — system/identity/meta slots
-        historyTTL: 604800, // 7 days — extended for ClawCanvas display
+        historyTTL: 604800, // 7 days — extended for canvas display
     },
     compositor: {
         // TUNE-010 (2026-04-02): Raised from 65000 → 90000.
@@ -108,22 +125,214 @@ const DEFAULT_CONFIG = {
         maxMessagesPerTick: 500,
     },
     embedding: {
-        provider: 'openai',
+        provider: 'ollama',
         ollamaUrl: 'http://localhost:11434',
-        openaiBaseUrl: 'https://openrouter.ai/api/v1',
-        model: 'qwen/qwen3-embedding-8b',
-        dimensions: 4096,
-        timeout: 15000,
-        batchSize: 100,
+        model: 'nomic-embed-text',
+        dimensions: 768,
+        timeout: 10000,
+        batchSize: 32,
     },
 };
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function normalizeAgentId(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function parseIdentityField(markdown, label) {
+    const pattern = new RegExp(`^\\s*-\\s+\\*\\*${escapeRegExp(label)}:\\*\\*\\s*(.+?)\\s*$`, 'mi');
+    const match = markdown.match(pattern);
+    return match?.[1]?.trim() || null;
+}
+function parseSoulName(markdown) {
+    const anchor = markdown.match(/You are \*\*([^*]+)\*\*/);
+    if (anchor?.[1])
+        return anchor[1].trim();
+    const heading = markdown.match(/^#\s+SOUL\.md\s+[—-]\s+([^,\n]+)/m);
+    return heading?.[1]?.trim() || null;
+}
+function parseSoulRole(markdown) {
+    const anchor = markdown.match(/You are \*\*[^*]+\*\*\s+[—-]\s+([^\.\n]+)/);
+    return anchor?.[1]?.trim() || null;
+}
+function inferTierFromRole(role) {
+    const lower = (role || '').toLowerCase();
+    if (!lower)
+        return 'unknown';
+    if (lower.includes('council') || lower.includes(' seat'))
+        return 'council';
+    if (lower.includes('director'))
+        return 'director';
+    if (lower.includes('specialist') || lower.includes('aide-de-camp'))
+        return 'specialist';
+    return 'unknown';
+}
+function parseReportTargets(raw) {
+    if (!raw)
+        return [];
+    const stripped = raw.replace(/\([^)]*\)/g, ' ');
+    const parts = stripped
+        .split(/\s*(?:\+|,|\/|&|\band\b)\s*/i)
+        .map(part => normalizeAgentId(part))
+        .filter(Boolean);
+    return [...new Set(parts)];
+}
+function mergeStartupCandidate(target, partial) {
+    const existing = target.get(partial.agentId);
+    if (!existing) {
+        target.set(partial.agentId, {
+            agentId: partial.agentId,
+            displayName: partial.displayName || partial.agentId,
+            tier: partial.tier || 'unknown',
+            orgId: partial.orgId ?? null,
+            reportsTo: partial.reportsTo ?? null,
+            reportTargets: partial.reportTargets ? [...partial.reportTargets] : [],
+            metadata: partial.metadata ?? null,
+        });
+        return;
+    }
+    if (partial.displayName && existing.displayName === existing.agentId) {
+        existing.displayName = partial.displayName;
+    }
+    if (partial.tier && existing.tier === 'unknown') {
+        existing.tier = partial.tier;
+    }
+    if (partial.orgId && !existing.orgId) {
+        existing.orgId = partial.orgId;
+    }
+    if (partial.reportsTo && !existing.reportsTo) {
+        existing.reportsTo = partial.reportsTo;
+    }
+    if (partial.reportTargets?.length) {
+        existing.reportTargets = [...new Set([...existing.reportTargets, ...partial.reportTargets])];
+    }
+    if (partial.metadata) {
+        existing.metadata = { ...(existing.metadata ?? {}), ...partial.metadata };
+    }
+}
+function discoverStartupFleetCandidates(dbManager, opts = {}) {
+    const homeDir = process.env.HOME || os.homedir();
+    const workspaceRoots = opts.workspaceRoots ?? [
+        path.join(homeDir, '.openclaw', 'workspace'),
+        path.join(homeDir, '.openclaw', 'workspace'),
+    ];
+    const candidates = new Map();
+    for (const root of workspaceRoots) {
+        if (!fs.existsSync(root))
+            continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(root, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const workspacePath = path.join(root, entry.name);
+            const identityPath = path.join(workspacePath, 'IDENTITY.md');
+            const soulPath = path.join(workspacePath, 'SOUL.md');
+            if (!fs.existsSync(identityPath) && !fs.existsSync(soulPath))
+                continue;
+            let identityText = '';
+            let soulText = '';
+            try {
+                if (fs.existsSync(identityPath))
+                    identityText = fs.readFileSync(identityPath, 'utf8');
+            }
+            catch { }
+            try {
+                if (fs.existsSync(soulPath))
+                    soulText = fs.readFileSync(soulPath, 'utf8');
+            }
+            catch { }
+            const displayName = parseIdentityField(identityText, 'Name') ||
+                parseSoulName(soulText) ||
+                entry.name;
+            const role = parseIdentityField(identityText, 'Role') ||
+                parseSoulRole(soulText) ||
+                null;
+            const reportTargets = parseReportTargets(parseIdentityField(identityText, 'Reports to'));
+            const agentId = normalizeAgentId(entry.name || displayName);
+            if (!agentId)
+                continue;
+            mergeStartupCandidate(candidates, {
+                agentId,
+                displayName,
+                tier: inferTierFromRole(role),
+                reportTargets,
+                metadata: {
+                    startupSeed: {
+                        source: 'workspace-identity',
+                        workspacePath,
+                        reportsToRaw: reportTargets,
+                    },
+                },
+            });
+        }
+    }
+    if (opts.includeMessageDbAgents !== false) {
+        for (const agentId of dbManager.listAgents()) {
+            mergeStartupCandidate(candidates, {
+                agentId,
+                displayName: agentId,
+                tier: 'unknown',
+                metadata: {
+                    startupSeed: {
+                        source: 'message-db',
+                    },
+                },
+            });
+        }
+    }
+    const resolved = [...candidates.values()];
+    const knownIds = new Set(resolved.map(candidate => candidate.agentId));
+    const councilIds = new Set(resolved
+        .filter(candidate => candidate.tier === 'council')
+        .map(candidate => candidate.agentId));
+    for (const candidate of resolved) {
+        const preferredLead = candidate.reportTargets.find(target => councilIds.has(target)) ||
+            candidate.reportTargets.find(target => knownIds.has(target)) ||
+            null;
+        if (candidate.tier === 'council' && !candidate.orgId) {
+            candidate.orgId = `${candidate.agentId}-org`;
+        }
+        if (candidate.tier === 'director' && preferredLead) {
+            candidate.reportsTo = preferredLead;
+            if (!candidate.orgId) {
+                candidate.orgId = `${preferredLead}-org`;
+            }
+        }
+        if (!candidate.reportsTo && preferredLead && candidate.tier !== 'director') {
+            candidate.reportsTo = preferredLead;
+        }
+        // Null out reportsTo if it points outside the known fleet (e.g. a human operator ID)
+        if (candidate.reportsTo && !knownIds.has(candidate.reportsTo)) {
+            candidate.reportsTo = null;
+        }
+        candidate.metadata = {
+            ...(candidate.metadata ?? {}),
+            startupSeed: {
+                ...(candidate.metadata ?? {}).startupSeed,
+                derivedOrgId: candidate.orgId,
+                derivedReportsTo: candidate.reportsTo,
+            },
+        };
+    }
+    return resolved.sort((a, b) => a.agentId.localeCompare(b.agentId));
+}
 /**
  * hypermem — the main API facade.
  *
  * Usage:
  *   const hm = await hypermem.create({ dataDir: '~/.openclaw/hypermem' });
- *   await hm.record('agent1', 'agent:agent1:webchat:main', userMsg);
- *   const result = await hm.compose({ agentId: 'agent1', sessionKey: '...', ... });
+ *   await hm.record('alice', 'agent:alice:webchat:main', userMsg);
+ *   const result = await hm.compose({ agentId: 'alice', sessionKey: '...', ... });
  */
 export class HyperMem {
     dbManager;
@@ -176,23 +385,43 @@ export class HyperMem {
         // hybridSearch() continues in FTS5-only mode.
         // The vector store is shared (not per-agent) — facts/episodes from all agents
         // are indexed together, keyed by (source_table, source_id).
-        try {
-            const vectorDb = hm.dbManager.getSharedVectorDb();
-            if (vectorDb) {
-                const vs = new VectorStore(vectorDb, merged.embedding, hm.dbManager.getLibraryDb());
-                vs.ensureTables();
-                hm.compositor.setVectorStore(vs);
-                const embeddingDesc = merged.embedding.provider === 'openai'
-                    ? `${merged.embedding.openaiBaseUrl?.includes('openrouter') ? 'openrouter' : 'openai'}/${merged.embedding.model ?? 'text-embedding-3-small'}`
-                    : `ollama/${merged.embedding.model ?? 'nomic-embed-text'}`;
-                console.log(`[hypermem] Vector store initialized (sqlite-vec + ${embeddingDesc})`);
+        if (merged.embedding.provider === 'none') {
+            console.log('[hypermem] Embedding provider: none — semantic search disabled, using FTS5 fallback');
+        }
+        else {
+            try {
+                const vectorDb = hm.dbManager.getSharedVectorDb();
+                if (vectorDb) {
+                    const vs = new VectorStore(vectorDb, merged.embedding, hm.dbManager.getLibraryDb());
+                    vs.ensureTables();
+                    hm.compositor.setVectorStore(vs);
+                    const embeddingDesc = merged.embedding.provider === 'openai'
+                        ? `${merged.embedding.openaiBaseUrl?.includes('openrouter') ? 'openrouter' : 'openai'}/${merged.embedding.model ?? 'text-embedding-3-small'}`
+                        : `ollama/${merged.embedding.model ?? 'nomic-embed-text'}`;
+                    console.log(`[hypermem] Vector store initialized (sqlite-vec + ${embeddingDesc})`);
+                }
+                else {
+                    console.warn('[hypermem] sqlite-vec unavailable — semantic recall in FTS5-only mode');
+                }
             }
-            else {
-                console.warn('[hypermem] sqlite-vec unavailable — semantic recall in FTS5-only mode');
+            catch (err) {
+                console.warn('[hypermem] Vector store init failed (non-fatal):', err.message);
             }
         }
-        catch (err) {
-            console.warn('[hypermem] Vector store init failed (non-fatal):', err.message);
+        const autoStartupFleetSeeding = merged.startupFleetSeeding !== false &&
+            !path.resolve(merged.dataDir).startsWith(path.resolve(os.tmpdir()) + path.sep);
+        if (autoStartupFleetSeeding) {
+            try {
+                const startupSeed = await hm.seedFleetAgentsOnStartup();
+                if (startupSeed.discovered > 0) {
+                    console.log(`[hypermem] Startup fleet seed: ${startupSeed.inserted} inserted, ` +
+                        `${startupSeed.updated} updated, ${startupSeed.skipped} unchanged, ` +
+                        `${startupSeed.orgsCreated} orgs, ${startupSeed.hydratedAgents} cached`);
+                }
+            }
+            catch (err) {
+                console.warn('[hypermem] Startup fleet seed failed (non-fatal):', err.message);
+            }
         }
         return hm;
     }
@@ -267,6 +496,67 @@ export class HyperMem {
         const libraryDb = this.dbManager.getLibraryDb();
         return this.compositor.compose(request, db, libraryDb);
     }
+    // ─── Tool Artifacts (L2: per-agent, schema v9) ───────────────────
+    /**
+     * Persist a full tool result payload and return the durable record.
+     * Used by the plugin wave-guard to capture payloads before stubbing the
+     * transcript. Dedupes by content hash within the (agentId, sessionKey)
+     * scope — identical payloads bump ref_count on the existing row.
+     */
+    async recordToolArtifact(agentId, sessionKey, input) {
+        const db = this.dbManager.getMessageDb(agentId);
+        this.dbManager.ensureAgent(agentId);
+        const { ToolArtifactStore } = await import('./tool-artifact-store.js');
+        const store = new ToolArtifactStore(db);
+        return store.put({ ...input, agentId, sessionKey });
+    }
+    /** Fetch a tool artifact by id. Returns null if unknown. */
+    async getToolArtifact(agentId, artifactId) {
+        const db = this.dbManager.getMessageDb(agentId);
+        const { ToolArtifactStore } = await import('./tool-artifact-store.js');
+        const store = new ToolArtifactStore(db);
+        const record = store.get(artifactId);
+        if (record)
+            store.touch(artifactId);
+        return record;
+    }
+    /** List tool artifacts for a specific turn. */
+    async listToolArtifactsByTurn(agentId, sessionKey, turnId) {
+        const db = this.dbManager.getMessageDb(agentId);
+        const { ToolArtifactStore } = await import('./tool-artifact-store.js');
+        const store = new ToolArtifactStore(db);
+        return store.listByTurn(sessionKey, turnId);
+    }
+    // ─── Archived Mining (L2: Messages) ─────────────────────────
+    /**
+     * List archived or forked contexts for an agent.
+     *
+     * operator-safe enumeration path. This is the approved archived-context
+     * listing surface. Active composition remains separate.
+     */
+    listArchivedContexts(agentId, opts) {
+        const db = this.dbManager.getMessageDb(agentId);
+        return getArchivedContexts(db, agentId, opts);
+    }
+    /**
+     * Mine a single archived or forked context through the archived-mining
+     * surface. This does not widen active composition.
+     */
+    mineArchivedContext(agentId, query) {
+        const db = this.dbManager.getMessageDb(agentId);
+        const store = new MessageStore(db);
+        return store.mineArchivedContext(query);
+    }
+    /**
+     * Mine multiple archived or forked contexts through the capped archived-
+     * mining surface. This does not expose raw DAG helpers and does not widen
+     * active composition.
+     */
+    mineArchivedContexts(agentId, contextIds, opts) {
+        const db = this.dbManager.getMessageDb(agentId);
+        const store = new MessageStore(db);
+        return store.mineArchivedContexts(contextIds, opts);
+    }
     /**
      * Warm a session from SQLite into Redis.
      */
@@ -278,9 +568,9 @@ export class HyperMem {
     /**
      * Recompute the Redis hot history view from SQLite and re-apply tool gradient.
      */
-    async refreshRedisGradient(agentId, sessionKey, tokenBudget) {
+    async refreshRedisGradient(agentId, sessionKey, tokenBudget, historyDepth) {
         const db = this.dbManager.getMessageDb(agentId);
-        await this.compositor.refreshRedisGradient(agentId, sessionKey, db, tokenBudget);
+        await this.compositor.refreshRedisGradient(agentId, sessionKey, db, tokenBudget, historyDepth);
     }
     /**
      * Full-text search across all messages for an agent.
@@ -1010,7 +1300,93 @@ export class HyperMem {
         const store = new DocChunkStore(db);
         return store.listSources(opts);
     }
-    // ─── Fleet Cache Hydration ──────────────────────────────────
+    // ─── Fleet Startup Seeding + Cache Hydration ────────────────
+    /**
+     * Seed fleet agents from known workspace identity files and existing
+     * message-db agent directories, then optionally hydrate the Redis fleet cache.
+     *
+     * The sweep is idempotent: existing rows are only updated when startup-discovered
+     * values differ, so repeated boots do not duplicate or churn fleet rows.
+     */
+    async seedFleetAgentsOnStartup(opts = {}) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        const discovered = discoverStartupFleetCandidates(this.dbManager, opts);
+        let inserted = 0;
+        let updated = 0;
+        let skipped = 0;
+        let orgsCreated = 0;
+        for (const candidate of discovered) {
+            const existing = store.getAgent(candidate.agentId);
+            const mergedMetadata = {
+                ...(existing?.metadata ?? {}),
+                ...(candidate.metadata ?? {}),
+            };
+            if (!existing) {
+                store.upsertAgent(candidate.agentId, {
+                    displayName: candidate.displayName,
+                    tier: candidate.tier,
+                    orgId: candidate.orgId ?? undefined,
+                    reportsTo: candidate.reportsTo ?? undefined,
+                    status: 'active',
+                    metadata: Object.keys(mergedMetadata).length > 0 ? mergedMetadata : undefined,
+                });
+                inserted++;
+                continue;
+            }
+            const patch = {};
+            if (candidate.displayName && candidate.displayName !== existing.displayName) {
+                patch.displayName = candidate.displayName;
+            }
+            if (candidate.tier && candidate.tier !== 'unknown' && candidate.tier !== existing.tier) {
+                patch.tier = candidate.tier;
+            }
+            if (candidate.orgId && candidate.orgId !== existing.orgId) {
+                patch.orgId = candidate.orgId;
+            }
+            if (candidate.reportsTo && candidate.reportsTo !== existing.reportsTo) {
+                patch.reportsTo = candidate.reportsTo;
+            }
+            if (JSON.stringify(mergedMetadata) !== JSON.stringify(existing.metadata ?? {})) {
+                patch.metadata = mergedMetadata;
+            }
+            if (Object.keys(patch).length === 0) {
+                skipped++;
+                continue;
+            }
+            store.upsertAgent(candidate.agentId, patch);
+            updated++;
+        }
+        for (const candidate of discovered) {
+            if (!candidate.orgId)
+                continue;
+            if (store.getOrg(candidate.orgId))
+                continue;
+            if (candidate.tier !== 'council')
+                continue;
+            store.upsertOrg(candidate.orgId, {
+                name: `${candidate.displayName} Org`,
+                leadAgentId: candidate.agentId,
+            });
+            orgsCreated++;
+        }
+        let hydratedAgents = 0;
+        let hydratedSummary = false;
+        if (opts.hydrateCache !== false) {
+            const hydrated = await this.hydrateFleetCache();
+            hydratedAgents = hydrated.agents;
+            hydratedSummary = hydrated.summary;
+        }
+        return {
+            discovered: discovered.length,
+            inserted,
+            updated,
+            skipped,
+            orgsCreated,
+            hydratedAgents,
+            hydratedSummary,
+        };
+    }
     /**
      * Hydrate the Redis fleet cache from library.db.
      * Call on gateway startup to warm the cache for dashboard queries.

package/dist/knowledge-lint.d.ts

@@ -10,8 +10,10 @@ import type { DatabaseSync } from 'node:sqlite';
 export interface LintResult {
     staleDecayed: number;
     orphansFound: number;
+    orphansPruned: number;
     coverageGaps: string[];
 }
+export declare const ORPHAN_PRUNE_DAYS = 14;
 /**
  * Run lint checks on the knowledge table.
  *

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

@@ -1 +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"}
+{"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,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAID,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAIpC;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,YAAY,GAAG,UAAU,CA8IjE"}

package/dist/knowledge-lint.js

@@ -7,6 +7,9 @@
  *  3. Coverage gaps — topics with many messages but no synthesis
  */
 import { LINT_STALE_DAYS } from './topic-synthesizer.js';
+// Orphan topics older than this many days are eligible for pruning.
+// 48h = report threshold, 14d = prune threshold (conservative).
+export const ORPHAN_PRUNE_DAYS = 14;
 // ─── lintKnowledge ──────────────────────────────────────────────
 /**
  * Run lint checks on the knowledge table.
@@ -25,6 +28,7 @@ export function lintKnowledge(libraryDb) {
     const result = {
         staleDecayed: 0,
         orphansFound: 0,
+        orphansPruned: 0,
         coverageGaps: [],
     };
     // ── 1. Stale syntheses ─────────────────────────────────────────
@@ -80,7 +84,42 @@ export function lintKnowledge(libraryDb) {
     `).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(', ')}`);
+            const sample = orphans.slice(0, 10).map(o => o.name).join(', ');
+            const remainder = Math.max(0, orphans.length - 10);
+            console.log(`[lint] ${orphans.length} orphan topic(s) found (< 3 messages, stale > 48h)` +
+                (sample ? `; sample: ${sample}` : '') +
+                (remainder > 0 ? `; +${remainder} more` : ''));
+        }
+        // Prune orphan topics older than ORPHAN_PRUNE_DAYS (conservative cleanup).
+        // Safety: only prune topics with no knowledge-synthesis entries and no facts
+        // referencing them (via source_ref 'topic:<id>' pattern).
+        try {
+            const prunable = libraryDb.prepare(`
+        SELECT t.id, t.name FROM topics t
+        WHERE t.message_count < 3
+          AND t.updated_at < datetime('now', '-' || ? || ' days')
+          AND NOT EXISTS (
+            SELECT 1 FROM knowledge k
+            WHERE k.agent_id = t.agent_id
+              AND k.domain = 'topic-synthesis'
+              AND k.key = t.name
+              AND k.superseded_by IS NULL
+          )
+          AND NOT EXISTS (
+            SELECT 1 FROM facts f
+            WHERE f.source_ref LIKE 'topic:' || t.id || '%'
+          )
+      `).all(ORPHAN_PRUNE_DAYS);
+            if (prunable.length > 0) {
+                const ids = prunable.map(p => p.id);
+                const placeholders = ids.map(() => '?').join(',');
+                libraryDb.prepare(`DELETE FROM topics WHERE id IN (${placeholders})`).run(...ids);
+                result.orphansPruned = prunable.length;
+                console.log(`[lint] pruned ${prunable.length} orphan topic(s) (< 3 messages, stale > ${ORPHAN_PRUNE_DAYS}d, no syntheses or facts)`);
+            }
+        }
+        catch (err) {
+            console.warn('[lint] orphan prune failed (non-fatal):', err.message);
         }
     }
     catch {

package/dist/library-schema.d.ts

@@ -16,7 +16,12 @@
  *   9. Work items (fleet kanban)
  *  10. Topics (cross-session thread tracking)
  */
-import type { DatabaseSync } from 'node:sqlite';
-export declare const LIBRARY_SCHEMA_VERSION = 15;
+import { DatabaseSync } from 'node:sqlite';
+export declare const LIBRARY_SCHEMA_VERSION = 19;
+export declare function repairLibraryDb(dbPath: string): {
+    repaired: boolean;
+    backupPath?: string;
+    message: string;
+};
 export declare function migrateLibrary(db: DatabaseSync, engineVersion?: string): void;
 //# sourceMappingURL=library-schema.d.ts.map

package/dist/library-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library-schema.d.ts","sourceRoot":"","sources":["../src/library-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAy5BzC,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CA6P7E"}
+{"version":3,"file":"library-schema.d.ts","sourceRoot":"","sources":["../src/library-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAo6BzC,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAkF3G;AAID,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAuZ7E"}