@psiclawops/hypermem 0.7.0 → 0.8.1

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAgJvC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA0H9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAgJxC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA0K9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}

package/dist/schema.js

@@ -5,7 +5,7 @@
  * Write-heavy, temporal, rotatable.
  * Contains ONLY conversation data — structured knowledge lives in library.db.
  */
-export const LATEST_SCHEMA_VERSION = 8;
+export const LATEST_SCHEMA_VERSION = 10;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -250,6 +250,51 @@ export function migrate(db) {
         db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
             .run(8, nowIso());
     }
+    // v8 → v9: Tool Artifact Store — durable storage for full tool result payloads.
+    // Transcript stubs carry an artifactId pointer; raw payload lives here so
+    // wave-guard degradation is never lossy. See specs/TOOL_ARTIFACT_STORE.md.
+    if (currentVersion < 9) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS tool_artifacts (
+        id                 TEXT PRIMARY KEY,
+        content_hash       TEXT NOT NULL,
+        agent_id           TEXT NOT NULL,
+        session_key        TEXT NOT NULL,
+        conversation_id    INTEGER REFERENCES conversations(id),
+        message_id         INTEGER REFERENCES messages(id),
+        turn_id            TEXT,
+        tool_call_id       TEXT,
+        tool_name          TEXT NOT NULL,
+        is_error           INTEGER NOT NULL DEFAULT 0,
+        content_type       TEXT NOT NULL DEFAULT 'text/plain',
+        size_bytes         INTEGER NOT NULL,
+        token_estimate     INTEGER NOT NULL,
+        payload            TEXT NOT NULL,
+        summary            TEXT,
+        created_at         TEXT NOT NULL,
+        last_used_at       TEXT NOT NULL,
+        ref_count          INTEGER NOT NULL DEFAULT 1
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_hash ON tool_artifacts(content_hash)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_session ON tool_artifacts(agent_id, session_key, created_at DESC)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_turn ON tool_artifacts(turn_id)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_tool_artifacts_tool_call ON tool_artifacts(tool_call_id)');
+        db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(9, nowIso());
+    }
+    // v9 → v10: Retention sweep — add is_sensitive flag to tool_artifacts.
+    // Enables differential TTL: sensitive artifacts expire sooner than standard ones.
+    // See: ToolArtifactStore.sweep() and ToolArtifactRetentionPolicy.
+    if (currentVersion < 10) {
+        const taCols = db.prepare('PRAGMA table_info(tool_artifacts)').all()
+            .map(r => r.name);
+        if (!taCols.includes('is_sensitive')) {
+            db.exec('ALTER TABLE tool_artifacts ADD COLUMN is_sensitive INTEGER NOT NULL DEFAULT 0');
+        }
+        db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(10, nowIso());
+    }
 }
 export { LATEST_SCHEMA_VERSION as SCHEMA_VERSION };
 //# sourceMappingURL=schema.js.map

package/dist/session-flusher.d.ts

