@mono-agent/memory-supermemory 0.6.2 → 0.9.0

package/README.md

@@ -4,6 +4,9 @@
 
 Category: `context`
 
+Plugin tier: this package is released in the mono-agent lockstep, but is not
+installed with `@mono-agent/agent-app`; the operator installs and selects it explicitly.
+
 ## Responsibility
 
 Provides a `MemoryStore` (from `@mono-agent/agent-contracts`) backed by an external
@@ -16,9 +19,16 @@ embeddings model and no memory chat LLM — the adapter just posts turns and sea
 ## Install / Usage
 
 ```bash
-pnpm --filter @mono-agent/memory-supermemory run build
+npm install @mono-agent/memory-supermemory@<matching-mono-agent-version>
 ```
 
+The package also ships `skills/mono-agent-supermemory/SKILL.md`, which guides a
+local configuration agent through service selection, privacy disclosure,
+validation, and a real recall smoke test. Installing the package never enables
+the backend by itself; `memory.backend: "supermemory"` remains the explicit opt-in.
+There is deliberately no separate plugin-preset loader: an installed plugin is
+offered by the normal wizard, while the skill owns later configuration changes.
+
 ```ts
 import { createSupermemoryStore } from "@mono-agent/memory-supermemory";
 
@@ -29,19 +39,38 @@ const store = createSupermemoryStore({
   maxBytes: 64_000,
 });
 
-await store.appendHostSummary("conv-1", "User prefers dark mode.");
+await store.persistCompletedTurn({
+  runId: "run-018f...",
+  conversationId: "conv-1",
+  summary: "User prefers dark mode.",
+  captureText: "User: Use dark mode.\nAssistant: Done.",
+});
 const block = await store.load("conv-1", "preferences");
 ```
 
 - `load(query)` → `POST /v4/search` (cached `/v3` fallback), formats ranked hits into a
   markdown block capped at `maxBytes`. Degrades to `undefined` on any error.
-- `appendHostSummary` / `scheduleCapture` → `POST /v3/documents` (one-liner / full turn,
-  async server-side extraction). Writes never throw.
+- `persistCompletedTurn` → one awaited `POST /v3/documents` containing the deterministic
+  summary and optional full capture text. A SHA-256-derived custom id keyed only by `runId`
+  keeps remote retries on one logical upsert. During one store lifetime an exact retry returns
+  as a duplicate without another request, while conflicting reuse of a run id fails before a
+  request. That exact lifetime check retains only two SHA-256 digests per distinct run—never raw
+  run ids, conversation ids, or turn content. After a process restart the remote API does not
+  expose enough conditional/read state
+  to distinguish a new document from a retry. Success returns the stable custom id after remote
+  admission, while any failure emits a constant content-free warning and is thrown so the harness
+  can report degradation. Raw run and
+  conversation ids are not placed in remote metadata. Documents over 1,000,000 bytes are
+  rejected rather than partially captured.
+- Legacy `appendHostSummary` / `scheduleCapture` remain compatible best-effort writes (one-liner /
+  full turn, async server-side extraction) and never throw. The harness does not call them when
+  the strong method is present.
 - `recall(query)` → hits shaped for the in-app `MemoryRecall` MCP tool.
 
 ## Public API
 
 - `createSupermemoryStore`, `SupermemoryMemoryStore`
+- `validateSupermemoryConfig`, `SupermemoryConfigValidation`
 - `createSupermemoryHttpClient`
 - `formatHitsAsBlock`, `SUPERMEMORY_SOURCE`
 - `CreateSupermemoryStoreConfig`, `SupermemoryStoreOptions`, `SupermemoryRecallHit`
