@mono-agent/memory-supermemory 0.4.1

package/README.md

@@ -0,0 +1,74 @@
+# @mono-agent/memory-supermemory
+
+## Category
+
+Category: `context`
+
+## Responsibility
+
+Provides a `MemoryStore` (from `@mono-agent/agent-contracts`) backed by an external
+[Supermemory](https://supermemory.ai) instance — a local OSS binary
+(`supermemory-server`, MIT) or the hosted cloud — reached over its REST API. Selected via
+`config.memory.backend: "supermemory"`; the built-in BuJo engine remains the default.
+Supermemory extracts and consolidates memories **server-side**, so this backend needs no
+embeddings model and no memory chat LLM — the adapter just posts turns and searches.
+
+## Install / Usage
+
+```bash
+pnpm --filter @mono-agent/memory-supermemory run build
+```
+
+```ts
+import { createSupermemoryStore } from "@mono-agent/memory-supermemory";
+
+const store = createSupermemoryStore({
+  baseUrl: "http://127.0.0.1:6767", // local binary; or https://api.supermemory.ai for cloud
+  apiKey: process.env.SUPERMEMORY_API_KEY, // optional; omit for a keyless local instance
+  container: "my-agent",            // namespace tag scoping every add + search
+  maxBytes: 64_000,
+});
+
+await store.appendHostSummary("conv-1", "User prefers dark mode.");
+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.
+- `recall(query)` → hits shaped for the in-app `memory_recall` MCP tool.
+
+## Public API
+
+- `createSupermemoryStore`, `SupermemoryMemoryStore`
+- `createSupermemoryHttpClient`
+- `formatHitsAsBlock`, `SUPERMEMORY_SOURCE`
+- `CreateSupermemoryStoreConfig`, `SupermemoryStoreOptions`, `SupermemoryRecallHit`
+- `SupermemoryClient`, `SupermemoryHttpClientConfig`, `SupermemoryAddParams`,
+  `SupermemorySearchParams`, `SupermemoryHit`, `SupermemoryMetadataValue`,
+  `SupermemorySearchMode`, `SupermemoryFetch`, `SupermemoryFetchResponse`
+
+## Dependency Boundary
+
+Depends only on `@mono-agent/agent-contracts` (for the `MemoryStore` contract types) and the
+Fetch API. No native build, no SDK dependency — the REST client uses raw `fetch` behind an
+injectable seam (`SupermemoryFetch`) so the store is fully unit-testable without a network.
+
+## What This Package Does Not Own
+
+It does not own backend selection (that is `config.memory.backend`) or the
+`memory_recall` tool wiring; both are resolved in `@mono-agent/agent-app`. It also does not own
+the Supermemory service itself (extraction, consolidation, and storage all happen
+server-side). It does not run BuJo scheduled consolidation and ignores `mode`/`embeddings`/`llm`.
+
+## Verification
+
+```bash
+pnpm --filter @mono-agent/memory-supermemory run build
+pnpm --filter @mono-agent/memory-supermemory run typecheck
+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).

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Thin REST client for Supermemory's Memory API. Two operations back the MemoryStore adapter:
+ *   - ADD    `POST {base}/v3/documents`  (ingestion is async; the server returns `{ id, status }`)
+ *   - SEARCH `POST {base}/v4/search`     (preferred; falls back to legacy `/v3/search`)
+ *
+ * Wire shapes are taken from the verified Supermemory API surface (sdk-ts api.md + docs). We use raw
+ * `fetch` behind a tiny injectable seam ({@link SupermemoryFetch}) rather than the `supermemory` SDK:
+ * the adapter only needs two endpoints, the wire format is fixed, and a raw client keeps the package
+ * dependency-free and fully unit-testable without a network or the SDK.
+ *
+ * Self-host caveat: the self-hosted binary's quickstart documents only the v3 routes, so search tries
+ * `/v4/search` first and transparently falls back to the legacy `/v3/search` (plural `containerTags`,
+ * `score` instead of `similarity`, text under `content`/`chunks[].content`) on a 404. Both response
+ * shapes are normalized into {@link SupermemoryHit}.
+ */
+export type SupermemorySearchMode = "memories" | "hybrid" | "documents";
+/** A normalized, ranked memory hit (uniform across the v4 and legacy v3 response shapes). */
+export interface SupermemoryHit {
+    readonly id: string;
+    readonly text: string;
+    /** Relevance score in [0, 1]. */
+    readonly score: number;
+}
+/** Flat metadata values only — Supermemory rejects nested objects. */
+export type SupermemoryMetadataValue = string | number | boolean | readonly string[];
+export interface SupermemoryAddParams {
+    readonly content: string;
+    /** Stable id enabling idempotent upsert/de-dup of re-emitted content. */
+    readonly customId?: string;
+    readonly metadata?: Readonly<Record<string, SupermemoryMetadataValue>>;
+}
+export interface SupermemorySearchParams {
+    readonly query: string;
+    /** Max hits (defaults to the client's configured `searchLimit`). */
+    readonly limit?: number;
+}
+/** The capability the store depends on. Fakes implement this directly in unit tests. */
+export interface SupermemoryClient {
+    /** Add a document to the agent's container. Rejects on non-2xx so callers can degrade. */
+    add(params: SupermemoryAddParams): Promise<void>;
+    /** Search the agent's container. Rejects on transport failure so `load` can degrade to undefined. */
+    search(params: SupermemorySearchParams): Promise<SupermemoryHit[]>;
+}
+/** Minimal response surface we use — keeps the injectable `fetch` seam trivial to stub in tests. */
+export interface SupermemoryFetchResponse {
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+export type SupermemoryFetch = (url: string, init: {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+    readonly signal: AbortSignal;
+}) => Promise<SupermemoryFetchResponse>;
+export interface SupermemoryHttpClientConfig {
+    /** REST base URL — local OSS binary (e.g. http://127.0.0.1:6767) or hosted cloud. */
+    readonly baseUrl: string;
+    /** Bearer token. Omitted → no Authorization header (keyless local instances). */
+    readonly apiKey?: string;
+    /** Namespace tag scoping every add + search. */
+    readonly containerTag: string;
+    readonly timeoutMs?: number;
+    readonly searchLimit?: number;
+    readonly searchMode?: SupermemorySearchMode;
+    /**
+     * Minimum-similarity cutoff (0..1) applied SERVER-SIDE on v4 search. Unset (default) → no floor,
+     * so recall returns the top ranked hits like the bujo backend. Set it only to deliberately drop
+     * weak matches; a non-trivial floor on hybrid search can silently discard relevant memories.
+     */
+    readonly threshold?: number;
+    readonly rerank?: boolean;
+    /** Injectable transport (defaults to global fetch). */
+    readonly fetch?: SupermemoryFetch;
+}
+export declare function createSupermemoryHttpClient(config: SupermemoryHttpClientConfig): SupermemoryClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExE,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,qGAAqG;IACrG,MAAM,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CACpE;AAED,oGAAoG;AACpG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,KACE,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAEvC,MAAM,WAAW,2BAA2B;IAC1C,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAOD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,2BAA2B,GAAG,iBAAiB,CA0ElG"}

package/dist/client.js

@@ -0,0 +1,160 @@
+/**
+ * Thin REST client for Supermemory's Memory API. Two operations back the MemoryStore adapter:
+ *   - ADD    `POST {base}/v3/documents`  (ingestion is async; the server returns `{ id, status }`)
+ *   - SEARCH `POST {base}/v4/search`     (preferred; falls back to legacy `/v3/search`)
+ *
+ * Wire shapes are taken from the verified Supermemory API surface (sdk-ts api.md + docs). We use raw
+ * `fetch` behind a tiny injectable seam ({@link SupermemoryFetch}) rather than the `supermemory` SDK:
+ * the adapter only needs two endpoints, the wire format is fixed, and a raw client keeps the package
+ * dependency-free and fully unit-testable without a network or the SDK.
+ *
+ * Self-host caveat: the self-hosted binary's quickstart documents only the v3 routes, so search tries
+ * `/v4/search` first and transparently falls back to the legacy `/v3/search` (plural `containerTags`,
+ * `score` instead of `similarity`, text under `content`/`chunks[].content`) on a 404. Both response
+ * shapes are normalized into {@link SupermemoryHit}.
+ */
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_SEARCH_LIMIT = 10;
+const DEFAULT_SEARCH_MODE = "hybrid";
+const defaultFetch = async (url, init) => {
+    const res = await fetch(url, init);
+    return { status: res.status, json: () => res.json() };
+};
+export function createSupermemoryHttpClient(config) {
+    const base = config.baseUrl.replace(/\/+$/u, "");
+    const containerTag = config.containerTag;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const searchLimit = config.searchLimit ?? DEFAULT_SEARCH_LIMIT;
+    const searchMode = config.searchMode ?? DEFAULT_SEARCH_MODE;
+    const threshold = config.threshold;
+    const rerank = config.rerank ?? false;
+    const doFetch = config.fetch ?? defaultFetch;
+    // Remember when an instance doesn't serve /v4 so we route straight to /v3 thereafter instead of
+    // re-probing v4 (and paying its latency) on every subsequent search.
+    let v4Available = true;
+    async function request(path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await doFetch(`${base}${path}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(config.apiKey === undefined ? {} : { authorization: `Bearer ${config.apiKey}` }),
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            const json = await res.json().catch(() => undefined);
+            return { status: res.status, json };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        async add(params) {
+            const { status } = await request("/v3/documents", {
+                content: params.content,
+                containerTag,
+                ...(params.customId === undefined ? {} : { customId: params.customId }),
+                ...(params.metadata === undefined ? {} : { metadata: params.metadata }),
+            });
+            if (!ok(status)) {
+                throw new Error(`supermemory add failed: HTTP ${status}`);
+            }
+        },
+        async search(params) {
+            const limit = params.limit ?? searchLimit;
+            if (v4Available) {
+                const v4 = await request("/v4/search", {
+                    q: params.query,
+                    containerTag,
+                    searchMode,
+                    limit,
+                    // Omit the floor unless explicitly configured — match bujo's "top-N, no minimum" recall.
+                    ...(threshold === undefined ? {} : { threshold }),
+                    rerank,
+                });
+                if (v4.status !== 404) {
+                    if (!ok(v4.status)) {
+                        throw new Error(`supermemory search failed: HTTP ${v4.status}`);
+                    }
+                    return normalizeHits(v4.json, "v4");
+                }
+                // This instance doesn't serve /v4 (self-hosted binary may only expose v3) — remember it.
+                v4Available = false;
+            }
+            const v3 = await request("/v3/search", { q: params.query, containerTags: [containerTag], limit });
+            if (!ok(v3.status)) {
+                throw new Error(`supermemory v3 search failed: HTTP ${v3.status}`);
+            }
+            return normalizeHits(v3.json, "v3");
+        },
+    };
+}
+function ok(status) {
+    return status >= 200 && status < 300;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Pull the result array from either a `results` or `documents` envelope. */
+function resultsOf(json) {
+    if (!isRecord(json)) {
+        return [];
+    }
+    if (Array.isArray(json.results)) {
+        return json.results;
+    }
+    if (Array.isArray(json.documents)) {
+        return json.documents;
+    }
+    return [];
+}
+/**
+ * Normalize a search response into ranked hits. v4 carries text under `memory`/`chunk` and the score
+ * under `similarity`; legacy v3 carries text under `content`/`chunks[].content` and the score under
+ * `score`. Malformed/empty rows are dropped rather than throwing.
+ */
+function normalizeHits(json, shape) {
+    const hits = [];
+    for (const row of resultsOf(json)) {
+        if (!isRecord(row)) {
+            continue;
+        }
+        // v4 identifies hits as `id`; the legacy v3 route uses `documentId` (fall back to `id`).
+        const idField = shape === "v4" ? row.id : row.documentId ?? row.id;
+        const id = typeof idField === "string" ? idField : "";
+        const text = shape === "v4" ? textV4(row) : textV3(row);
+        if (text.trim().length === 0) {
+            continue;
+        }
+        const rawScore = shape === "v4" ? row.similarity : row.score;
+        const score = typeof rawScore === "number" && Number.isFinite(rawScore) ? rawScore : 0;
+        hits.push({ id, text, score });
+    }
+    return hits;
+}
+function textV4(row) {
+    if (typeof row.memory === "string") {
+        return row.memory;
+    }
+    if (typeof row.chunk === "string") {
+        return row.chunk;
+    }
+    return "";
+}
+function textV3(row) {
+    if (typeof row.content === "string") {
+        return row.content;
+    }
+    if (Array.isArray(row.chunks)) {
+        const first = row.chunks.find((c) => isRecord(c) && typeof c.content === "string");
+        if (isRecord(first) && typeof first.content === "string") {
+            return first.content;
+        }
+    }
+    return "";
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/format.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryBlock } from "@mono-agent/agent-contracts";
+import type { SupermemoryHit } from "./client.js";
+export declare const SUPERMEMORY_SOURCE = "supermemory";
+/**
+ * Render ranked Supermemory hits into a markdown {@link MemoryBlock}, capped at `maxBytes`. Each hit
+ * is one bullet `- (score) text` with whitespace collapsed. The block is truncated on a byte boundary
+ * (with `truncated: true`) so it never blows the per-turn recall budget.
+ */
+export declare function formatHitsAsBlock(hits: readonly SupermemoryHit[], maxBytes: number): MemoryBlock;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAkBhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAWhG"}

package/dist/format.js

@@ -0,0 +1,33 @@
+export const SUPERMEMORY_SOURCE = "supermemory";
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/** Truncate to at most `maxBytes` UTF-8 bytes on a character boundary. */
+function truncateToBytes(text, maxBytes) {
+    if (byteLength(text) <= maxBytes) {
+        return text;
+    }
+    let end = Math.min(text.length, maxBytes);
+    while (end > 0 && byteLength(text.slice(0, end)) > maxBytes) {
+        end -= 1;
+    }
+    return text.slice(0, end);
+}
+/**
+ * Render ranked Supermemory hits into a markdown {@link MemoryBlock}, capped at `maxBytes`. Each hit
+ * is one bullet `- (score) text` with whitespace collapsed. The block is truncated on a byte boundary
+ * (with `truncated: true`) so it never blows the per-turn recall budget.
+ */
+export function formatHitsAsBlock(hits, maxBytes) {
+    const full = hits
+        .map((hit) => `- (${hit.score.toFixed(3)}) ${hit.text.replace(/\s+/gu, " ").trim()}`)
+        .join("\n");
+    const truncated = byteLength(full) > maxBytes;
+    return {
+        kind: "markdown",
+        content: truncated ? truncateToBytes(full, maxBytes) : full,
+        source: SUPERMEMORY_SOURCE,
+        truncated,
+    };
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEhD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED,0EAA0E;AAC1E,SAAS,eAAe,CAAC,IAAY,EAAE,QAAgB;IACrD,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC1C,OAAO,GAAG,GAAG,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;QAC5D,GAAG,IAAI,CAAC,CAAC;IACX,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA+B,EAAE,QAAgB;IACjF,MAAM,IAAI,GAAG,IAAI;SACd,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;SACpF,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;IAC9C,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QAC3D,MAAM,EAAE,kBAAkB;QAC1B,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { SupermemorySearchMode } from "./client.js";
+import { SupermemoryMemoryStore } from "./store.js";
+export { createSupermemoryHttpClient } from "./client.js";
+export type { SupermemoryAddParams, SupermemoryClient, SupermemoryFetch, SupermemoryFetchResponse, SupermemoryHit, SupermemoryHttpClientConfig, SupermemoryMetadataValue, SupermemorySearchMode, SupermemorySearchParams, } from "./client.js";
+export { formatHitsAsBlock, SUPERMEMORY_SOURCE } from "./format.js";
+export { SupermemoryMemoryStore } from "./store.js";
+export type { SupermemoryRecallHit, SupermemoryStoreOptions } from "./store.js";
+/** Config for the convenience factory that wires an HTTP client + store in one call. */
+export interface CreateSupermemoryStoreConfig {
+    readonly baseUrl: string;
+    readonly apiKey?: string;
+    /** Namespace tag scoping this agent's memories. */
+    readonly container: string;
+    readonly timeoutMs?: number;
+    readonly maxBytes?: number;
+    readonly searchLimit?: number;
+    readonly searchMode?: SupermemorySearchMode;
+    readonly threshold?: number;
+    readonly rerank?: boolean;
+    readonly logger?: {
+        warn(message: string): void;
+    };
+}
+/** 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

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,24 @@
+import { createSupermemoryHttpClient } from "./client.js";
+import { SupermemoryMemoryStore } from "./store.js";
+export { createSupermemoryHttpClient } from "./client.js";
+export { formatHitsAsBlock, SUPERMEMORY_SOURCE } from "./format.js";
+export { SupermemoryMemoryStore } from "./store.js";
+/** Build a {@link SupermemoryMemoryStore} over the REST client. The single entry point hosts use. */
+export function createSupermemoryStore(config) {
+    const client = createSupermemoryHttpClient({
+        baseUrl: config.baseUrl,
+        containerTag: config.container,
+        ...(config.apiKey === undefined ? {} : { apiKey: config.apiKey }),
+        ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
+        ...(config.searchLimit === undefined ? {} : { searchLimit: config.searchLimit }),
+        ...(config.searchMode === undefined ? {} : { searchMode: config.searchMode }),
+        ...(config.threshold === undefined ? {} : { threshold: config.threshold }),
+        ...(config.rerank === undefined ? {} : { rerank: config.rerank }),
+    });
+    return new SupermemoryMemoryStore(client, {
+        ...(config.maxBytes === undefined ? {} : { maxBytes: config.maxBytes }),
+        ...(config.searchLimit === undefined ? {} : { recallLimit: config.searchLimit }),
+        ...(config.logger === undefined ? {} : { logger: config.logger }),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/store.d.ts

@@ -0,0 +1,54 @@
+import type { MemoryBlock, 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. */
+    readonly maxBytes?: number;
+    /** Max hits to request per recall (passed through to the client). */
+    readonly recallLimit?: number;
+    readonly logger?: {
+        warn(message: string): void;
+    };
+}
+/** A recall hit shaped like the bujo store's, so the recall MCP server can format it uniformly. */
+export interface SupermemoryRecallHit {
+    readonly score: number;
+    readonly record: {
+        readonly id: string;
+        readonly text: string;
+    };
+}
+/**
+ * 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.
+ *
+ * `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.
+ */
+export declare class SupermemoryMemoryStore implements MemoryStore {
+    private readonly client;
+    private captureChain;
+    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>;
+    scheduleCapture(conversationId: string, text: string): void;
+    flush(): Promise<void>;
+    /** Drain queued captures (HTTP client owns no handle to close). */
+    close(): Promise<void>;
+    /**
+     * Recall hits shaped for the in-app `memory_recall` MCP tool (Stage 3 reuses the bujo formatter).
+     * Unlike `load`, this propagates client errors so the recall tool can report a search failure.
+     */
+    recall(query: string, options?: {
+        readonly topK?: number;
+    }): Promise<SupermemoryRecallHit[]>;
+    private search;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +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"}

package/dist/store.js

@@ -0,0 +1,101 @@
+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;
+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.
+ *
+ * `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.
+ */
+export class SupermemoryMemoryStore {
+    client;
+    captureChain = Promise.resolve();
+    maxBytes;
+    recallLimit;
+    logger;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.recallLimit = options.recallLimit;
+        this.logger = options.logger ?? NOOP_LOGGER;
+    }
+    async load(conversationId, query) {
+        const q = (query ?? "").trim().length > 0 ? query : conversationId;
+        try {
+            const hits = await this.search(q);
+            if (hits.length === 0) {
+                return undefined;
+            }
+            return formatHitsAsBlock(hits, this.maxBytes);
+        }
+        catch (error) {
+            this.logger.warn(`supermemory recall failed: ${message(error)}`);
+            return undefined;
+        }
+    }
+    async appendHostSummary(conversationId, summary) {
+        const bytes = Buffer.byteLength(summary, "utf8");
+        try {
+            await this.client.add({
+                content: summary,
+                // Idempotent: re-emitting the same one-liner upserts instead of duplicating. Supermemory
+                // customIds allow only [A-Za-z0-9._-], so use a hyphen separator (NOT a colon — that is
+                // rejected, which would silently drop the write).
+                customId: `host-summary-${stableId(`${conversationId}\n${summary}`)}`,
+                metadata: { kind: "host-summary", conversationId },
+            });
+            return { conversationId, source: SUPERMEMORY_SOURCE, bytesWritten: bytes };
+        }
+        catch (error) {
+            this.logger.warn(`supermemory appendHostSummary failed: ${message(error)}`);
+            return { conversationId, source: SUPERMEMORY_SOURCE, bytesWritten: 0 };
+        }
+    }
+    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)}`);
+            }
+        })
+            // Terminal guard: the chain must never settle rejected, or every future capture would be skipped.
+            .catch(() => undefined);
+    }
+    async flush() {
+        await this.captureChain;
+    }
+    /** Drain queued captures (HTTP client owns no handle to close). */
+    async close() {
+        await this.flush();
+    }
+    /**
+     * Recall hits shaped for the in-app `memory_recall` MCP tool (Stage 3 reuses the bujo formatter).
+     * Unlike `load`, this propagates client errors so the recall tool can report a search failure.
+     */
+    async recall(query, options) {
+        const hits = await this.search(query, options?.topK);
+        return hits.map((hit) => ({ score: hit.score, record: { id: hit.id, text: hit.text } }));
+    }
+    async search(query, topK) {
+        const limit = topK ?? this.recallLimit;
+        return this.client.search({ query, ...(limit === undefined ? {} : { limit }) });
+    }
+}
+function stableId(input) {
+    return createHash("sha1").update(input).digest("hex").slice(0, 24);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/package.json

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