@@ -1,7 +1,7 @@
 /**
  * session-flusher.ts
  *
- * Provides a clean, operator-safe way to flush a session's hot cache from Redis
+ * Provides a clean, operator-safe way to flush a session's hot cache
  * without touching long-term memory (facts, vectors, episodes, knowledge graph).
  *
  * Used to implement the /fresh slash command — lets users start a new unwarmed
@@ -12,7 +12,7 @@
  */
 import type { CacheLayer } from './cache.js';
 export interface FlushSessionOptions {
-    /** If true, also clears topic-level Redis keys for this session */
+    /** If true, also clears topic-level hot-cache entries for this session */
     includeTopics?: boolean;
 }
 export interface FlushSessionResult {

package/dist/session-flusher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-flusher.d.ts","sourceRoot":"","sources":["../src/session-flusher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM;IAGlC;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGzF"}
+{"version":3,"file":"session-flusher.d.ts","sourceRoot":"","sources":["../src/session-flusher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM;IAGlC;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGzF"}

package/dist/session-flusher.js

@@ -1,7 +1,7 @@
 /**
  * session-flusher.ts
  *
- * Provides a clean, operator-safe way to flush a session's hot cache from Redis
+ * Provides a clean, operator-safe way to flush a session's hot cache
  * without touching long-term memory (facts, vectors, episodes, knowledge graph).
  *
  * Used to implement the /fresh slash command — lets users start a new unwarmed

package/dist/temporal-store.js

@@ -59,11 +59,11 @@ export class TemporalStore {
         const limit = opts.limit ?? 20;
         const order = opts.order ?? 'DESC';
         const minConf = opts.minConfidence ?? 0;
-        const params = [];
+        const params = [minConf];
         const conditions = [
             'f.superseded_by IS NULL',
             'f.decay_score < 0.8',
-            `t.confidence >= ${minConf}`,
+            't.confidence >= ?',
         ];
         if (opts.agentId) {
             conditions.push('t.agent_id = ?');

package/dist/tool-artifact-store.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Tool Artifact Store
+ *
+ * Durable, addressable storage for full tool result payloads. Schema v9.
+ *
+ * Why: the wave-guard at ingest time replaces oversized tool result payloads
+ * with a small stub for pressure relief. Before this store existed, the full
+ * payload was discarded. Now the stub in the transcript carries an
+ * `artifactId` pointing at the durable copy here, and hydration is an
+ * explicit decision, not an automatic transcript rewrite.
+ *
+ * Retention is deliberately independent of transcript eviction. Artifacts
+ * outlive the messages that referenced them, and GC is a separate concern
+ * (Phase 2).
+ *
+ * See: specs/TOOL_ARTIFACT_STORE.md
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface ToolArtifactRetentionPolicy {
+    /** TTL in ms for non-sensitive artifacts (e.g. 7 * 24 * 60 * 60 * 1000). */
+    standardTtlMs: number;
+    /** TTL in ms for sensitive artifacts. Should be <= standardTtlMs. */
+    sensitiveTtlMs: number;
+    /** Optional: max artifacts to keep per (agent_id, session_key). Excess removed oldest-first. */
+    maxPerSession?: number;
+}
+export interface ToolArtifactRecord {
+    id: string;
+    contentHash: string;
+    agentId: string;
+    sessionKey: string;
+    conversationId: number | null;
+    messageId: number | null;
+    turnId: string | null;
+    toolCallId: string | null;
+    toolName: string;
+    isError: boolean;
+    contentType: string;
+    sizeBytes: number;
+    tokenEstimate: number;
+    payload: string;
+    summary: string | null;
+    createdAt: string;
+    lastUsedAt: string;
+    refCount: number;
+    isSensitive: boolean;
+}
+export interface PutToolArtifactInput {
+    agentId: string;
+    sessionKey: string;
+    conversationId?: number;
+    messageId?: number;
+    turnId?: string;
+    toolCallId?: string;
+    toolName: string;
+    isError?: boolean;
+    contentType?: string;
+    payload: string;
+    summary?: string;
+    isSensitive?: boolean;
+}
+export declare class ToolArtifactStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Insert a new artifact, or dedupe against an existing one in the same
+     * (agentId, sessionKey) scope. Dedupe is scoped to a session so distinct
+     * sessions can't leak artifact ids across each other even when payload
+     * content is identical.
+     */
+    put(input: PutToolArtifactInput): ToolArtifactRecord;
+    /** Alias for get(id) — explicit name used by the compositor hydration pass. */
+    getById(id: string): ToolArtifactRecord | null;
+    get(id: string): ToolArtifactRecord | null;
+    getByHash(agentId: string, sessionKey: string, contentHash: string): ToolArtifactRecord | null;
+    listByTurn(sessionKey: string, turnId: string): ToolArtifactRecord[];
+    listByToolCall(toolCallId: string): ToolArtifactRecord[];
+    listRecent(agentId: string, sessionKey: string, limit?: number): ToolArtifactRecord[];
+    /** Update last_used_at — call this when hydration actually surfaces the payload. */
+    touch(id: string): void;
+    /**
+     * GC sweep: delete artifacts that exceed their TTL or per-session count cap.
+     * Returns total rows deleted.
+     *
+     * Sensitive artifacts use sensitiveTtlMs (shorter); standard artifacts use
+     * standardTtlMs. Optional maxPerSession bounds row count per (agent, session)
+     * using a ROW_NUMBER() window query — oldest last_used_at removed first.
+     */
+    sweep(policy: ToolArtifactRetentionPolicy): number;
+    /**
+     * Delete artifacts whose last_used_at is older than the ISO cutoff.
+     * Returns the number of rows deleted. Phase 1: manual invocation only.
+     */
+    deleteOlderThan(isoCutoff: string): number;
+    /** Debug / ops: row count across a session. */
+    count(agentId?: string, sessionKey?: string): number;
+}
+//# sourceMappingURL=tool-artifact-store.d.ts.map

