@psiclawops/hypermem 0.1.0 → 0.5.1

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem — Agent-Centric Memory & Context Composition Engine
+ * hypermem — Agent-Centric Memory & Context Composition Engine
  *
  * @module @psiclawops/hypermem
  *
@@ -9,6 +9,7 @@
  *   L3: vectors.db  — per-agent semantic search index (reconstructable)
  *   L4: library.db  — fleet-wide structured knowledge (crown jewel)
  */
+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 { FactStore } from './fact-store.js';
@@ -20,13 +21,15 @@ export { FleetStore } from './fleet-store.js';
 export { SystemStore } from './system-store.js';
 export { WorkStore } from './work-store.js';
 export { DesiredStateStore } from './desired-state-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 { RedisLayer } from './redis.js';
-export { Compositor } from './compositor.js';
+export { CacheLayer } from './cache.js';
+export { Compositor, applyToolGradientToWindow, canPersistReshapedHistory } 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';
-export { toProviderFormat, fromProviderFormat, userMessageToNeutral, toolResultsToNeutral, normalizeToolCallId, generateToolCallId, detectProvider, } from './provider-translator.js';
+export { toProviderFormat, fromProviderFormat, userMessageToNeutral, toolResultsToNeutral, normalizeToolCallId, generateToolCallId, detectProvider, repairToolCallPairs, } from './provider-translator.js';
 export { migrate, SCHEMA_VERSION } from './schema.js';
 export { migrateLibrary, LIBRARY_SCHEMA_VERSION } from './library-schema.js';
 export { VectorStore, generateEmbeddings } from './vector-store.js';
@@ -34,8 +37,18 @@ export { hybridSearch, buildFtsQuery } from './hybrid-retrieval.js';
 export { DocChunkStore } from './doc-chunk-store.js';
 export { WorkspaceSeeder, seedWorkspace } from './seed.js';
 export { chunkMarkdown, chunkFile, inferCollection, hashContent, ACA_COLLECTIONS } from './doc-chunker.js';
-export { crossAgentQuery, canAccess, visibilityFilter, defaultOrgRegistry, buildOrgRegistryFromDb, } from './cross-agent.js';
+export { crossAgentQuery, canAccess, visibilityFilter, defaultOrgRegistry, buildOrgRegistryFromDb, loadOrgRegistryFromDb, } from './cross-agent.js';
 export { BackgroundIndexer, createIndexer } from './background-indexer.js';
+export { runDreamingPromoter, runDreamingPassForFleet, resolveAgentWorkspacePath, DEFAULT_DREAMER_CONFIG, } from './dreaming-promoter.js';
+export { TopicSynthesizer } from './topic-synthesizer.js';
+export { WikiPageEmitter } from './wiki-page-emitter.js';
+export { lintKnowledge } from './knowledge-lint.js';
+export { buildSpawnContext } from './spawn-context.js';
+export { runNoiseSweep, runToolDecay } from './proactive-pass.js';
+export { classifyContentType, signalWeight, isSignalBearing, SIGNAL_WEIGHT } from './content-type-classifier.js';
+export { detectTopicShift, stripMessageMetadata } from './topic-detector.js';
+export { SessionTopicMap } from './session-topic-map.js';
+export { getActiveFOS, matchMOD, renderFOS, renderMOD, recordOutputMetrics, } from './fos-mod.js';
 import { DatabaseManager } from './db.js';
 import { MessageStore } from './message-store.js';
 import { FactStore } from './fact-store.js';
@@ -48,10 +61,11 @@ import { SystemStore } from './system-store.js';
 import { WorkStore } from './work-store.js';
 import { KnowledgeGraph } from './knowledge-graph.js';
 import { DesiredStateStore } from './desired-state-store.js';
-import { RedisLayer } from './redis.js';
+import { CacheLayer } from './cache.js';
 import { Compositor } from './compositor.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';
