@onenomad/engram-mcp 1.0.0 → 2.0.0

package/dist/source-dedup.js

@@ -1,148 +1,148 @@
-/**
- * Session-scoped same-source ingest dedup.
- *
- * Agents in long sessions repeatedly re-read stable files, re-poll
- * unchanged endpoints, and re-list the same directories. Each re-ingest
- * goes through the full chunk → embed → save pipeline even though the
- * content hasn't moved. On CPU embeddings (Engram's default backend),
- * a 20K-token re-read can cost 5–15 seconds; multiplied across a
- * 50-step agent run that's significant wall-clock burn.
- *
- * The existing 0.75-similarity dedup (in `server.ts`'s memory_ingest
- * tool handler) catches semantic duplicates, but does so against the
- * ENTIRE memory store — and at write-time it actually trips on
- * incidentally-similar memories (a fact about Pyre at 0.78 similarity
- * to a fact about Engram). It also requires the new content to be
- * embedded first, so it doesn't save the embedding cost.
- *
- * This module is the cheaper, more conservative path:
- *   - Scoped to a single source identifier (file path, URL, etc.).
- *   - Hash-based equality (SHA-256 of trimmed content) — exact match
- *     only, no false positives.
- *   - In-memory LRU keyed by `source` → list of recent content hashes.
- *   - Bounded: max 64 sources tracked, max 8 hashes per source.
- *
- * When an ingest hits the dedup cache, the caller can skip embedding
- * AND skip the disk write — return the cached chunk id. Agent's
- * conversation history stays internally consistent (same id for same
- * content), and the wall-clock cost drops from "embed + save" to a
- * map lookup.
- *
- * Process-scoped intentionally: the persistence layer doesn't need
- * to know about this. Engram restart resets the cache — first ingest
- * after restart goes through the full pipeline, which is fine.
- */
-import { createHash } from 'node:crypto';
-const MAX_SOURCES = 64;
-const MAX_PER_SOURCE = 8;
-export class SourceDedupCache {
-    /** sourceKey → list of recent (hash, chunkId) entries, MRU first. */
-    bySource = new Map();
-    /** Cache hit count since boot. Useful for telemetry. */
-    hits = 0;
-    /** Cache miss count since boot. */
-    misses = 0;
-    /**
-     * Hash trimmed content. Stable across ingest calls for the same
-     * payload — that's the whole point.
-     */
-    static hashContent(content) {
-        return createHash('sha256').update(content.trim()).digest('hex');
-    }
-    /**
-     * Look up a (source, content) pair. Returns the cached entry on hit
-     * or null on miss. Does NOT promote the entry on read — promote on
-     * write only, so a hit doesn't reset its LRU position.
-     */
-    lookup(source, content) {
-        if (!source) {
-            // No source key → no scoping → don't dedup. The caller's
-            // existing semantic-similarity dedup is the right tool for
-            // unscoped ingests.
-            this.misses++;
-            return null;
-        }
-        const list = this.bySource.get(source);
-        if (!list || list.length === 0) {
-            this.misses++;
-            return null;
-        }
-        const hash = SourceDedupCache.hashContent(content);
-        const found = list.find((e) => e.hash === hash);
-        if (found) {
-            this.hits++;
-            return found;
-        }
-        this.misses++;
-        return null;
-    }
-    /**
-     * Record a new (source, content, chunkId) entry after a successful
-     * ingest. LRU-evicts the oldest entry per source when the per-source
-     * cap is hit, and the oldest source when the overall cap is hit.
-     */
-    remember(source, content, chunkId) {
-        if (!source)
-            return;
-        const hash = SourceDedupCache.hashContent(content);
-        const entry = { hash, chunkId, ts: Date.now() };
-        let list = this.bySource.get(source);
-        if (!list) {
-            list = [];
-            // Evict the oldest source if we're at the global cap.
-            if (this.bySource.size >= MAX_SOURCES) {
-                let oldestKey = null;
-                let oldestTs = Infinity;
-                for (const [k, entries] of this.bySource.entries()) {
-                    const recent = entries[0]?.ts ?? 0;
-                    if (recent < oldestTs) {
-                        oldestTs = recent;
-                        oldestKey = k;
-                    }
-                }
-                if (oldestKey)
-                    this.bySource.delete(oldestKey);
-            }
-            this.bySource.set(source, list);
-        }
-        // De-dupe by hash within the per-source list — if the same hash
-        // is already there, replace it (fresh chunkId), otherwise prepend.
-        const existing = list.findIndex((e) => e.hash === hash);
-        if (existing >= 0) {
-            list[existing] = entry;
-        }
-        else {
-            list.unshift(entry);
-            if (list.length > MAX_PER_SOURCE)
-                list.length = MAX_PER_SOURCE;
-        }
-    }
-    /** Drop the entire cache. Useful for tests and explicit resets. */
-    clear() {
-        this.bySource.clear();
-        this.hits = 0;
-        this.misses = 0;
-    }
-    /** Snapshot stats for telemetry / Settings UI. */
-    stats() {
-        let entries = 0;
-        for (const list of this.bySource.values())
-            entries += list.length;
-        const total = this.hits + this.misses;
-        return {
-            sources: this.bySource.size,
-            entries,
-            hits: this.hits,
-            misses: this.misses,
-            hitRate: total === 0 ? 0 : this.hits / total,
-        };
-    }
-}
-/**
- * Module-level singleton. Engram is process-singleton anyway (one
- * server instance per data dir), so a single cache covers the whole
- * lifetime. Tests construct fresh `SourceDedupCache` instances; prod
- * uses this default.
- */
-export const sourceDedup = new SourceDedupCache();
+/**
+ * Session-scoped same-source ingest dedup.
+ *
+ * Agents in long sessions repeatedly re-read stable files, re-poll
+ * unchanged endpoints, and re-list the same directories. Each re-ingest
+ * goes through the full chunk → embed → save pipeline even though the
+ * content hasn't moved. On CPU embeddings (Engram's default backend),
+ * a 20K-token re-read can cost 5–15 seconds; multiplied across a
+ * 50-step agent run that's significant wall-clock burn.
+ *
+ * The existing 0.75-similarity dedup (in `server.ts`'s engram-ingest
+ * tool handler) catches semantic duplicates, but does so against the
+ * ENTIRE memory store — and at write-time it actually trips on
+ * incidentally-similar memories (a fact about Pyre at 0.78 similarity
+ * to a fact about Engram). It also requires the new content to be
+ * embedded first, so it doesn't save the embedding cost.
+ *
+ * This module is the cheaper, more conservative path:
+ *   - Scoped to a single source identifier (file path, URL, etc.).
+ *   - Hash-based equality (SHA-256 of trimmed content) — exact match
+ *     only, no false positives.
+ *   - In-memory LRU keyed by `source` → list of recent content hashes.
+ *   - Bounded: max 64 sources tracked, max 8 hashes per source.
+ *
+ * When an ingest hits the dedup cache, the caller can skip embedding
+ * AND skip the disk write — return the cached chunk id. Agent's
+ * conversation history stays internally consistent (same id for same
+ * content), and the wall-clock cost drops from "embed + save" to a
+ * map lookup.
+ *
+ * Process-scoped intentionally: the persistence layer doesn't need
+ * to know about this. Engram restart resets the cache — first ingest
+ * after restart goes through the full pipeline, which is fine.
+ */
+import { createHash } from 'node:crypto';
+const MAX_SOURCES = 64;
+const MAX_PER_SOURCE = 8;
+export class SourceDedupCache {
+    /** sourceKey → list of recent (hash, chunkId) entries, MRU first. */
+    bySource = new Map();
+    /** Cache hit count since boot. Useful for telemetry. */
+    hits = 0;
+    /** Cache miss count since boot. */
+    misses = 0;
+    /**
+     * Hash trimmed content. Stable across ingest calls for the same
+     * payload — that's the whole point.
+     */
+    static hashContent(content) {
+        return createHash('sha256').update(content.trim()).digest('hex');
+    }
+    /**
+     * Look up a (source, content) pair. Returns the cached entry on hit
+     * or null on miss. Does NOT promote the entry on read — promote on
+     * write only, so a hit doesn't reset its LRU position.
+     */
+    lookup(source, content) {
+        if (!source) {
+            // No source key → no scoping → don't dedup. The caller's
+            // existing semantic-similarity dedup is the right tool for
+            // unscoped ingests.
+            this.misses++;
+            return null;
+        }
+        const list = this.bySource.get(source);
+        if (!list || list.length === 0) {
+            this.misses++;
+            return null;
+        }
+        const hash = SourceDedupCache.hashContent(content);
+        const found = list.find((e) => e.hash === hash);
+        if (found) {
+            this.hits++;
+            return found;
+        }
+        this.misses++;
+        return null;
+    }
+    /**
+     * Record a new (source, content, chunkId) entry after a successful
+     * ingest. LRU-evicts the oldest entry per source when the per-source
+     * cap is hit, and the oldest source when the overall cap is hit.
+     */
+    remember(source, content, chunkId) {
+        if (!source)
+            return;
+        const hash = SourceDedupCache.hashContent(content);
+        const entry = { hash, chunkId, ts: Date.now() };
+        let list = this.bySource.get(source);
+        if (!list) {
+            list = [];
+            // Evict the oldest source if we're at the global cap.
+            if (this.bySource.size >= MAX_SOURCES) {
+                let oldestKey = null;
+                let oldestTs = Infinity;
+                for (const [k, entries] of this.bySource.entries()) {
+                    const recent = entries[0]?.ts ?? 0;
+                    if (recent < oldestTs) {
+                        oldestTs = recent;
+                        oldestKey = k;
+                    }
+                }
+                if (oldestKey)
+                    this.bySource.delete(oldestKey);
+            }
+            this.bySource.set(source, list);
+        }
+        // De-dupe by hash within the per-source list — if the same hash
+        // is already there, replace it (fresh chunkId), otherwise prepend.
+        const existing = list.findIndex((e) => e.hash === hash);
+        if (existing >= 0) {
+            list[existing] = entry;
+        }
+        else {
+            list.unshift(entry);
+            if (list.length > MAX_PER_SOURCE)
+                list.length = MAX_PER_SOURCE;
+        }
+    }
+    /** Drop the entire cache. Useful for tests and explicit resets. */
+    clear() {
+        this.bySource.clear();
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /** Snapshot stats for telemetry / Settings UI. */
+    stats() {
+        let entries = 0;
+        for (const list of this.bySource.values())
+            entries += list.length;
+        const total = this.hits + this.misses;
+        return {
+            sources: this.bySource.size,
+            entries,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total === 0 ? 0 : this.hits / total,
+        };
+    }
+}
+/**
+ * Module-level singleton. Engram is process-singleton anyway (one
+ * server instance per data dir), so a single cache covers the whole
+ * lifetime. Tests construct fresh `SourceDedupCache` instances; prod
+ * uses this default.
+ */
+export const sourceDedup = new SourceDedupCache();
 //# sourceMappingURL=source-dedup.js.map

package/dist/storage-postgres.js

@@ -68,13 +68,13 @@ export class PostgresStorageAdapter {
     // ── Chunks ─────────────────────────────────────────────────────────
     async saveChunk(chunk) {
         const { params } = this.chunkInsertParams(chunk);
-        await this.pool.query(`INSERT INTO chunks (id, tenant_id, embedding, domain, content, metadata, created_at)
-       VALUES ($1, $2, $3::vector, $4, $5, $6::jsonb, $7)
-       ON CONFLICT (id) DO UPDATE SET
-         tenant_id = EXCLUDED.tenant_id,
-         embedding = EXCLUDED.embedding,
-         domain = EXCLUDED.domain,
-         content = EXCLUDED.content,
+        await this.pool.query(`INSERT INTO chunks (id, tenant_id, embedding, domain, content, metadata, created_at)
+       VALUES ($1, $2, $3::vector, $4, $5, $6::jsonb, $7)
+       ON CONFLICT (id) DO UPDATE SET
+         tenant_id = EXCLUDED.tenant_id,
+         embedding = EXCLUDED.embedding,
+         domain = EXCLUDED.domain,
+         content = EXCLUDED.content,
          metadata = EXCLUDED.metadata`, params);
     }
     async saveChunks(chunks) {
@@ -92,8 +92,8 @@ export class PostgresStorageAdapter {
             values.push(`($${++p}, $${++p}, $${++p}::vector, $${++p}, $${++p}, $${++p}::jsonb, $${++p})`);
             params.push(...row);
         }
-        await this.pool.query(`INSERT INTO chunks (id, tenant_id, embedding, domain, content, metadata, created_at)
-       VALUES ${values.join(', ')}
+        await this.pool.query(`INSERT INTO chunks (id, tenant_id, embedding, domain, content, metadata, created_at)
+       VALUES ${values.join(', ')}
        ON CONFLICT (id) DO NOTHING`, params);
     }
     chunkInsertParams(chunk) {
@@ -139,9 +139,9 @@ export class PostgresStorageAdapter {
         };
     }
     async getChunk(id) {
-        const { rows } = await this.pool.query(`SELECT id, domain, content, metadata, embedding::text AS embedding, created_at
-         FROM chunks
-        WHERE tenant_id = $1 AND id = $2
+        const { rows } = await this.pool.query(`SELECT id, domain, content, metadata, embedding::text AS embedding, created_at
+         FROM chunks
+        WHERE tenant_id = $1 AND id = $2
         LIMIT 1`, [this.tenantId, id]);
         return rows[0] ? pgRowToChunk(rows[0], this.embeddingDim) : null;
     }
@@ -178,8 +178,8 @@ export class PostgresStorageAdapter {
             params.push(JSON.stringify([opts.tag]));
             conds.push(`metadata->'tags' @> $${params.length}::jsonb`);
         }
-        const { rows } = await this.pool.query(`SELECT id, domain, content, metadata, embedding::text AS embedding, created_at
-         FROM chunks
+        const { rows } = await this.pool.query(`SELECT id, domain, content, metadata, embedding::text AS embedding, created_at
+         FROM chunks
         WHERE ${conds.join(' AND ')}`, params);
         return rows.map((r) => pgRowToChunk(r, this.embeddingDim));
     }
@@ -212,11 +212,11 @@ export class PostgresStorageAdapter {
             const translated = translateFilter(filter);
             extra = ` AND (${translated})`;
         }
-        const { rows } = await this.pool.query(`SELECT id, domain, content, metadata, embedding::text AS embedding, created_at,
-              embedding <=> $2::vector AS distance
-         FROM chunks
-        WHERE tenant_id = $1${extra}
-        ORDER BY embedding <=> $2::vector
+        const { rows } = await this.pool.query(`SELECT id, domain, content, metadata, embedding::text AS embedding, created_at,
+              embedding <=> $2::vector AS distance
+         FROM chunks
+        WHERE tenant_id = $1${extra}
+        ORDER BY embedding <=> $2::vector
         LIMIT $3`, params);
         return rows.map((row) => ({
             chunk: pgRowToChunk(row, this.embeddingDim),
@@ -238,7 +238,7 @@ export class PostgresStorageAdapter {
     }
     // ── Daily Logs ────────────────────────────────────────────────────
     async appendDailyEntry(date, entry) {
-        await this.pool.query(`INSERT INTO daily_logs (date, tenant_id, entry, created_at)
+        await this.pool.query(`INSERT INTO daily_logs (date, tenant_id, entry, created_at)
        VALUES ($1::date, $2, $3::jsonb, NOW())`, [
             date,
             this.tenantId,
@@ -251,9 +251,9 @@ export class PostgresStorageAdapter {
         ]);
     }
     async getDailyLogs(daysBack) {
-        const { rows } = await this.pool.query(`SELECT date::text AS date, entry
-         FROM daily_logs
-        WHERE tenant_id = $1 AND date >= (CURRENT_DATE - ($2 || ' days')::interval)
+        const { rows } = await this.pool.query(`SELECT date::text AS date, entry
+         FROM daily_logs
+        WHERE tenant_id = $1 AND date >= (CURRENT_DATE - ($2 || ' days')::interval)
         ORDER BY date, created_at`, [this.tenantId, String(daysBack)]);
         const grouped = new Map();
         for (const r of rows) {
@@ -271,8 +271,8 @@ export class PostgresStorageAdapter {
     }
     // ── Procedural Rules ──────────────────────────────────────────────
     async saveRule(rule) {
-        await this.pool.query(`INSERT INTO rules (id, tenant_id, rule, created_at)
-       VALUES ($1, $2, $3::jsonb, $4)
+        await this.pool.query(`INSERT INTO rules (id, tenant_id, rule, created_at)
+       VALUES ($1, $2, $3::jsonb, $4)
        ON CONFLICT (id) DO UPDATE SET rule = EXCLUDED.rule, tenant_id = EXCLUDED.tenant_id`, [rule.id, this.tenantId, JSON.stringify(rule), rule.createdAt]);
     }
     async getRules() {
@@ -286,15 +286,15 @@ export class PostgresStorageAdapter {
     }
     // ── Knowledge Triples ────────────────────────────────────────────
     async saveTriple(triple) {
-        await this.pool.query(`INSERT INTO knowledge_triples
-         (id, tenant_id, subject, predicate, object, source_id, invalidated_at, created_at)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
-       ON CONFLICT (id) DO UPDATE SET
-         tenant_id = EXCLUDED.tenant_id,
-         subject = EXCLUDED.subject,
-         predicate = EXCLUDED.predicate,
-         object = EXCLUDED.object,
-         source_id = EXCLUDED.source_id,
+        await this.pool.query(`INSERT INTO knowledge_triples
+         (id, tenant_id, subject, predicate, object, source_id, invalidated_at, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       ON CONFLICT (id) DO UPDATE SET
+         tenant_id = EXCLUDED.tenant_id,
+         subject = EXCLUDED.subject,
+         predicate = EXCLUDED.predicate,
+         object = EXCLUDED.object,
+         source_id = EXCLUDED.source_id,
          invalidated_at = EXCLUDED.invalidated_at`, [
             triple.id,
             this.tenantId,
@@ -328,30 +328,30 @@ export class PostgresStorageAdapter {
         }
         if (opts?.activeOnly)
             conds.push(`invalidated_at IS NULL`);
-        const { rows } = await this.pool.query(`SELECT id, subject, predicate, object, source_id, invalidated_at, created_at
-         FROM knowledge_triples
+        const { rows } = await this.pool.query(`SELECT id, subject, predicate, object, source_id, invalidated_at, created_at
+         FROM knowledge_triples
         WHERE ${conds.join(' AND ')}`, params);
         return rows.map(pgRowToTriple);
     }
     async invalidateTriple(id) {
-        await this.pool.query(`UPDATE knowledge_triples SET invalidated_at = NOW()
+        await this.pool.query(`UPDATE knowledge_triples SET invalidated_at = NOW()
         WHERE tenant_id = $1 AND id = $2`, [this.tenantId, id]);
     }
     async getTripleTimeline(entity) {
-        const { rows } = await this.pool.query(`SELECT id, subject, predicate, object, source_id, invalidated_at, created_at
-         FROM knowledge_triples
-        WHERE tenant_id = $1 AND (subject = $2 OR object = $2)
+        const { rows } = await this.pool.query(`SELECT id, subject, predicate, object, source_id, invalidated_at, created_at
+         FROM knowledge_triples
+        WHERE tenant_id = $1 AND (subject = $2 OR object = $2)
         ORDER BY created_at ASC`, [this.tenantId, entity]);
         return rows.map(pgRowToTriple);
     }
     async getTripleStats() {
-        const { rows } = await this.pool.query(`SELECT
-          COUNT(*)::int AS total,
-          COUNT(*) FILTER (WHERE invalidated_at IS NULL)::int AS active,
-          COUNT(*) FILTER (WHERE invalidated_at IS NOT NULL)::int AS invalidated,
-          COUNT(DISTINCT subject)::int AS subjects,
-          COUNT(DISTINCT predicate)::int AS predicates
-         FROM knowledge_triples
+        const { rows } = await this.pool.query(`SELECT
+          COUNT(*)::int AS total,
+          COUNT(*) FILTER (WHERE invalidated_at IS NULL)::int AS active,
+          COUNT(*) FILTER (WHERE invalidated_at IS NOT NULL)::int AS invalidated,
+          COUNT(DISTINCT subject)::int AS subjects,
+          COUNT(DISTINCT predicate)::int AS predicates
+         FROM knowledge_triples
         WHERE tenant_id = $1`, [this.tenantId]);
         const r = rows[0] ?? { total: 0, active: 0, invalidated: 0, subjects: 0, predicates: 0 };
         return { total: r.total, active: r.active, invalidated: r.invalidated, subjects: r.subjects, predicates: r.predicates };
@@ -362,7 +362,7 @@ export class PostgresStorageAdapter {
         const date = now.toISOString().split('T')[0];
         const time = now.toISOString().split('T')[1].split('.')[0];
         const trimmed = content.trim();
-        await this.pool.query(`INSERT INTO diary_entries (date, tenant_id, agent, content, created_at)
+        await this.pool.query(`INSERT INTO diary_entries (date, tenant_id, agent, content, created_at)
        VALUES ($1::date, $2, $3, $4, $5)`, [date, this.tenantId, agent, trimmed, now.toISOString()]);
         return { date, time, content: trimmed, agent };
     }
@@ -382,9 +382,9 @@ export class PostgresStorageAdapter {
             params.push(opts.agent);
             conds.push(`agent = $${params.length}`);
         }
-        const { rows } = await this.pool.query(`SELECT date::text AS date, agent, content, created_at
-         FROM diary_entries
-        WHERE ${conds.join(' AND ')}
+        const { rows } = await this.pool.query(`SELECT date::text AS date, agent, content, created_at
+         FROM diary_entries
+        WHERE ${conds.join(' AND ')}
         ORDER BY date DESC, created_at ASC`, params);
         const grouped = new Map();
         for (const r of rows) {
@@ -397,9 +397,9 @@ export class PostgresStorageAdapter {
         return Array.from(grouped.entries()).map(([date, entries]) => ({ date, entries }));
     }
     async listDiaryDates() {
-        const { rows } = await this.pool.query(`SELECT DISTINCT date::text AS date
-         FROM diary_entries
-        WHERE tenant_id = $1
+        const { rows } = await this.pool.query(`SELECT DISTINCT date::text AS date
+         FROM diary_entries
+        WHERE tenant_id = $1
         ORDER BY date DESC`, [this.tenantId]);
         return rows.map((r) => r.date);
     }
@@ -408,7 +408,7 @@ export class PostgresStorageAdapter {
         const timestamp = new Date().toISOString();
         const full = { ...note, timestamp };
         const id = randomUUID();
-        await this.pool.query(`INSERT INTO handoffs (id, tenant_id, content_json, content_md, created_at)
+        await this.pool.query(`INSERT INTO handoffs (id, tenant_id, content_json, content_md, created_at)
        VALUES ($1, $2, $3::jsonb, $4, $5)`, [id, this.tenantId, JSON.stringify(full), formatHandoffMarkdown(full), timestamp]);
         return full;
     }
@@ -420,16 +420,16 @@ export class PostgresStorageAdapter {
             const { rows } = await this.pool.query(`SELECT content_json FROM handoffs WHERE tenant_id = $1 AND id = $2 LIMIT 1`, [this.tenantId, stamp]);
             return rows[0] ? rows[0].content_json : null;
         }
-        const { rows } = await this.pool.query(`SELECT content_json FROM handoffs
-        WHERE tenant_id = $1
+        const { rows } = await this.pool.query(`SELECT content_json FROM handoffs
+        WHERE tenant_id = $1
         ORDER BY created_at DESC LIMIT 1`, [this.tenantId]);
         return rows[0] ? rows[0].content_json : null;
     }
     async listHandoffs(limit = 10) {
-        const { rows } = await this.pool.query(`SELECT id, content_json, created_at
-         FROM handoffs
-        WHERE tenant_id = $1
-        ORDER BY created_at DESC
+        const { rows } = await this.pool.query(`SELECT id, content_json, created_at
+         FROM handoffs
+        WHERE tenant_id = $1
+        ORDER BY created_at DESC
         LIMIT $2`, [this.tenantId, limit]);
         return rows.map((r) => {
             const note = r.content_json;

package/dist/update-metadata.d.ts

@@ -1,29 +1,29 @@
-import type { CognitiveLayer, MemoryChunk, MemoryType, Sentiment } from './types.js';
-export interface UpdateMetadataInput {
-    tags?: string[];
-    source?: string;
-    domain?: string;
-    topic?: string;
-    type?: MemoryType;
-    sentiment?: Sentiment;
-    importance?: number;
-    cognitiveLayer?: CognitiveLayer;
-}
-export type UpdateMetadataMode = 'merge' | 'replace';
-/**
- * Pure helper: build the storage patch for a memory_update_metadata
- * call. Separated from server.ts so importing it (e.g. from tests)
- * doesn't pull in the MCP stdio server bootstrap.
- *
- * - `merge`: only fields the caller specified land in the patch.
- *   Untouched fields are absent → Storage.updateChunk leaves them alone.
- * - `replace`: every metadata-shape field is set, with caller values
- *   where present and engram defaults otherwise. Existing untouched
- *   fields get overwritten with the default. Footgun-y; the tool
- *   layer logs a warning when this mode fires.
- *
- * Immutable fields (id, createdAt, embedding, embeddingVersion) are
- * never produced by this helper; the tool layer doesn't accept them
- * in its input schema either.
- */
-export declare function buildUpdateMetadataPatch(metadata: UpdateMetadataInput, mode: UpdateMetadataMode): Partial<MemoryChunk>;
+import type { CognitiveLayer, MemoryChunk, MemoryType, Sentiment } from './types.js';
+export interface UpdateMetadataInput {
+    tags?: string[];
+    source?: string;
+    domain?: string;
+    topic?: string;
+    type?: MemoryType;
+    sentiment?: Sentiment;
+    importance?: number;
+    cognitiveLayer?: CognitiveLayer;
+}
+export type UpdateMetadataMode = 'merge' | 'replace';
+/**
+ * Pure helper: build the storage patch for a engram-update-metadata
+ * call. Separated from server.ts so importing it (e.g. from tests)
+ * doesn't pull in the MCP stdio server bootstrap.
+ *
+ * - `merge`: only fields the caller specified land in the patch.
+ *   Untouched fields are absent → Storage.updateChunk leaves them alone.
+ * - `replace`: every metadata-shape field is set, with caller values
+ *   where present and engram defaults otherwise. Existing untouched
+ *   fields get overwritten with the default. Footgun-y; the tool
+ *   layer logs a warning when this mode fires.
+ *
+ * Immutable fields (id, createdAt, embedding, embeddingVersion) are
+ * never produced by this helper; the tool layer doesn't accept them
+ * in its input schema either.
+ */
+export declare function buildUpdateMetadataPatch(metadata: UpdateMetadataInput, mode: UpdateMetadataMode): Partial<MemoryChunk>;