package/dist/tool-artifact-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-artifact-store.d.ts","sourceRoot":"","sources":["../src/tool-artifact-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0BhD,MAAM,WAAW,2BAA2B;IAC1C,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA0BD,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,oBAAoB,GAAG,kBAAkB;IA+FpD,+EAA+E;IAC/E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAI9C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAO1C,SAAS,CACP,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,kBAAkB,GAAG,IAAI;IAY5B,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAWpE,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAWxD,UAAU,CACR,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAW,GACjB,kBAAkB,EAAE;IAYvB,oFAAoF;IACpF,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMvB;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,2BAA2B,GAAG,MAAM;IAsClD;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAO1C,+CAA+C;IAC/C,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAcrD"}

package/dist/tool-artifact-store.js

@@ -0,0 +1,244 @@
+/**
+ * Tool Artifact Store
+ *
+ * Durable, addressable storage for full tool result payloads. Schema v9.
+ *
+ * Why: the wave-guard at ingest time replaces oversized tool result payloads
+ * with a small stub for pressure relief. Before this store existed, the full
+ * payload was discarded. Now the stub in the transcript carries an
+ * `artifactId` pointing at the durable copy here, and hydration is an
+ * explicit decision, not an automatic transcript rewrite.
+ *
+ * Retention is deliberately independent of transcript eviction. Artifacts
+ * outlive the messages that referenced them, and GC is a separate concern
+ * (Phase 2).
+ *
+ * See: specs/TOOL_ARTIFACT_STORE.md
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Simple char/4 heuristic matching src/compositor.ts estimateTokens().
+ * Kept local to avoid a cyclic import and keep the store self-contained.
+ */
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function newArtifactId() {
+    // 24-char lowercase id. Deliberately NOT a UUID — shorter, fits the stub
+    // length cap in src/degradation.ts (DEGRADATION_LIMITS.artifactId = 64).
+    return 'art_' + randomBytes(10).toString('hex');
+}
+function sha256Hex(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        contentHash: row.content_hash,
+        agentId: row.agent_id,
+        sessionKey: row.session_key,
+        conversationId: row.conversation_id ?? null,
+        messageId: row.message_id ?? null,
+        turnId: row.turn_id ?? null,
+        toolCallId: row.tool_call_id ?? null,
+        toolName: row.tool_name,
+        isError: row.is_error === 1,
+        contentType: row.content_type,
+        sizeBytes: row.size_bytes,
+        tokenEstimate: row.token_estimate,
+        payload: row.payload,
+        summary: row.summary ?? null,
+        createdAt: row.created_at,
+        lastUsedAt: row.last_used_at,
+        refCount: row.ref_count,
+        isSensitive: row.is_sensitive === 1,
+    };
+}
+export class ToolArtifactStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Insert a new artifact, or dedupe against an existing one in the same
+     * (agentId, sessionKey) scope. Dedupe is scoped to a session so distinct
+     * sessions can't leak artifact ids across each other even when payload
+     * content is identical.
+     */
+    put(input) {
+        const payload = input.payload ?? '';
+        const contentHash = sha256Hex(payload);
+        const sizeBytes = Buffer.byteLength(payload, 'utf8');
+        const tokenEstimate = estimateTokens(payload);
+        const contentType = input.contentType ?? 'text/plain';
+        const isError = input.isError ? 1 : 0;
+        const isSensitive = input.isSensitive ? 1 : 0;
+        // Dedupe within (agentId, sessionKey) — same hash bumps ref_count and
+        // updates last_used_at, returning the existing record.
+        const existing = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE agent_id = ? AND session_key = ? AND content_hash = ?
+           LIMIT 1`)
+            .get(input.agentId, input.sessionKey, contentHash);
+        if (existing) {
+            const ts = nowIso();
+            this.db
+                .prepare(`UPDATE tool_artifacts
+             SET ref_count = ref_count + 1,
+                 last_used_at = ?
+             WHERE id = ?`)
+                .run(ts, existing.id);
+            return rowToRecord({ ...existing, ref_count: existing.ref_count + 1, last_used_at: ts, is_sensitive: existing.is_sensitive ?? 0 });
+        }
+        const id = newArtifactId();
+        const ts = nowIso();
+        this.db
+            .prepare(`INSERT INTO tool_artifacts (
+            id, content_hash, agent_id, session_key,
+            conversation_id, message_id, turn_id, tool_call_id,
+            tool_name, is_error, content_type,
+            size_bytes, token_estimate, payload, summary,
+            created_at, last_used_at, ref_count, is_sensitive
+          ) VALUES (?, ?, ?, ?,
+                    ?, ?, ?, ?,
+                    ?, ?, ?,
+                    ?, ?, ?, ?,
+                    ?, ?, 1, ?)`)
+            .run(id, contentHash, input.agentId, input.sessionKey, input.conversationId ?? null, input.messageId ?? null, input.turnId ?? null, input.toolCallId ?? null, input.toolName, isError, contentType, sizeBytes, tokenEstimate, payload, input.summary ?? null, ts, ts, isSensitive);
+        return {
+            id,
+            contentHash,
+            agentId: input.agentId,
+            sessionKey: input.sessionKey,
+            conversationId: input.conversationId ?? null,
+            messageId: input.messageId ?? null,
+            turnId: input.turnId ?? null,
+            toolCallId: input.toolCallId ?? null,
+            toolName: input.toolName,
+            isError: input.isError ?? false,
+            contentType,
+            sizeBytes,
+            tokenEstimate,
+            payload,
+            summary: input.summary ?? null,
+            createdAt: ts,
+            lastUsedAt: ts,
+            refCount: 1,
+            isSensitive: input.isSensitive ?? false,
+        };
+    }
+    /** Alias for get(id) — explicit name used by the compositor hydration pass. */
+    getById(id) {
+        return this.get(id);
+    }
+    get(id) {
+        const row = this.db
+            .prepare('SELECT * FROM tool_artifacts WHERE id = ? LIMIT 1')
+            .get(id);
+        return row ? rowToRecord(row) : null;
+    }
+    getByHash(agentId, sessionKey, contentHash) {
+        const row = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE agent_id = ? AND session_key = ? AND content_hash = ?
+           ORDER BY created_at DESC
+           LIMIT 1`)
+            .get(agentId, sessionKey, contentHash);
+        return row ? rowToRecord(row) : null;
+    }
+    listByTurn(sessionKey, turnId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE session_key = ? AND turn_id = ?
+           ORDER BY created_at ASC`)
+            .all(sessionKey, turnId);
+        return rows.map(rowToRecord);
+    }
+    listByToolCall(toolCallId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE tool_call_id = ?
+           ORDER BY created_at ASC`)
+            .all(toolCallId);
+        return rows.map(rowToRecord);
+    }
+    listRecent(agentId, sessionKey, limit = 20) {
+        const rows = this.db
+            .prepare(`SELECT * FROM tool_artifacts
+           WHERE agent_id = ? AND session_key = ?
+           ORDER BY created_at DESC
+           LIMIT ?`)
+            .all(agentId, sessionKey, limit);
+        return rows.map(rowToRecord);
+    }
+    /** Update last_used_at — call this when hydration actually surfaces the payload. */
+    touch(id) {
+        this.db
+            .prepare('UPDATE tool_artifacts SET last_used_at = ? WHERE id = ?')
+            .run(nowIso(), id);
+    }
+    /**
+     * GC sweep: delete artifacts that exceed their TTL or per-session count cap.
+     * Returns total rows deleted.
+     *
+     * Sensitive artifacts use sensitiveTtlMs (shorter); standard artifacts use
+     * standardTtlMs. Optional maxPerSession bounds row count per (agent, session)
+     * using a ROW_NUMBER() window query — oldest last_used_at removed first.
+     */
+    sweep(policy) {
+        const now = Date.now();
+        const standardCutoff = new Date(now - policy.standardTtlMs).toISOString();
+        const sensitiveCutoff = new Date(now - policy.sensitiveTtlMs).toISOString();
+        const ttlResult = this.db
+            .prepare(`DELETE FROM tool_artifacts
+           WHERE (is_sensitive = 0 AND last_used_at < ?)
+              OR (is_sensitive = 1 AND last_used_at < ?)`)
+            .run(standardCutoff, sensitiveCutoff);
+        let deleted = ttlResult.changes ?? 0;
+        if (policy.maxPerSession != null) {
+            const boundResult = this.db
+                .prepare(`DELETE FROM tool_artifacts
+             WHERE id IN (
+               SELECT id FROM (
+                 SELECT id,
+                        ROW_NUMBER() OVER (
+                          PARTITION BY agent_id, session_key
+                          ORDER BY last_used_at DESC
+                        ) AS rn
+                 FROM tool_artifacts
+               )
+               WHERE rn > ?
+             )`)
+                .run(policy.maxPerSession);
+            deleted += boundResult.changes ?? 0;
+        }
+        return deleted;
+    }
+    /**
+     * Delete artifacts whose last_used_at is older than the ISO cutoff.
+     * Returns the number of rows deleted. Phase 1: manual invocation only.
+     */
+    deleteOlderThan(isoCutoff) {
+        const result = this.db
+            .prepare('DELETE FROM tool_artifacts WHERE last_used_at < ?')
+            .run(isoCutoff);
+        return Number(result.changes ?? 0);
+    }
+    /** Debug / ops: row count across a session. */
+    count(agentId, sessionKey) {
+        if (agentId && sessionKey) {
+            const row = this.db
+                .prepare('SELECT COUNT(*) AS n FROM tool_artifacts WHERE agent_id = ? AND session_key = ?')
+                .get(agentId, sessionKey);
+            return row?.n ?? 0;
+        }
+        const row = this.db.prepare('SELECT COUNT(*) AS n FROM tool_artifacts').get();
+        return row?.n ?? 0;
+    }
+}
+//# sourceMappingURL=tool-artifact-store.js.map