@@ -71,4 +100,10 @@ pnpm --filter @mono-agent/memory-supermemory run test
 ```
 
 A gated real-instance round-trip runs when `MONO_AGENT_TEST_SUPERMEMORY_BASE_URL` points
-at a running Supermemory instance (skipped otherwise).
+at a running Supermemory instance (skipped otherwise). To require and run the
+package-owned, data-writing smoke explicitly:
+
+```bash
+MONO_AGENT_TEST_SUPERMEMORY_BASE_URL=http://127.0.0.1:6767 \
+  pnpm --filter @mono-agent/memory-supermemory run smoke
+```

package/dist/index.d.ts

@@ -21,6 +21,16 @@ export interface CreateSupermemoryStoreConfig {
         warn(message: string): void;
     };
 }
+export interface SupermemoryConfigValidation {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Validate plugin-owned service settings without making a network request.
+ * Connectivity remains the explicit live smoke because installation must not
+ * send agent data to an external service implicitly.
+ */
+export declare function validateSupermemoryConfig(config: CreateSupermemoryStoreConfig): SupermemoryConfigValidation;
 /** Build a {@link SupermemoryMemoryStore} over the REST client. The single entry point hosts use. */
 export declare function createSupermemoryStore(config: CreateSupermemoryStoreConfig): SupermemoryMemoryStore;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEhF,wFAAwF;AACxF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACnD;AAED,qGAAqG;AACrG,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,sBAAsB,CAgBnG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEhF,wFAAwF;AACxF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,4BAA4B,GACnC,2BAA2B,CA6B7B;AAED,qGAAqG;AACrG,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,sBAAsB,CAoBnG"}

package/dist/index.js

@@ -3,8 +3,46 @@ import { SupermemoryMemoryStore } from "./store.js";
 export { createSupermemoryHttpClient } from "./client.js";
 export { formatHitsAsBlock, SUPERMEMORY_SOURCE } from "./format.js";
 export { SupermemoryMemoryStore } from "./store.js";
+/**
+ * Validate plugin-owned service settings without making a network request.
+ * Connectivity remains the explicit live smoke because installation must not
+ * send agent data to an external service implicitly.
+ */
+export function validateSupermemoryConfig(config) {
+    const errors = [];
+    try {
+        const url = new URL(config.baseUrl);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            errors.push("baseUrl must use http or https.");
+        }
+        if (url.username.length > 0 || url.password.length > 0) {
+            errors.push("baseUrl must not contain credentials; use apiKey instead.");
+        }
+    }
+    catch {
+        errors.push("baseUrl must be a valid absolute URL.");
+    }
+    if (config.container.trim().length === 0) {
+        errors.push("container must not be empty.");
+    }
+    if (config.apiKey !== undefined && config.apiKey.trim().length === 0) {
+        errors.push("apiKey must be omitted rather than set to an empty value.");
+    }
+    positiveNumberError(errors, "timeoutMs", config.timeoutMs);
+    positiveNumberError(errors, "maxBytes", config.maxBytes);
+    positiveIntegerError(errors, "searchLimit", config.searchLimit);
+    if (config.threshold !== undefined
+        && (!Number.isFinite(config.threshold) || config.threshold < 0 || config.threshold > 1)) {
+        errors.push("threshold must be between 0 and 1.");
+    }
+    return { valid: errors.length === 0, errors };
+}
 /** Build a {@link SupermemoryMemoryStore} over the REST client. The single entry point hosts use. */
 export function createSupermemoryStore(config) {
+    const validation = validateSupermemoryConfig(config);
+    if (!validation.valid) {
+        throw new Error(`Invalid Supermemory configuration: ${validation.errors.join(" ")}`);
+    }
     const client = createSupermemoryHttpClient({
         baseUrl: config.baseUrl,
         containerTag: config.container,
@@ -21,4 +59,14 @@ export function createSupermemoryStore(config) {
         ...(config.logger === undefined ? {} : { logger: config.logger }),
     });
 }
+function positiveNumberError(errors, field, value) {
+    if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {
+        errors.push(`${field} must be greater than zero.`);
+    }
+}
+function positiveIntegerError(errors, field, value) {
+    if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+        errors.push(`${field} must be a positive integer.`);
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAY1D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAkBpD,qGAAqG;AACrG,MAAM,UAAU,sBAAsB,CAAC,MAAoC;IACzE,MAAM,MAAM,GAAG,2BAA2B,CAAC;QACzC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,YAAY,EAAE,MAAM,CAAC,SAAS;QAC9B,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QACjE,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAC1E,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;QAChF,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QAC7E,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAC1E,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;KAClE,CAAC,CAAC;IACH,OAAO,IAAI,sBAAsB,CAAC,MAAM,EAAE;QACxC,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;QACvE,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;QAChF,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;KAClE,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryBlock, MemoryStore, MemoryWriteResult } from "@mono-agent/agent-contracts";
+import type { MemoryBlock, MemoryCompletedTurn, MemoryCompletedTurnResult, MemoryStore, MemoryWriteResult } from "@mono-agent/agent-contracts";
 import type { SupermemoryClient } from "./client.js";
 export interface SupermemoryStoreOptions {
     /** Hard cap on the bytes a single `load` may return. */
@@ -20,11 +20,13 @@ export interface SupermemoryRecallHit {
 /**
  * MemoryStore backed by an external Supermemory instance (local OSS binary or hosted cloud).
  *
- * Writes are best-effort and NEVER throw — a memory failure must not break a reply. `appendHostSummary`
- * is a bounded await that returns `bytesWritten: 0` on failure; `scheduleCapture` is fire-and-forget,
- * serialized through a single chain (like the bujo store) so captures can't overlap or reject the
- * chain. Supermemory does extraction/consolidation server-side, so capture just posts the raw turn —
- * note that ingestion is async, so a just-captured turn is not immediately searchable.
+ * The strong `persistCompletedTurn` path awaits one run-keyed remote upsert, coalesces exact
+ * same-process retries, rejects same-process payload conflicts, and propagates failure so the
+ * harness can report degradation without changing the provider answer. Legacy
+ * writes remain best-effort and NEVER throw: `appendHostSummary` returns `bytesWritten: 0` on
+ * failure; `scheduleCapture` is fire-and-forget, serialized through a single chain so captures
+ * cannot overlap or reject the chain. Supermemory does extraction/consolidation server-side, so
+ * ingestion is async and a just-admitted turn may not be immediately searchable.
  *
  * `load` degrades to `undefined` on any client error (mirroring how the harness treats empty recall),
  * so a slow/down backend yields no context rather than a failed turn.
@@ -32,12 +34,23 @@ export interface SupermemoryRecallHit {
 export declare class SupermemoryMemoryStore implements MemoryStore {
     private readonly client;
     private captureChain;
+    /** Exact lifetime idempotency with no retained run/conversation/content. */
+    private readonly completedTurns;
+    private readonly completedTurnInflight;
     private readonly maxBytes;
     private readonly recallLimit;
     private readonly logger;
     constructor(client: SupermemoryClient, options?: SupermemoryStoreOptions);
     load(conversationId: string, query?: string): Promise<MemoryBlock | undefined>;
     appendHostSummary(conversationId: string, summary: string): Promise<MemoryWriteResult>;
+    /**
+     * Strong, awaited completed-turn admission. The remote custom id is derived
+     * only from the stable run id, so a cross-process retry upserts the same
+     * logical document; local digests distinguish exact retry from conflict.
+     * Unlike the legacy write methods, any failure is logged and propagated for
+     * the harness to surface as memory degradation.
+     */
+    persistCompletedTurn(turn: MemoryCompletedTurn): Promise<MemoryCompletedTurnResult>;
     scheduleCapture(conversationId: string, text: string): void;
     flush(): Promise<void>;
     /** Drain queued captures (HTTP client owns no handle to close). */

package/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAE/F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAMrD,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACnD;AAED,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAID;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAuB,YAAW,WAAW;IAOtD,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAGtC,MAAM,EAAE,iBAAiB,EAC1C,OAAO,GAAE,uBAA4B;IAOjC,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAc9E,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkB5F,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAarD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,mEAAmE;IAC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAKpF,MAAM;CAIrB"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,yBAAyB,EACzB,WAAW,EACX,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAYrD,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACnD;AAED,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,YAAW,WAAW;IAatD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB,OAAO,CAAC,YAAY,CAAoC;IACxD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAGjC;IACL,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAGtC,MAAM,EAAE,iBAAiB,EAC1C,OAAO,GAAE,uBAA4B;IAOjC,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAc9E,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkB5F;;;;;;OAMG;IACG,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAoDzF,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAarD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,mEAAmE;IAC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAKpF,MAAM;CAIrB"}

package/dist/store.js

@@ -2,15 +2,23 @@ import { createHash } from "node:crypto";
 import { formatHitsAsBlock, SUPERMEMORY_SOURCE } from "./format.js";
 /** Default per-turn recall budget (bytes) — mirrors the host's DEFAULT_MEMORY_MAX_BYTES. */
 const DEFAULT_MAX_BYTES = 64_000;
+/** Refuse oversized remote writes instead of silently dropping part of a completed turn. */
+const MAX_COMPLETED_TURN_BYTES = 1_000_000;
+const RECALL_WARNING = "supermemory recall failed; continuing without remote memory.";
+const SUMMARY_WARNING = "supermemory appendHostSummary failed; the turn continues.";
+const COMPLETED_TURN_WARNING = "supermemory persistCompletedTurn failed; the provider response remains valid.";
+const CAPTURE_WARNING = "supermemory capture failed; the queued turn continues.";
 const NOOP_LOGGER = { warn: (_message) => { } };
 /**
  * MemoryStore backed by an external Supermemory instance (local OSS binary or hosted cloud).
  *
- * Writes are best-effort and NEVER throw — a memory failure must not break a reply. `appendHostSummary`
- * is a bounded await that returns `bytesWritten: 0` on failure; `scheduleCapture` is fire-and-forget,
- * serialized through a single chain (like the bujo store) so captures can't overlap or reject the
- * chain. Supermemory does extraction/consolidation server-side, so capture just posts the raw turn —
- * note that ingestion is async, so a just-captured turn is not immediately searchable.
+ * The strong `persistCompletedTurn` path awaits one run-keyed remote upsert, coalesces exact
+ * same-process retries, rejects same-process payload conflicts, and propagates failure so the
+ * harness can report degradation without changing the provider answer. Legacy
+ * writes remain best-effort and NEVER throw: `appendHostSummary` returns `bytesWritten: 0` on
+ * failure; `scheduleCapture` is fire-and-forget, serialized through a single chain so captures
+ * cannot overlap or reject the chain. Supermemory does extraction/consolidation server-side, so
+ * ingestion is async and a just-admitted turn may not be immediately searchable.
  *
  * `load` degrades to `undefined` on any client error (mirroring how the harness treats empty recall),
  * so a slow/down backend yields no context rather than a failed turn.
@@ -18,6 +26,9 @@ const NOOP_LOGGER = { warn: (_message) => { } };
 export class SupermemoryMemoryStore {
     client;
     captureChain = Promise.resolve();
+    /** Exact lifetime idempotency with no retained run/conversation/content. */
+    completedTurns = new Map();
+    completedTurnInflight = new Map();
     maxBytes;
     recallLimit;
     logger;
@@ -36,8 +47,8 @@ export class SupermemoryMemoryStore {
             }
             return formatHitsAsBlock(hits, this.maxBytes);
         }
-        catch (error) {
-            this.logger.warn(`supermemory recall failed: ${message(error)}`);
+        catch {
+            safeWarn(this.logger, RECALL_WARNING);
             return undefined;
         }
     }
@@ -54,19 +65,78 @@ export class SupermemoryMemoryStore {
             });
             return { conversationId, source: SUPERMEMORY_SOURCE, bytesWritten: bytes };
         }
-        catch (error) {
-            this.logger.warn(`supermemory appendHostSummary failed: ${message(error)}`);
+        catch {
+            safeWarn(this.logger, SUMMARY_WARNING);
             return { conversationId, source: SUPERMEMORY_SOURCE, bytesWritten: 0 };
         }
     }
+    /**
+     * Strong, awaited completed-turn admission. The remote custom id is derived
+     * only from the stable run id, so a cross-process retry upserts the same
+     * logical document; local digests distinguish exact retry from conflict.
+     * Unlike the legacy write methods, any failure is logged and propagated for
+     * the harness to surface as memory degradation.
+     */
+    async persistCompletedTurn(turn) {
+        try {
+            assertCompletedTurn(turn);
+            const content = completedTurnDocument(turn);
+            const bytesWritten = Buffer.byteLength(content, "utf8");
+            if (bytesWritten > MAX_COMPLETED_TURN_BYTES) {
+                throw new Error(`completed turn exceeds the ${MAX_COMPLETED_TURN_BYTES}-byte Supermemory admission limit`);
+            }
+            const runIdHash = safeHash(turn.runId);
+            const customId = `completed-turn-${runIdHash.slice(0, 32)}`;
+            const payloadDigest = completedTurnDigest(turn);
+            const completed = this.completedTurns.get(runIdHash);
+            if (completed !== undefined) {
+                assertMatchingCompletedTurn(completed, payloadDigest);
+                return completedTurnResult(turn, customId, 0, "duplicate");
+            }
+            const inflight = this.completedTurnInflight.get(runIdHash);
+            if (inflight !== undefined) {
+                assertMatchingCompletedTurn(inflight.payloadDigest, payloadDigest);
+                await inflight.promise;
+                return completedTurnResult(turn, customId, 0, "duplicate");
+            }
+            const result = completedTurnResult(turn, customId, bytesWritten, "admitted");
+            const promise = (async () => {
+                await this.client.add({
+                    content,
+                    customId,
+                    // Keep remote indexing metadata flat and free of raw channel/run ids.
+                    metadata: {
+                        kind: "completed-turn",
+                        schemaVersion: 1,
+                        hasCapture: turn.captureText !== undefined,
+                    },
+                });
+                this.completedTurns.set(runIdHash, payloadDigest);
+                return result;
+            })();
+            this.completedTurnInflight.set(runIdHash, { payloadDigest, promise });
+            try {
+                return await promise;
+            }
+            finally {
+                if (this.completedTurnInflight.get(runIdHash)?.promise === promise) {
+                    this.completedTurnInflight.delete(runIdHash);
+                }
+            }
+        }
+        catch (error) {
+            safeWarn(this.logger, COMPLETED_TURN_WARNING);
+            throw error;
+        }
+    }
     scheduleCapture(conversationId, text) {
         this.captureChain = this.captureChain
             .then(async () => {
             try {
                 await this.client.add({ content: text, metadata: { kind: "turn-capture", conversationId } });
             }
-            catch (error) {
-                this.logger.warn(`supermemory capture failed: ${message(error)}`);
+            catch {
+                safeWarn(this.logger, CAPTURE_WARNING);
             }
         })
             // Terminal guard: the chain must never settle rejected, or every future capture would be skipped.
@@ -95,7 +165,60 @@ export class SupermemoryMemoryStore {
 function stableId(input) {
     return createHash("sha1").update(input).digest("hex").slice(0, 24);
 }
-function message(error) {
-    return error instanceof Error ? error.message : String(error);
+function safeHash(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function completedTurnDigest(turn) {
+    return createHash("sha256").update(JSON.stringify({
+        conversationId: turn.conversationId,
+        summary: turn.summary,
+        ...(turn.captureText === undefined ? {} : { captureText: turn.captureText }),
+    })).digest("hex");
+}
+function assertMatchingCompletedTurn(existing, incoming) {
+    if (existing !== incoming) {
+        throw new Error("supermemory: completed-turn run id conflicts with an already admitted payload");
+    }
+}
+function completedTurnResult(turn, id, bytesWritten, admissionStatus) {
+    return {
+        id,
+        runId: turn.runId,
+        conversationId: turn.conversationId,
+        source: SUPERMEMORY_SOURCE,
+        bytesWritten,
+        // The documents endpoint exposes a successful upsert but cannot identify
+        // create versus cross-process retry; local exact retries use "duplicate".
+        admissionStatus,
+    };
+}
+function completedTurnDocument(turn) {
+    return [
+        "Completed turn summary:",
+        turn.summary,
+        ...(turn.captureText === undefined
+            ? []
+            : ["", "Completed turn capture:", turn.captureText]),
+    ].join("\n");
+}
+function assertCompletedTurn(turn) {
+    for (const [field, value] of [
+        ["runId", turn.runId],
+        ["conversationId", turn.conversationId],
+        ["summary", turn.summary],
+    ]) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new TypeError(`completed turn ${field} must be a non-empty string`);
+        }
+    }
+    if (turn.captureText !== undefined && typeof turn.captureText !== "string") {
+        throw new TypeError("completed turn captureText must be a string when provided");
+    }
+}
+function safeWarn(logger, message) {
+    try {
+        logger.warn(message);
+    }
+    catch { /* Diagnostics cannot replace the backend result. */ }
 }
 //# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,30 +1,37 @@
 {
   "name": "@mono-agent/memory-supermemory",
-  "version": "0.6.2",
+  "version": "0.9.0",
   "description": "Supermemory external memory backend: a MemoryStore over Supermemory's REST API (local OSS binary or hosted cloud).",
   "type": "module",
   "license": "UNLICENSED",
   "private": false,
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "scripts",
+    "skills",
     "README.md"
   ],
   "dependencies": {
-    "@mono-agent/agent-contracts": "0.6.2"
+    "@mono-agent/agent-contracts": "0.9.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "smoke": "node scripts/smoke.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests"
   }

package/scripts/smoke.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { createSupermemoryStore } from "../dist/index.js";
+
+const baseUrl = process.env.MONO_AGENT_TEST_SUPERMEMORY_BASE_URL;
+if (baseUrl === undefined || baseUrl.trim().length === 0) {
+  console.error(
+    "Set MONO_AGENT_TEST_SUPERMEMORY_BASE_URL to the local or hosted Supermemory service to run this data-writing smoke test.",
+  );
+  process.exitCode = 2;
+} else {
+  await smoke(baseUrl);
+}
+
+async function smoke(serviceUrl) {
+  const marker = `mono-agent-plugin-smoke-${Date.now()}-${process.pid}`;
+  const store = createSupermemoryStore({
+    baseUrl: serviceUrl,
+    container: marker,
+    ...(process.env.MONO_AGENT_TEST_SUPERMEMORY_API_KEY === undefined
+      ? {}
+      : { apiKey: process.env.MONO_AGENT_TEST_SUPERMEMORY_API_KEY }),
+  });
+  try {
+    store.scheduleCapture("smoke", `The unique verification marker is ${marker}.`);
+    await store.flush();
+
+    const deadline = Date.now() + 60_000;
+    while (Date.now() < deadline) {
+      const hits = await store.recall(marker, { topK: 3 });
+      if (hits.some((hit) => hit.record.text.includes(marker))) {
+        console.log(`Supermemory plugin smoke passed for ${serviceUrl}.`);
+        return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 2_000));
+    }
+    throw new Error("captured marker was not recallable within 60 seconds");
+  } finally {
+    await store.close();
+  }
+}

package/skills/mono-agent-supermemory/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: mono-agent-supermemory
+description: Configure an existing mono-agent to use the optional Supermemory memory plugin, with explicit service, privacy, credential, validation, and rollback checks.
+---
+
+# Configure Supermemory Memory
+
+Use this skill only in an existing mono-agent folder whose operator explicitly
+asked to install, enable, inspect, or remove the Supermemory plugin. Supermemory
+is optional: never switch an agent from Lite, Journal, or BuJo implicitly.
+
+## Rules
+
+- Inspect `mono-agent.config.json`, `mono-agent config`, and `mono-agent validate`
+  for current state. Recalled memory is not evidence of current configuration.
+- Ask whether data should stay on a local `supermemory-server` or be sent to the
+  hosted service. State that turns and recalled content leave mono-agent for the
+  selected service.
+- Keep credentials out of chat, config, skill files, and traces. A hosted key is
+  collected by the host's masked secret flow as
+  `MONO_AGENT_MEMORY_SUPERMEMORY_API_KEY`; a keyless local service needs no key.
+- Install the exact `@mono-agent/memory-supermemory` version matching
+  `@mono-agent/agent-app`. Do not use `latest` when versions differ.
+- Propose the smallest config change and preserve the previous memory root. Do
+  not migrate or delete local memory automatically.
+- Apply through the authenticated local configuration flow when available.
+  Otherwise show the patch and commands without claiming they ran.
+
+## Config
+
+```json
+{
+  "memory": {
+    "backend": "supermemory",
+    "mode": "lite",
+    "path": "./.mono-agent/memory",
+    "writeMode": "capture",
+    "supermemory": {
+      "baseUrl": "http://127.0.0.1:6767"
+    }
+  }
+}
+```
+
+The app derives the default container from the agent trace source. Set a
+container only when the operator deliberately wants another namespace.
+MemoryRecall is enabled by default for configured memory; an explicit false is
+the opt-out.
+
+## Verify
+
+1. Confirm the exact plugin package resolves.
+2. Run `mono-agent validate` and fix every memory error.
+3. After the host reloads in a fresh turn, call MemoryRecall once. An empty
+   result is a valid registration smoke for an empty container.
+4. Report the config change ID and rollback command. Never use a same-turn tool
+   call as proof of the newly applied backend because the active responder still
+   owns the prior store until reload.