@@ -60,13 +74,10 @@ import os from 'node:os';
 const DEFAULT_CONFIG = {
     enabled: true,
     dataDir: path.join(process.env.HOME || os.homedir(), '.openclaw', 'hypermem'),
-    redis: {
-        host: 'localhost',
-        port: 6379,
+    cache: {
         keyPrefix: 'hm:',
         sessionTTL: 14400, // 4 hours — system/identity/meta slots
-        historyTTL: 86400, // 24 hours — history list outlives other slots
-        flushInterval: 1000,
+        historyTTL: 604800, // 7 days — extended for ClawCanvas display
     },
     compositor: {
         // TUNE-010 (2026-04-02): Raised from 65000 → 90000.
@@ -75,9 +86,9 @@ const DEFAULT_CONFIG = {
         // re-run composition, so 90k is safe — leaves ~30k headroom for in-flight
         // tool results on a 120k window. Budget is better spent on context quality.
         defaultTokenBudget: 90000,
-        maxHistoryMessages: 250,
-        maxFacts: 40,
-        maxCrossSessionContext: 8000,
+        maxHistoryMessages: 1000,
+        maxFacts: 28,
+        maxCrossSessionContext: 6000,
         maxRecentToolPairs: 3,
         maxProseToolPairs: 10,
         warmHistoryBudgetFraction: 0.4,
@@ -90,6 +101,8 @@ const DEFAULT_CONFIG = {
         factDecayRate: 0.01,
         episodeSignificanceThreshold: 0.5,
         periodicInterval: 300000,
+        batchSize: 128,
+        maxMessagesPerTick: 500,
     },
     embedding: {
         ollamaUrl: 'http://localhost:11434',
@@ -100,24 +113,24 @@ const DEFAULT_CONFIG = {
     },
 };
 /**
- * HyperMem — the main API facade.
+ * hypermem — the main API facade.
  *
  * Usage:
- *   const hm = await HyperMem.create({ dataDir: '~/.openclaw/hypermem' });
+ *   const hm = await hypermem.create({ dataDir: '~/.openclaw/hypermem' });
  *   await hm.record('forge', 'agent:forge:webchat:main', userMsg);
  *   const result = await hm.compose({ agentId: 'forge', sessionKey: '...', ... });
  */
 export class HyperMem {
     dbManager;
-    redis;
+    cache;
     compositor;
     config;
     constructor(config) {
         this.config = config;
         this.dbManager = new DatabaseManager({ dataDir: config.dataDir });
-        this.redis = new RedisLayer(config.redis);
+        this.cache = new CacheLayer(config.cache);
         this.compositor = new Compositor({
-            redis: this.redis,
+            cache: this.cache,
             vectorStore: null, // Set after create() when vector DB is available
             libraryDb: null, // Set after create() when library DB is available
         }, config.compositor);
@@ -130,13 +143,13 @@ export class HyperMem {
         return this.compositor.vectorStore;
     }
     /**
-     * Create and initialize a HyperMem instance.
+     * Create and initialize a hypermem instance.
      */
     static async create(config) {
         const merged = {
             ...DEFAULT_CONFIG,
             ...config,
-            redis: { ...DEFAULT_CONFIG.redis, ...config?.redis },
+            cache: { ...DEFAULT_CONFIG.cache, ...config?.cache },
             compositor: { ...DEFAULT_CONFIG.compositor, ...config?.compositor },
             indexer: { ...DEFAULT_CONFIG.indexer, ...config?.indexer },
             embedding: {
@@ -145,12 +158,12 @@ export class HyperMem {
             },
         };
         const hm = new HyperMem(merged);
-        const redisOk = await hm.redis.connect();
-        if (redisOk) {
-            console.log('[hypermem] Redis connected');
+        const cacheOk = await hm.cache.connect();
+        if (cacheOk) {
+            console.log('[hypermem] Cache connected');
         }
         else {
-            console.warn('[hypermem] Redis unavailable — running in SQLite-only mode');
+            console.warn('[hypermem] Cache unavailable — running in SQLite-only mode');
         }
         // ── Vector store init ─────────────────────────────────────
         // Attempt to wire up sqlite-vec + nomic-embed-text for semantic recall.
@@ -164,7 +177,10 @@ export class HyperMem {
                 const vs = new VectorStore(vectorDb, merged.embedding, hm.dbManager.getLibraryDb());
                 vs.ensureTables();
                 hm.compositor.setVectorStore(vs);
-                console.log('[hypermem] Vector store initialized (sqlite-vec + nomic-embed-text)');
+                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');
@@ -189,13 +205,13 @@ export class HyperMem {
             provider: opts?.provider,
             model: opts?.model,
         });
-        const neutral = userMessageToNeutral(content);
+        const neutral = userMessageToNeutral(stripMessageMetadata(content));
         const stored = store.recordMessage(conversation.id, agentId, neutral, {
             tokenCount: opts?.tokenCount,
             isHeartbeat: opts?.isHeartbeat,
         });
-        await this.redis.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
-        await this.redis.touchSession(agentId, sessionKey);
+        await this.cache.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
+        await this.cache.touchSession(agentId, sessionKey);
         return stored;
     }
     /**
@@ -211,8 +227,8 @@ export class HyperMem {
         const stored = store.recordMessage(conversation.id, agentId, message, {
             tokenCount: opts?.tokenCount,
         });
-        await this.redis.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
-        await this.redis.touchSession(agentId, sessionKey);
+        await this.cache.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
+        await this.cache.touchSession(agentId, sessionKey);
         return stored;
     }
     /**
@@ -238,6 +254,13 @@ export class HyperMem {
         const libraryDb = this.dbManager.getLibraryDb();
         await this.compositor.warmSession(agentId, sessionKey, db, { ...opts, libraryDb });
     }
+    /**
+     * Recompute the Redis hot history view from SQLite and re-apply tool gradient.
+     */
+    async refreshRedisGradient(agentId, sessionKey, tokenBudget) {
+        const db = this.dbManager.getMessageDb(agentId);
+        await this.compositor.refreshRedisGradient(agentId, sessionKey, db, tokenBudget);
+    }
     /**
      * Full-text search across all messages for an agent.
      */
@@ -363,7 +386,7 @@ export class HyperMem {
         const store = new FleetStore(db);
         const result = store.upsertAgent(id, data);
         // Invalidate cache — fire and forget
-        this.redis.invalidateFleetAgent(id).catch(() => { });
+        this.cache.invalidateFleetAgent(id).catch(() => { });
         return result;
     }
     /**
@@ -371,14 +394,14 @@ export class HyperMem {
      */
     async getFleetAgentCached(id) {
         // Try cache first
-        const cached = await this.redis.getCachedFleetAgent(id);
+        const cached = await this.cache.getCachedFleetAgent(id);
         if (cached)
             return cached;
         // Fall back to SQLite
         const agent = this.getFleetAgent(id);
         if (agent) {
             // Warm cache — fire and forget
-            this.redis.cacheFleetAgent(id, agent).catch(() => { });
+            this.cache.cacheFleetAgent(id, agent).catch(() => { });
         }
         return agent;
     }
@@ -531,7 +554,7 @@ export class HyperMem {
         const store = new DesiredStateStore(db);
         const result = store.setDesired(agentId, configKey, desiredValue, opts);
         // Invalidate cache — desired state change affects fleet view
-        this.redis.invalidateFleetAgent(agentId).catch(() => { });
+        this.cache.invalidateFleetAgent(agentId).catch(() => { });
         return result;
     }
     /**
@@ -541,7 +564,7 @@ export class HyperMem {
         const db = this.dbManager.getLibraryDb();
         const store = new DesiredStateStore(db);
         const result = store.reportActual(agentId, configKey, actualValue);
-        this.redis.invalidateFleetAgent(agentId).catch(() => { });
+        this.cache.invalidateFleetAgent(agentId).catch(() => { });
         return result;
     }
     /**
@@ -551,7 +574,7 @@ export class HyperMem {
         const db = this.dbManager.getLibraryDb();
         const store = new DesiredStateStore(db);
         const result = store.reportActualBulk(agentId, actuals);
-        this.redis.invalidateFleetAgent(agentId).catch(() => { });
+        this.cache.invalidateFleetAgent(agentId).catch(() => { });
         return result;
     }
     /**
@@ -722,7 +745,7 @@ export class HyperMem {
      */
     async getSessionCursor(agentId, sessionKey) {
         // Try Redis first (hot path)
-        const redisCursor = await this.redis.getCursor(agentId, sessionKey);
+        const redisCursor = await this.cache.getCursor(agentId, sessionKey);
         if (redisCursor)
             return redisCursor;
         // Fallback to SQLite
@@ -746,7 +769,7 @@ export class HyperMem {
         };
         // Re-warm Redis so subsequent reads are fast
         try {
-            await this.redis.setCursor(agentId, sessionKey, cursor);
+            await this.cache.setCursor(agentId, sessionKey, cursor);
         }
         catch {
             // Best-effort re-warm
@@ -976,7 +999,7 @@ export class HyperMem {
      *  - Fleet summary (counts, drift status)
      */
     async hydrateFleetCache() {
-        if (!this.redis.isConnected)
+        if (!this.cache.isConnected)
             return { agents: 0, summary: false };
         const db = this.dbManager.getLibraryDb();
         const fleetStore = new FleetStore(db);
@@ -1000,7 +1023,7 @@ export class HyperMem {
                     })),
                     desiredConfig,
                 };
-                await this.redis.cacheFleetAgent(agent.id, composite);
+                await this.cache.cacheFleetAgent(agent.id, composite);
                 hydrated++;
             }
             catch (err) {
@@ -1022,7 +1045,7 @@ export class HyperMem {
                 drift: driftSummary,
                 hydratedAt: new Date().toISOString(),
             };
-            await this.redis.cacheFleetSummary(summary);
+            await this.cache.cacheFleetSummary(summary);
         }
         catch {
             return { agents: hydrated, summary: false };
@@ -1034,9 +1057,16 @@ export class HyperMem {
      * Clean shutdown.
      */
     async close() {
-        await this.redis.disconnect();
+        await this.cache.disconnect();
         this.dbManager.close();
     }
 }
 export default HyperMem;
+export { SessionFlusher, flushSession } from './session-flusher.js';
+export { importVault, watchVault, parseObsidianNote, parseFrontmatter, extractWikilinks, extractTags, cleanObsidianMarkdown } from './obsidian-watcher.js';
+export { exportToVault } from './obsidian-exporter.js';
+export { collectMetrics, formatMetricsSummary } from './metrics-dashboard.js';
+export { getProfile, mergeProfile, PROFILES, lightProfile, standardProfile, fullProfile, extendedProfile, minimalProfile, richProfile } from './profiles.js';
+export { renderStarterFOS, resolveOutputTier } from './fos-mod.js';
+export { repairToolPairs } from './repair-tool-pairs.js';
 //# sourceMappingURL=index.js.map

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

@@ -1,5 +1,5 @@
 /**
- * HyperMem Knowledge Graph
+ * hypermem Knowledge Graph
  *
  * DAG traversal over knowledge_links in library.db.
  * Links connect entities across collections:

package/dist/knowledge-graph.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Knowledge Graph
+ * hypermem Knowledge Graph
  *
  * DAG traversal over knowledge_links in library.db.
  * Links connect entities across collections:

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

package/dist/knowledge-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Knowledge Store
+ * hypermem Knowledge Store
  *
  * Long-term structured knowledge — replaces MEMORY.md.
  * Lives in the central library DB.

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

@@ -1 +1 @@
-{"version":3,"file":"knowledge-store.d.ts","sourceRoot":"","sources":["../src/knowledge-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAuB5C,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;AAE5F,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,SAAS;IAsEZ;;OAEG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,SAAS,EAAE;IAyBd;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAUnE;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE;IAUrE;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,SAAS,EAAE;IAavE;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAUrC;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAO/D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOjC;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAwDlF"}
+{"version":3,"file":"knowledge-store.d.ts","sourceRoot":"","sources":["../src/knowledge-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAwB5C,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;AAE5F,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,SAAS;IA4EZ;;OAEG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,SAAS,EAAE;IAyBd;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAUnE;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE;IAUrE;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,SAAS,EAAE;IAavE;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAUrC;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAO/D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOjC;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAwDlF"}

package/dist/knowledge-store.js

@@ -1,11 +1,12 @@
 /**
- * HyperMem Knowledge Store
+ * hypermem Knowledge Store
  *
  * Long-term structured knowledge — replaces MEMORY.md.
  * Lives in the central library DB.
  * Knowledge entries are keyed (domain + key), versioned via superseded_by,
  * and linked to each other via knowledge_links.
  */
+import { isSafeForSharedVisibility, requiresScan } from './secret-scanner.js';
 function nowIso() {
     return new Date().toISOString();
 }
@@ -47,7 +48,12 @@ export class KnowledgeStore {
         const now = nowIso();
         const sourceType = opts?.sourceType || 'manual';
         const confidence = opts?.confidence ?? 1.0;
-        const visibility = opts?.visibility ?? 'private';
+        // Secret gate: if requested visibility is shared, verify content is clean.
+        // Downgrade to 'private' rather than reject — matches episode-store pattern.
+        let visibility = opts?.visibility ?? 'private';
+        if (requiresScan(visibility) && !isSafeForSharedVisibility(content)) {
+            visibility = 'private';
+        }
         // Find current active entry (not superseded, not expired)
         const existing = this.db.prepare(`
       SELECT * FROM knowledge