package/dist/topic-detector.js

@@ -234,11 +234,11 @@ export function detectTopicShift(incomingMessage, recentMessages, currentTopicId
     const contextText = contextWindow
         .map(m => m.textContent ?? '')
         .join(' ');
-    if (incomingEntities.size > 0 && contextText.length > 0) {
+    if (incomingEntities.size >= 2 && contextText.length > 0) {
         const contextEntities = extractEntities(contextText);
         const similarity = jaccardSimilarity(incomingEntities, contextEntities);
         // Low similarity + no continuation marker → likely a new topic
-        if (similarity < 0.1) {
+        if (similarity < 0.15) {
             const name = extractTopicName(text);
             return { topicId: null, isNewTopic: true, confidence: 0.6, topicName: name };
         }

package/dist/topic-store.d.ts

@@ -7,6 +7,7 @@
  */
 import type { DatabaseSync } from 'node:sqlite';
 import type { Topic, TopicStatus } from './types.js';
+export declare function normalizeTopicName(name: string): string;
 export declare class TopicStore {
     private readonly db;
     constructor(db: DatabaseSync);
@@ -14,6 +15,11 @@ export declare class TopicStore {
      * Create a new topic.
      */
     create(agentId: string, name: string, description?: string, visibility?: string): Topic;
+    /**
+     * Find an existing topic by name (case-insensitive) or create a new one.
+     * Prevents duplicate topics for the same logical concept.
+     */
+    findOrCreate(agentId: string, rawName: string, description?: string, visibility?: string): Topic;
     /**
      * Touch a topic — update activity tracking.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"topic-store.d.ts","sourceRoot":"","sources":["../src/topic-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqBrD,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK;IAwBvF;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAE,MAAU,GAAG,IAAI;IAY3E;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,KAAK,EAAE;IAWvD;;OAEG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9C,KAAK,EAAE;IAoBV;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,KAAK,EAAE;IAanE;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAW,GAAG,MAAM;IAYpE;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,GAAE,MAAU,GAAG,MAAM;CAWnE"}
+{"version":3,"file":"topic-store.d.ts","sourceRoot":"","sources":["../src/topic-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAmBrD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGvD;AAqBD,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK;IAwBvF;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK;IAkBhG;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAE,MAAU,GAAG,IAAI;IAY3E;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,KAAK,EAAE;IAWvD;;OAEG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9C,KAAK,EAAE;IAoBV;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,KAAK,EAAE;IAanE;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAW,GAAG,MAAM;IAYpE;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,GAAE,MAAU,GAAG,MAAM;CAWnE"}

package/dist/topic-store.js

@@ -5,6 +5,26 @@
  * can span multiple sessions and channels.
  * Lives in the central library DB.
  */
+/**
+ * Normalize a topic name for dedup purposes.
+ * Preserves casing of known product names; lowercases everything else.
+ */
+const KNOWN_NAMES = {
+    hypermem: 'HyperMem',
+    hyperbuilder: 'HyperBuilder',
+    clawcanvas: 'ClawCanvas',
+    clawdash: 'ClawDash',
+    clawdispatch: 'ClawDispatch',
+    clawtext: 'ClawText',
+    clawtomation: 'ClawTomation',
+    clawcouncil: 'ClawCouncil',
+    openclaw: 'OpenClaw',
+    clawhub: 'ClawHub',
+};
+export function normalizeTopicName(name) {
+    const lower = name.trim().toLowerCase();
+    return KNOWN_NAMES[lower] ?? name.trim();
+}
 function nowIso() {
     return new Date().toISOString();
 }
@@ -50,6 +70,25 @@ export class TopicStore {
             updatedAt: now,
         };
     }
+    /**
+     * Find an existing topic by name (case-insensitive) or create a new one.
+     * Prevents duplicate topics for the same logical concept.
+     */
+    findOrCreate(agentId, rawName, description, visibility) {
+        const name = normalizeTopicName(rawName);
+        const existing = this.db.prepare(`
+      SELECT * FROM topics
+      WHERE agent_id = ?
+        AND lower(name) = lower(?)
+        AND status != 'closed'
+      ORDER BY updated_at DESC
+      LIMIT 1
+    `).get(agentId, name);
+        if (existing) {
+            return parseTopicRow(existing);
+        }
+        return this.create(agentId, name, description, visibility);
+    }
     /**
      * Touch a topic — update activity tracking.
      */