@onenomad/engram-mcp 1.0.0 → 2.0.0

package/dist/update-metadata.js

@@ -1,52 +1,52 @@
-/**
- * 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 function buildUpdateMetadataPatch(metadata, mode) {
-    const patch = {};
-    if (mode === 'replace') {
-        patch.tags = metadata.tags ?? [];
-        patch.source = metadata.source ?? '';
-        patch.domain = metadata.domain ?? '';
-        patch.topic = metadata.topic ?? '';
-        patch.type = metadata.type ?? 'context';
-        patch.sentiment = metadata.sentiment ?? 'neutral';
-        patch.importance = metadata.importance ?? 0.5;
-        if (metadata.cognitiveLayer !== undefined) {
-            patch.cognitiveLayer = metadata.cognitiveLayer;
-        }
-    }
-    else {
-        if (metadata.tags !== undefined)
-            patch.tags = metadata.tags;
-        if (metadata.source !== undefined)
-            patch.source = metadata.source;
-        if (metadata.domain !== undefined)
-            patch.domain = metadata.domain;
-        if (metadata.topic !== undefined)
-            patch.topic = metadata.topic;
-        if (metadata.type !== undefined)
-            patch.type = metadata.type;
-        if (metadata.sentiment !== undefined)
-            patch.sentiment = metadata.sentiment;
-        if (metadata.importance !== undefined)
-            patch.importance = metadata.importance;
-        if (metadata.cognitiveLayer !== undefined) {
-            patch.cognitiveLayer = metadata.cognitiveLayer;
-        }
-    }
-    return patch;
-}
+/**
+ * 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 function buildUpdateMetadataPatch(metadata, mode) {
+    const patch = {};
+    if (mode === 'replace') {
+        patch.tags = metadata.tags ?? [];
+        patch.source = metadata.source ?? '';
+        patch.domain = metadata.domain ?? '';
+        patch.topic = metadata.topic ?? '';
+        patch.type = metadata.type ?? 'context';
+        patch.sentiment = metadata.sentiment ?? 'neutral';
+        patch.importance = metadata.importance ?? 0.5;
+        if (metadata.cognitiveLayer !== undefined) {
+            patch.cognitiveLayer = metadata.cognitiveLayer;
+        }
+    }
+    else {
+        if (metadata.tags !== undefined)
+            patch.tags = metadata.tags;
+        if (metadata.source !== undefined)
+            patch.source = metadata.source;
+        if (metadata.domain !== undefined)
+            patch.domain = metadata.domain;
+        if (metadata.topic !== undefined)
+            patch.topic = metadata.topic;
+        if (metadata.type !== undefined)
+            patch.type = metadata.type;
+        if (metadata.sentiment !== undefined)
+            patch.sentiment = metadata.sentiment;
+        if (metadata.importance !== undefined)
+            patch.importance = metadata.importance;
+        if (metadata.cognitiveLayer !== undefined) {
+            patch.cognitiveLayer = metadata.cognitiveLayer;
+        }
+    }
+    return patch;
+}
 //# sourceMappingURL=update-metadata.js.map

package/dist/wal.d.ts

@@ -1,95 +1,95 @@
-import type { SmartMemoryConfig, MemoryType, CognitiveLayer, Sentiment, MemoryOrigin, MemoryTier } from './types.js';
-import type { StoredChunk } from './storage.js';
-import { Storage } from './storage.js';
-/**
- * Write-Ahead Log (WAL) — real-time memory capture during conversations.
- *
- * The WAL principle: write state BEFORE responding, not after.
- * This ensures no memory is lost if the agent crashes, compacts, or restarts.
- *
- * Use `ingest` for immediate capture of facts/decisions/preferences
- * as they happen, rather than waiting for post-conversation extraction.
- */
-export interface IngestEntry {
-    content: string;
-    type?: MemoryType;
-    layer?: CognitiveLayer;
-    importance?: number;
-    tags?: string[];
-    source?: string;
-    domain?: string;
-    topic?: string;
-    sentiment?: Sentiment;
-    emotionalValence?: number;
-    emotionalArousal?: number;
-    origin?: MemoryOrigin;
-    tier?: MemoryTier;
-    /**
-     * ISO 8601 timestamp override. Default: ingest time (Date.now()).
-     *
-     * Critical when the content represents an event that originally
-     * happened at a different time — meeting notes from yesterday,
-     * dated documents, imported chat history, benchmark fixtures.
-     *
-     * The createdAt timestamp flows into `buildContextPrefix()` which
-     * is included in the embedded text. The retrieval pipeline uses
-     * this as a temporal signal — both via similarity match against
-     * the prefix in queries, and via downstream temporal-boost logic
-     * in `search.ts`.
-     *
-     * Without an override, every ingested memory shares the ingest-
-     * time prefix (which is the same for everything ingested in the
-     * same hour), losing all temporal differentiation.
-     */
-    createdAt?: string;
-    /**
-     * When true, skip the per-chunk KG triple extraction. The standalone
-     * locomo bench bypasses this (calls saveChunk directly, never enters
-     * wal.ts), which is why its wall-clock is ~50× faster than Pyre's
-     * MCP-boundary bench on the same dataset.
-     *
-     * Real users keep KG extraction (it powers memory_dossier,
-     * memory_kg_query, graph rerank). Benchmark harnesses comparing
-     * apples-to-apples vs the standalone bench should pass this flag
-     * so they're measuring the same code path.
-     */
-    skipKgExtraction?: boolean;
-    /**
-     * When true, skip the post-batch appendDailyEntry write. Same
-     * rationale as skipKgExtraction — the standalone bench doesn't
-     * touch the daily-entries store; bench harnesses matching it
-     * should skip the write to compare on equal footing.
-     */
-    skipDailyEntry?: boolean;
-    /**
-     * When false, KG extraction + daily-entry append run in the
-     * BACKGROUND after ingest() returns. The caller gets its chunks
-     * back as soon as the saveChunk loop finishes; the side effects
-     * complete on their own pace.
-     *
-     * Default true (backwards compatible — caller awaits everything).
-     * Production callers where the agent doesn't immediately query
-     * the just-written content (chat WAL, tool-vault bridge) should
-     * pass false for ~5-30× faster perceived ingest latency.
-     *
-     * To wait for background work to drain (tests, shutdown), call
-     * `flushPendingSideEffects()` from this module.
-     */
-    awaitSideEffects?: boolean;
-}
-/**
- * Wait for all in-flight background side-effects (KG extraction +
- * daily-entry append fired with `awaitSideEffects: false`) to
- * complete. No-op when nothing is pending.
- *
- * Tests should call this between ingest and assert; shutdown code
- * should call before process exit to avoid losing KG writes.
- */
-export declare function flushPendingSideEffects(): Promise<void>;
-/** Pending count — for tests + telemetry. */
-export declare function pendingSideEffectCount(): number;
-/**
- * Immediately persist one or more memory entries.
- * Designed to be called mid-conversation, before the agent responds.
- */
-export declare function ingest(config: SmartMemoryConfig, storage: Storage, entries: IngestEntry[]): Promise<StoredChunk[]>;
+import type { SmartMemoryConfig, MemoryType, CognitiveLayer, Sentiment, MemoryOrigin, MemoryTier } from './types.js';
+import type { StoredChunk } from './storage.js';
+import { Storage } from './storage.js';
+/**
+ * Write-Ahead Log (WAL) — real-time memory capture during conversations.
+ *
+ * The WAL principle: write state BEFORE responding, not after.
+ * This ensures no memory is lost if the agent crashes, compacts, or restarts.
+ *
+ * Use `ingest` for immediate capture of facts/decisions/preferences
+ * as they happen, rather than waiting for post-conversation extraction.
+ */
+export interface IngestEntry {
+    content: string;
+    type?: MemoryType;
+    layer?: CognitiveLayer;
+    importance?: number;
+    tags?: string[];
+    source?: string;
+    domain?: string;
+    topic?: string;
+    sentiment?: Sentiment;
+    emotionalValence?: number;
+    emotionalArousal?: number;
+    origin?: MemoryOrigin;
+    tier?: MemoryTier;
+    /**
+     * ISO 8601 timestamp override. Default: ingest time (Date.now()).
+     *
+     * Critical when the content represents an event that originally
+     * happened at a different time — meeting notes from yesterday,
+     * dated documents, imported chat history, benchmark fixtures.
+     *
+     * The createdAt timestamp flows into `buildContextPrefix()` which
+     * is included in the embedded text. The retrieval pipeline uses
+     * this as a temporal signal — both via similarity match against
+     * the prefix in queries, and via downstream temporal-boost logic
+     * in `search.ts`.
+     *
+     * Without an override, every ingested memory shares the ingest-
+     * time prefix (which is the same for everything ingested in the
+     * same hour), losing all temporal differentiation.
+     */
+    createdAt?: string;
+    /**
+     * When true, skip the per-chunk KG triple extraction. The standalone
+     * locomo bench bypasses this (calls saveChunk directly, never enters
+     * wal.ts), which is why its wall-clock is ~50× faster than Pyre's
+     * MCP-boundary bench on the same dataset.
+     *
+     * Real users keep KG extraction (it powers engram-dossier,
+     * engram-kg-query, graph rerank). Benchmark harnesses comparing
+     * apples-to-apples vs the standalone bench should pass this flag
+     * so they're measuring the same code path.
+     */
+    skipKgExtraction?: boolean;
+    /**
+     * When true, skip the post-batch appendDailyEntry write. Same
+     * rationale as skipKgExtraction — the standalone bench doesn't
+     * touch the daily-entries store; bench harnesses matching it
+     * should skip the write to compare on equal footing.
+     */
+    skipDailyEntry?: boolean;
+    /**
+     * When false, KG extraction + daily-entry append run in the
+     * BACKGROUND after ingest() returns. The caller gets its chunks
+     * back as soon as the saveChunk loop finishes; the side effects
+     * complete on their own pace.
+     *
+     * Default true (backwards compatible — caller awaits everything).
+     * Production callers where the agent doesn't immediately query
+     * the just-written content (chat WAL, tool-vault bridge) should
+     * pass false for ~5-30× faster perceived ingest latency.
+     *
+     * To wait for background work to drain (tests, shutdown), call
+     * `flushPendingSideEffects()` from this module.
+     */
+    awaitSideEffects?: boolean;
+}
+/**
+ * Wait for all in-flight background side-effects (KG extraction +
+ * daily-entry append fired with `awaitSideEffects: false`) to
+ * complete. No-op when nothing is pending.
+ *
+ * Tests should call this between ingest and assert; shutdown code
+ * should call before process exit to avoid losing KG writes.
+ */
+export declare function flushPendingSideEffects(): Promise<void>;
+/** Pending count — for tests + telemetry. */
+export declare function pendingSideEffectCount(): number;
+/**
+ * Immediately persist one or more memory entries.
+ * Designed to be called mid-conversation, before the agent responds.
+ */
+export declare function ingest(config: SmartMemoryConfig, storage: Storage, entries: IngestEntry[]): Promise<StoredChunk[]>;