@theokit/memory-supermemory 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 2.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @theokit/sdk@1.3.0
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @theokit/sdk@1.2.0
+
+## 0.1.0
+
+### Added
+
+- Initial release. Implements the `MemoryAdapter` contract (ADR D141) over
+  the `supermemory@^4.21.0` SDK. Exposes:
+  - `supermemoryMemory(options)` plugin factory.
+  - `MemoryAdapter.write` → `documents.add` with translated containerTags.
+  - `MemoryAdapter.recall` → `search.memories` with rerank=true.
+  - `MemoryAdapter.delete` → `documents.delete` with EC-B prefix validation.
+  - LLM-callable tool schemas (`memory_write`, `memory_recall`).
+- EC-C identifier sanitizer (`^[a-zA-Z0-9_-]+$`) for every containerTag
+  component — prevents silent cross-bucket leak from `:`/whitespace in
+  userId/agentId/tenantId/tags.
+- Typed error translation: 401/403 → `auth_failed`, 429 → `rate_limited`,
+  404 → `not_found`, network → `network`.

package/README.md

@@ -0,0 +1,82 @@
+# @theokit/memory-supermemory
+
+Supermemory memory adapter for [`@theokit/sdk`](../sdk).
+
+Wraps [`supermemory@^4`](https://www.npmjs.com/package/supermemory) (zero-dep,
+MIT-licensed, native fetch) with the `MemoryAdapter` contract from ADR D141.
+
+## Install
+
+```bash
+pnpm add @theokit/memory-supermemory supermemory
+```
+
+## Usage
+
+```ts
+import { Agent } from "@theokit/sdk";
+import { supermemoryMemory } from "@theokit/memory-supermemory";
+
+const agent = await Agent.create({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  model: { id: "openai/gpt-4o-mini" },
+  local: {},
+  plugins: [supermemoryMemory({ apiKey: process.env.SUPERMEMORY_API_KEY! })],
+  memoryContext: { userId: "demo" },
+});
+
+// Direct API
+await agent.memory.write("User likes Brazilian jazz", { userId: "demo" });
+const facts = await agent.memory.recall("music preferences", { userId: "demo" });
+
+// LLM-driven via tool schemas (registered automatically when toolSchemas: true)
+await agent.send("What music does the user enjoy?");
+```
+
+## Options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | Supermemory API key. Required. |
+| `baseUrl` | `string` | Supermemory cloud | Override for self-hosted deployments. |
+| `containerTagPrefix` | `string` | `"theokit"` | Prefix for every container tag. Useful for test isolation. |
+
+## Container tag scheme
+
+Every memory write is tagged with:
+
+- `${prefix}:user:${userId}` (always)
+- `${prefix}:agent:${agentId}` (when set)
+- `${prefix}:tenant:${tenantId}` (when set)
+- `${prefix}:tag:${tag}` (one per entry in `ctx.tags`)
+
+Each component is sanitized against `^[a-zA-Z0-9_-]+$` (EC-C) — values
+containing `:` or whitespace throw `MemoryAdapterError(code: "invalid_input")`
+at the boundary, before any HTTP call.
+
+## Multi-tenant accumulation (EC-S)
+
+Calling `agent.memory.write` writes durable data to Supermemory tied to
+the supplied `userId`. In bot/CI scenarios where the same `userId` is
+reused across runs, set a unique `containerTagPrefix` per test:
+
+```ts
+supermemoryMemory({
+  apiKey,
+  containerTagPrefix: `theokit-test-${Date.now()}`,
+})
+```
+
+## Failure modes
+
+| HTTP status | Maps to | `isRetryable` |
+|---|---|---|
+| 401 / 403 | `MemoryAdapterError(code: "auth_failed")` | false |
+| 429 | `MemoryAdapterError(code: "rate_limited")` | true |
+| 404 | `MemoryAdapterError(code: "not_found")` | false |
+| Network/timeout | `MemoryAdapterError(code: "network")` | true |
+| Other | `MemoryAdapterError(code: "unknown")` | false |
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -0,0 +1,251 @@
+'use strict';
+
+var sdk = require('@theokit/sdk');
+var SupermemoryClient = require('supermemory');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var SupermemoryClient__default = /*#__PURE__*/_interopDefault(SupermemoryClient);
+
+// src/index.ts
+var SAFE_IDENT = /^[a-zA-Z0-9_-]+$/;
+var ADAPTER_ID = "supermemory";
+function sanitizeIdentifier(value, fieldName) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new sdk.MemoryAdapterError(`Supermemory adapter: ${fieldName} must be a non-empty string`, {
+      adapterId: ADAPTER_ID,
+      code: "invalid_input"
+    });
+  }
+  if (!SAFE_IDENT.test(value)) {
+    throw new sdk.MemoryAdapterError(
+      `Supermemory adapter: ${fieldName} "${value}" contains invalid characters (allowed: a-zA-Z0-9_-)`,
+      { adapterId: ADAPTER_ID, code: "invalid_input" }
+    );
+  }
+  return value;
+}
+function buildContainerTags(ctx, prefix) {
+  const safePrefix = sanitizeIdentifier(prefix, "prefix");
+  const tags = [`${safePrefix}:user:${sanitizeIdentifier(ctx.userId, "userId")}`];
+  if (ctx.agentId !== void 0) {
+    tags.push(`${safePrefix}:agent:${sanitizeIdentifier(ctx.agentId, "agentId")}`);
+  }
+  if (ctx.tenantId !== void 0) {
+    tags.push(`${safePrefix}:tenant:${sanitizeIdentifier(ctx.tenantId, "tenantId")}`);
+  }
+  if (ctx.tags !== void 0) {
+    for (const t of ctx.tags) {
+      tags.push(`${safePrefix}:tag:${sanitizeIdentifier(t, "tag")}`);
+    }
+  }
+  return tags;
+}
+function primaryContainerTag(ctx, prefix) {
+  const safePrefix = sanitizeIdentifier(prefix, "prefix");
+  return `${safePrefix}:user:${sanitizeIdentifier(ctx.userId, "userId")}`;
+}
+
+// src/adapter.ts
+var ADAPTER_ID2 = "supermemory";
+var CAPS = {
+  history: false,
+  sessions: false,
+  tenancy: true,
+  reasoning: false,
+  toolSchemas: true,
+  prefetch: false
+};
+var SupermemoryAdapter = class {
+  id = ADAPTER_ID2;
+  capabilities = CAPS;
+  #opts;
+  #client;
+  constructor(opts) {
+    this.#opts = opts;
+  }
+  isAvailable() {
+    return typeof this.#opts.apiKey === "string" && this.#opts.apiKey.length > 0;
+  }
+  async initialize() {
+  }
+  async write(content, ctx) {
+    const text = this.#renderContent(content);
+    if (text.length === 0) {
+      throw new sdk.MemoryAdapterError("write: empty content", {
+        adapterId: ADAPTER_ID2,
+        code: "invalid_input"
+      });
+    }
+    const containerTags = buildContainerTags(ctx, this.#prefix());
+    try {
+      const resp = await this.#sdk().documents.add({
+        content: text,
+        containerTags,
+        ...ctx.metadata !== void 0 ? { metadata: ctx.metadata } : {}
+      });
+      return sdk.mkMemoryId(ADAPTER_ID2, resp.id);
+    } catch (err) {
+      throw this.#translateError(err, "write");
+    }
+  }
+  async recall(query, ctx, k = 10) {
+    if (k <= 0) return [];
+    const containerTag = primaryContainerTag(ctx, this.#prefix());
+    try {
+      const resp = await this.#sdk().search.memories({
+        q: query,
+        containerTag,
+        limit: k,
+        rerank: true
+      });
+      const results = resp.results ?? [];
+      return results.map(this.#mapResult);
+    } catch (err) {
+      throw this.#translateError(err, "recall");
+    }
+  }
+  async delete(id) {
+    const rawId = sdk.extractRawId(id, ADAPTER_ID2);
+    try {
+      await this.#sdk().documents.delete(rawId);
+    } catch (err) {
+      throw this.#translateError(err, "delete");
+    }
+  }
+  getToolSchemas() {
+    return [
+      {
+        name: "memory_write",
+        description: "Persist a fact about the user or context to Supermemory long-term memory. Returns the stored memory ID.",
+        parameters: {
+          type: "object",
+          properties: {
+            content: { type: "string", description: "Fact text to persist verbatim." }
+          },
+          required: ["content"]
+        }
+      },
+      {
+        name: "memory_recall",
+        description: "Retrieve up to k semantically relevant facts from Supermemory long-term memory. Returns an array of {id, content, score, createdAt} objects.",
+        parameters: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Free-text query to search memory." },
+            k: {
+              type: "integer",
+              minimum: 1,
+              maximum: 50,
+              description: "Max results (default 10)."
+            }
+          },
+          required: ["query"]
+        }
+      }
+    ];
+  }
+  async handleToolCall(name, args, ctx) {
+    if (name === "memory_write") {
+      const content = String(args.content ?? "");
+      const id = await this.write(content, ctx);
+      return JSON.stringify({ ok: true, id });
+    }
+    if (name === "memory_recall") {
+      const query = String(args.query ?? "");
+      const k = typeof args.k === "number" ? args.k : 10;
+      const facts = await this.recall(query, ctx, k);
+      return JSON.stringify({ ok: true, facts });
+    }
+    throw new sdk.MemoryAdapterError(`Unknown tool name: ${name}`, {
+      adapterId: ADAPTER_ID2,
+      code: "invalid_input"
+    });
+  }
+  async shutdown() {
+    this.#client = void 0;
+  }
+  // ── helpers ────────────────────────────────────────────────────────
+  #prefix() {
+    return this.#opts.containerTagPrefix ?? "theokit";
+  }
+  #renderContent(content) {
+    if (typeof content === "string") return content.trim();
+    return content.map((m) => `${m.role}: ${m.content}`).join("\n").trim();
+  }
+  #mapResult = (r) => {
+    const obj = r ?? {};
+    const memory = obj.memory ?? obj;
+    const rawId = String(memory.id ?? obj.id ?? "");
+    const content = String(memory.content ?? memory.text ?? obj.content ?? "");
+    const score = typeof obj.score === "number" ? obj.score : void 0;
+    const createdAt = typeof memory.createdAt === "string" ? memory.createdAt : void 0;
+    return {
+      id: sdk.mkMemoryId(ADAPTER_ID2, rawId),
+      content,
+      ...score !== void 0 ? { score } : {},
+      ...createdAt !== void 0 ? { createdAt } : {}
+    };
+  };
+  #sdk() {
+    if (this.#client === void 0) {
+      this.#client = new SupermemoryClient__default.default({
+        apiKey: this.#opts.apiKey,
+        ...this.#opts.baseUrl !== void 0 ? { baseURL: this.#opts.baseUrl } : {}
+      });
+    }
+    return this.#client;
+  }
+  #translateError(err, op) {
+    if (err instanceof sdk.MemoryAdapterError) return err;
+    const status = err?.status ?? err?.statusCode;
+    const message = err?.message ?? String(err);
+    if (status === 401 || status === 403) {
+      return new sdk.MemoryAdapterError(`Supermemory auth failed (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "auth_failed",
+        cause: err
+      });
+    }
+    if (status === 429) {
+      return new sdk.MemoryAdapterError(`Supermemory rate limited (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "rate_limited",
+        cause: err
+      });
+    }
+    if (status === 404) {
+      return new sdk.MemoryAdapterError(`Supermemory not found (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "not_found",
+        cause: err
+      });
+    }
+    if (status === void 0 && message.toLowerCase().includes("network")) {
+      return new sdk.MemoryAdapterError(`Supermemory network error (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "network",
+        cause: err
+      });
+    }
+    return new sdk.MemoryAdapterError(`Supermemory error (${op}): ${message}`, {
+      adapterId: ADAPTER_ID2,
+      code: "unknown",
+      cause: err
+    });
+  }
+};
+
+// src/index.ts
+function supermemoryMemory(options) {
+  return sdk.definePlugin({
+    name: "@theokit/memory-supermemory",
+    version: "0.1.0",
+    kind: "memory",
+    createProvider: () => new SupermemoryAdapter(options)
+  });
+}
+
+exports.supermemoryMemory = supermemoryMemory;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/translate.ts","../src/adapter.ts","../src/index.ts"],"names":["MemoryAdapterError","ADAPTER_ID","mkMemoryId","extractRawId","SupermemoryClient","definePlugin"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * `MemoryContext` → Supermemory containerTags translation (T3.2).\n *\n * EC-C fix: every component runs through a strict identifier sanitizer\n * (regex `^[a-zA-Z0-9_-]+$`) before being joined with `:`. Rejects with\n * `MemoryAdapterError(code: \"invalid_input\")` on invalid input, so a\n * value like `userId: \"user:123\"` cannot silently land in a different\n * bucket via tag mis-parsing.\n *\n * @internal\n */\n\nimport type { MemoryContext } from \"@theokit/sdk\";\nimport { MemoryAdapterError } from \"@theokit/sdk\";\n\nconst SAFE_IDENT = /^[a-zA-Z0-9_-]+$/;\nconst ADAPTER_ID = \"supermemory\";\n\nexport function sanitizeIdentifier(value: string, fieldName: string): string {\n  if (typeof value !== \"string\" || value.length === 0) {\n    throw new MemoryAdapterError(`Supermemory adapter: ${fieldName} must be a non-empty string`, {\n      adapterId: ADAPTER_ID,\n      code: \"invalid_input\",\n    });\n  }\n  if (!SAFE_IDENT.test(value)) {\n    throw new MemoryAdapterError(\n      `Supermemory adapter: ${fieldName} \"${value}\" contains invalid characters (allowed: a-zA-Z0-9_-)`,\n      { adapterId: ADAPTER_ID, code: \"invalid_input\" },\n    );\n  }\n  return value;\n}\n\n/**\n * Build the array of containerTags for `documents.add`. Each component\n * is sanitized; collisions across tag namespaces (user/agent/tenant/tag)\n * are intentional — Supermemory treats containerTags as a set.\n *\n * @internal\n */\nexport function buildContainerTags(ctx: MemoryContext, prefix: string): string[] {\n  const safePrefix = sanitizeIdentifier(prefix, \"prefix\");\n  const tags: string[] = [`${safePrefix}:user:${sanitizeIdentifier(ctx.userId, \"userId\")}`];\n  if (ctx.agentId !== undefined) {\n    tags.push(`${safePrefix}:agent:${sanitizeIdentifier(ctx.agentId, \"agentId\")}`);\n  }\n  if (ctx.tenantId !== undefined) {\n    tags.push(`${safePrefix}:tenant:${sanitizeIdentifier(ctx.tenantId, \"tenantId\")}`);\n  }\n  if (ctx.tags !== undefined) {\n    for (const t of ctx.tags) {\n      tags.push(`${safePrefix}:tag:${sanitizeIdentifier(t, \"tag\")}`);\n    }\n  }\n  return tags;\n}\n\n/**\n * Pick the primary containerTag for `search.memories` (which takes a\n * single string, not an array). The user tag is canonical.\n *\n * @internal\n */\nexport function primaryContainerTag(ctx: MemoryContext, prefix: string): string {\n  const safePrefix = sanitizeIdentifier(prefix, \"prefix\");\n  return `${safePrefix}:user:${sanitizeIdentifier(ctx.userId, \"userId\")}`;\n}\n","/**\n * SupermemoryAdapter — `@theokit-memory-supermemory` core (T3.2, ADR D141).\n *\n * Wraps `supermemory` SDK v4. Implements `MemoryAdapter` so the SDK's\n * `pre_user_send` / `post_assistant_reply` hooks (D145) and\n * `agent.memory.*` direct API (D142) work end-to-end against Supermemory's\n * managed memory + RAG service.\n *\n * @public\n */\n\nimport {\n  extractRawId,\n  type MemoryAdapter,\n  type MemoryAdapterCapabilities,\n  MemoryAdapterError,\n  type MemoryContext,\n  type MemoryFact,\n  type MemoryId,\n  type MemoryToolSchema,\n  type MemoryTurnMessage,\n  mkMemoryId,\n} from \"@theokit/sdk\";\nimport type Supermemory from \"supermemory\";\nimport SupermemoryClient from \"supermemory\";\n\nimport { buildContainerTags, primaryContainerTag } from \"./translate.js\";\n\n/** Configuration accepted by the `supermemoryMemory(...)` factory. @public */\nexport interface SupermemoryAdapterOptions {\n  /** Supermemory API key. Falls back to `SUPERMEMORY_API_KEY`. */\n  apiKey: string;\n  /** Base URL override for self-hosted Supermemory deployments. */\n  baseUrl?: string;\n  /** Prefix for every containerTag (default `\"theokit\"`). Useful for test isolation (EC-S). */\n  containerTagPrefix?: string;\n}\n\nconst ADAPTER_ID = \"supermemory\";\n\nconst CAPS: MemoryAdapterCapabilities = {\n  history: false,\n  sessions: false,\n  tenancy: true,\n  reasoning: false,\n  toolSchemas: true,\n  prefetch: false,\n};\n\n/**\n * SDK-internal adapter class. Construct via `supermemoryMemory(...)`\n * factory from `./index.ts`, not directly.\n *\n * @internal\n */\nexport class SupermemoryAdapter implements MemoryAdapter {\n  readonly id = ADAPTER_ID;\n  readonly capabilities = CAPS;\n  readonly #opts: SupermemoryAdapterOptions;\n  #client?: Supermemory;\n\n  constructor(opts: SupermemoryAdapterOptions) {\n    this.#opts = opts;\n  }\n\n  isAvailable(): boolean {\n    return typeof this.#opts.apiKey === \"string\" && this.#opts.apiKey.length > 0;\n  }\n\n  async initialize(): Promise<void> {\n    // Lazy: defer the actual client construction until first call.\n    // initialize() is idempotent — see EC-3 / EC-I.\n  }\n\n  async write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId> {\n    const text = this.#renderContent(content);\n    if (text.length === 0) {\n      throw new MemoryAdapterError(\"write: empty content\", {\n        adapterId: ADAPTER_ID,\n        code: \"invalid_input\",\n      });\n    }\n    const containerTags = buildContainerTags(ctx, this.#prefix());\n    try {\n      const resp = await this.#sdk().documents.add({\n        content: text,\n        containerTags,\n        ...(ctx.metadata !== undefined ? { metadata: ctx.metadata as Record<string, string> } : {}),\n      });\n      return mkMemoryId(ADAPTER_ID, resp.id);\n    } catch (err) {\n      throw this.#translateError(err, \"write\");\n    }\n  }\n\n  async recall(query: string, ctx: MemoryContext, k = 10): Promise<MemoryFact[]> {\n    if (k <= 0) return [];\n    const containerTag = primaryContainerTag(ctx, this.#prefix());\n    try {\n      const resp = await this.#sdk().search.memories({\n        q: query,\n        containerTag,\n        limit: k,\n        rerank: true,\n      });\n      const results = resp.results ?? [];\n      return results.map(this.#mapResult);\n    } catch (err) {\n      throw this.#translateError(err, \"recall\");\n    }\n  }\n\n  async delete(id: MemoryId): Promise<void> {\n    const rawId = extractRawId(id, ADAPTER_ID);\n    try {\n      await this.#sdk().documents.delete(rawId);\n    } catch (err) {\n      throw this.#translateError(err, \"delete\");\n    }\n  }\n\n  getToolSchemas(): MemoryToolSchema[] {\n    return [\n      {\n        name: \"memory_write\",\n        description:\n          \"Persist a fact about the user or context to Supermemory long-term memory. \" +\n          \"Returns the stored memory ID.\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            content: { type: \"string\", description: \"Fact text to persist verbatim.\" },\n          },\n          required: [\"content\"],\n        },\n      },\n      {\n        name: \"memory_recall\",\n        description:\n          \"Retrieve up to k semantically relevant facts from Supermemory long-term memory. \" +\n          \"Returns an array of {id, content, score, createdAt} objects.\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            query: { type: \"string\", description: \"Free-text query to search memory.\" },\n            k: {\n              type: \"integer\",\n              minimum: 1,\n              maximum: 50,\n              description: \"Max results (default 10).\",\n            },\n          },\n          required: [\"query\"],\n        },\n      },\n    ];\n  }\n\n  async handleToolCall(\n    name: string,\n    args: Record<string, unknown>,\n    ctx: MemoryContext,\n  ): Promise<string> {\n    if (name === \"memory_write\") {\n      const content = String(args.content ?? \"\");\n      const id = await this.write(content, ctx);\n      return JSON.stringify({ ok: true, id });\n    }\n    if (name === \"memory_recall\") {\n      const query = String(args.query ?? \"\");\n      const k = typeof args.k === \"number\" ? args.k : 10;\n      const facts = await this.recall(query, ctx, k);\n      return JSON.stringify({ ok: true, facts });\n    }\n    throw new MemoryAdapterError(`Unknown tool name: ${name}`, {\n      adapterId: ADAPTER_ID,\n      code: \"invalid_input\",\n    });\n  }\n\n  async shutdown(): Promise<void> {\n    this.#client = undefined;\n  }\n\n  // ── helpers ────────────────────────────────────────────────────────\n\n  #prefix(): string {\n    return this.#opts.containerTagPrefix ?? \"theokit\";\n  }\n\n  #renderContent(content: string | MemoryTurnMessage[]): string {\n    if (typeof content === \"string\") return content.trim();\n    return content\n      .map((m) => `${m.role}: ${m.content}`)\n      .join(\"\\n\")\n      .trim();\n  }\n\n  #mapResult = (r: unknown): MemoryFact => {\n    const obj = (r as Record<string, unknown>) ?? {};\n    // SDK shape: { memory?: { id, content, ... }, score, ... } or chunk shape.\n    const memory = (obj.memory as Record<string, unknown> | undefined) ?? obj;\n    const rawId = String(memory.id ?? obj.id ?? \"\");\n    const content = String(memory.content ?? memory.text ?? obj.content ?? \"\");\n    const score = typeof obj.score === \"number\" ? obj.score : undefined;\n    const createdAt = typeof memory.createdAt === \"string\" ? memory.createdAt : undefined;\n    return {\n      id: mkMemoryId(ADAPTER_ID, rawId),\n      content,\n      ...(score !== undefined ? { score } : {}),\n      ...(createdAt !== undefined ? { createdAt } : {}),\n    };\n  };\n\n  #sdk(): Supermemory {\n    if (this.#client === undefined) {\n      this.#client = new SupermemoryClient({\n        apiKey: this.#opts.apiKey,\n        ...(this.#opts.baseUrl !== undefined ? { baseURL: this.#opts.baseUrl } : {}),\n      });\n    }\n    return this.#client;\n  }\n\n  #translateError(err: unknown, op: string): MemoryAdapterError {\n    if (err instanceof MemoryAdapterError) return err;\n    const status =\n      (err as { status?: number; statusCode?: number })?.status ??\n      (err as { statusCode?: number })?.statusCode;\n    const message = (err as Error)?.message ?? String(err);\n    if (status === 401 || status === 403) {\n      return new MemoryAdapterError(`Supermemory auth failed (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"auth_failed\",\n        cause: err,\n      });\n    }\n    if (status === 429) {\n      return new MemoryAdapterError(`Supermemory rate limited (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"rate_limited\",\n        cause: err,\n      });\n    }\n    if (status === 404) {\n      return new MemoryAdapterError(`Supermemory not found (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"not_found\",\n        cause: err,\n      });\n    }\n    if (status === undefined && message.toLowerCase().includes(\"network\")) {\n      return new MemoryAdapterError(`Supermemory network error (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"network\",\n        cause: err,\n      });\n    }\n    return new MemoryAdapterError(`Supermemory error (${op}): ${message}`, {\n      adapterId: ADAPTER_ID,\n      code: \"unknown\",\n      cause: err,\n    });\n  }\n}\n","/**\n * `@theokit/memory-supermemory` — Supermemory memory adapter for @theokit/sdk.\n *\n * Usage:\n *\n * ```ts\n * import { Agent } from \"@theokit/sdk\";\n * import { supermemoryMemory } from \"@theokit/memory-supermemory\";\n *\n * const agent = await Agent.create({\n *   apiKey: process.env.OPENROUTER_API_KEY,\n *   model: { id: \"openai/gpt-4o-mini\" },\n *   local: {},\n *   plugins: [supermemoryMemory({ apiKey: process.env.SUPERMEMORY_API_KEY! })],\n *   memoryContext: { userId: \"demo\" },\n * });\n *\n * await agent.memory.write(\"User likes Brazilian jazz\", { userId: \"demo\" });\n * const facts = await agent.memory.recall(\"music preferences\", { userId: \"demo\" });\n * ```\n *\n * @public\n */\n\nimport type { Plugin } from \"@theokit/sdk\";\nimport { definePlugin } from \"@theokit/sdk\";\n\nimport { SupermemoryAdapter, type SupermemoryAdapterOptions } from \"./adapter.js\";\n\nexport type { SupermemoryAdapterOptions } from \"./adapter.js\";\n\n/**\n * Build a `Plugin { kind: \"memory\" }` ready to pass to\n * `Agent.create({ plugins: [...] })`.\n *\n * @public\n */\nexport function supermemoryMemory(options: SupermemoryAdapterOptions): Plugin {\n  return definePlugin({\n    name: \"@theokit/memory-supermemory\",\n    version: \"0.1.0\",\n    kind: \"memory\",\n    createProvider: () => new SupermemoryAdapter(options),\n  });\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,55 @@
+import { Plugin } from '@theokit/sdk';
+
+/**
+ * SupermemoryAdapter — `@theokit-memory-supermemory` core (T3.2, ADR D141).
+ *
+ * Wraps `supermemory` SDK v4. Implements `MemoryAdapter` so the SDK's
+ * `pre_user_send` / `post_assistant_reply` hooks (D145) and
+ * `agent.memory.*` direct API (D142) work end-to-end against Supermemory's
+ * managed memory + RAG service.
+ *
+ * @public
+ */
+/** Configuration accepted by the `supermemoryMemory(...)` factory. @public */
+interface SupermemoryAdapterOptions {
+    /** Supermemory API key. Falls back to `SUPERMEMORY_API_KEY`. */
+    apiKey: string;
+    /** Base URL override for self-hosted Supermemory deployments. */
+    baseUrl?: string;
+    /** Prefix for every containerTag (default `"theokit"`). Useful for test isolation (EC-S). */
+    containerTagPrefix?: string;
+}
+
+/**
+ * `@theokit/memory-supermemory` — Supermemory memory adapter for @theokit/sdk.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { Agent } from "@theokit/sdk";
+ * import { supermemoryMemory } from "@theokit/memory-supermemory";
+ *
+ * const agent = await Agent.create({
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ *   model: { id: "openai/gpt-4o-mini" },
+ *   local: {},
+ *   plugins: [supermemoryMemory({ apiKey: process.env.SUPERMEMORY_API_KEY! })],
+ *   memoryContext: { userId: "demo" },
+ * });
+ *
+ * await agent.memory.write("User likes Brazilian jazz", { userId: "demo" });
+ * const facts = await agent.memory.recall("music preferences", { userId: "demo" });
+ * ```
+ *
+ * @public
+ */
+
+/**
+ * Build a `Plugin { kind: "memory" }` ready to pass to
+ * `Agent.create({ plugins: [...] })`.
+ *
+ * @public
+ */
+declare function supermemoryMemory(options: SupermemoryAdapterOptions): Plugin;
+
+export { type SupermemoryAdapterOptions, supermemoryMemory };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { Plugin } from '@theokit/sdk';
+
+/**
+ * SupermemoryAdapter — `@theokit-memory-supermemory` core (T3.2, ADR D141).
+ *
+ * Wraps `supermemory` SDK v4. Implements `MemoryAdapter` so the SDK's
+ * `pre_user_send` / `post_assistant_reply` hooks (D145) and
+ * `agent.memory.*` direct API (D142) work end-to-end against Supermemory's
+ * managed memory + RAG service.
+ *
+ * @public
+ */
+/** Configuration accepted by the `supermemoryMemory(...)` factory. @public */
+interface SupermemoryAdapterOptions {
+    /** Supermemory API key. Falls back to `SUPERMEMORY_API_KEY`. */
+    apiKey: string;
+    /** Base URL override for self-hosted Supermemory deployments. */
+    baseUrl?: string;
+    /** Prefix for every containerTag (default `"theokit"`). Useful for test isolation (EC-S). */
+    containerTagPrefix?: string;
+}
+
+/**
+ * `@theokit/memory-supermemory` — Supermemory memory adapter for @theokit/sdk.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { Agent } from "@theokit/sdk";
+ * import { supermemoryMemory } from "@theokit/memory-supermemory";
+ *
+ * const agent = await Agent.create({
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ *   model: { id: "openai/gpt-4o-mini" },
+ *   local: {},
+ *   plugins: [supermemoryMemory({ apiKey: process.env.SUPERMEMORY_API_KEY! })],
+ *   memoryContext: { userId: "demo" },
+ * });
+ *
+ * await agent.memory.write("User likes Brazilian jazz", { userId: "demo" });
+ * const facts = await agent.memory.recall("music preferences", { userId: "demo" });
+ * ```
+ *
+ * @public
+ */
+
+/**
+ * Build a `Plugin { kind: "memory" }` ready to pass to
+ * `Agent.create({ plugins: [...] })`.
+ *
+ * @public
+ */
+declare function supermemoryMemory(options: SupermemoryAdapterOptions): Plugin;
+
+export { type SupermemoryAdapterOptions, supermemoryMemory };

package/dist/index.js

@@ -0,0 +1,245 @@
+import { definePlugin, MemoryAdapterError, mkMemoryId, extractRawId } from '@theokit/sdk';
+import SupermemoryClient from 'supermemory';
+
+// src/index.ts
+var SAFE_IDENT = /^[a-zA-Z0-9_-]+$/;
+var ADAPTER_ID = "supermemory";
+function sanitizeIdentifier(value, fieldName) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new MemoryAdapterError(`Supermemory adapter: ${fieldName} must be a non-empty string`, {
+      adapterId: ADAPTER_ID,
+      code: "invalid_input"
+    });
+  }
+  if (!SAFE_IDENT.test(value)) {
+    throw new MemoryAdapterError(
+      `Supermemory adapter: ${fieldName} "${value}" contains invalid characters (allowed: a-zA-Z0-9_-)`,
+      { adapterId: ADAPTER_ID, code: "invalid_input" }
+    );
+  }
+  return value;
+}
+function buildContainerTags(ctx, prefix) {
+  const safePrefix = sanitizeIdentifier(prefix, "prefix");
+  const tags = [`${safePrefix}:user:${sanitizeIdentifier(ctx.userId, "userId")}`];
+  if (ctx.agentId !== void 0) {
+    tags.push(`${safePrefix}:agent:${sanitizeIdentifier(ctx.agentId, "agentId")}`);
+  }
+  if (ctx.tenantId !== void 0) {
+    tags.push(`${safePrefix}:tenant:${sanitizeIdentifier(ctx.tenantId, "tenantId")}`);
+  }
+  if (ctx.tags !== void 0) {
+    for (const t of ctx.tags) {
+      tags.push(`${safePrefix}:tag:${sanitizeIdentifier(t, "tag")}`);
+    }
+  }
+  return tags;
+}
+function primaryContainerTag(ctx, prefix) {
+  const safePrefix = sanitizeIdentifier(prefix, "prefix");
+  return `${safePrefix}:user:${sanitizeIdentifier(ctx.userId, "userId")}`;
+}
+
+// src/adapter.ts
+var ADAPTER_ID2 = "supermemory";
+var CAPS = {
+  history: false,
+  sessions: false,
+  tenancy: true,
+  reasoning: false,
+  toolSchemas: true,
+  prefetch: false
+};
+var SupermemoryAdapter = class {
+  id = ADAPTER_ID2;
+  capabilities = CAPS;
+  #opts;
+  #client;
+  constructor(opts) {
+    this.#opts = opts;
+  }
+  isAvailable() {
+    return typeof this.#opts.apiKey === "string" && this.#opts.apiKey.length > 0;
+  }
+  async initialize() {
+  }
+  async write(content, ctx) {
+    const text = this.#renderContent(content);
+    if (text.length === 0) {
+      throw new MemoryAdapterError("write: empty content", {
+        adapterId: ADAPTER_ID2,
+        code: "invalid_input"
+      });
+    }
+    const containerTags = buildContainerTags(ctx, this.#prefix());
+    try {
+      const resp = await this.#sdk().documents.add({
+        content: text,
+        containerTags,
+        ...ctx.metadata !== void 0 ? { metadata: ctx.metadata } : {}
+      });
+      return mkMemoryId(ADAPTER_ID2, resp.id);
+    } catch (err) {
+      throw this.#translateError(err, "write");
+    }
+  }
+  async recall(query, ctx, k = 10) {
+    if (k <= 0) return [];
+    const containerTag = primaryContainerTag(ctx, this.#prefix());
+    try {
+      const resp = await this.#sdk().search.memories({
+        q: query,
+        containerTag,
+        limit: k,
+        rerank: true
+      });
+      const results = resp.results ?? [];
+      return results.map(this.#mapResult);
+    } catch (err) {
+      throw this.#translateError(err, "recall");
+    }
+  }
+  async delete(id) {
+    const rawId = extractRawId(id, ADAPTER_ID2);
+    try {
+      await this.#sdk().documents.delete(rawId);
+    } catch (err) {
+      throw this.#translateError(err, "delete");
+    }
+  }
+  getToolSchemas() {
+    return [
+      {
+        name: "memory_write",
+        description: "Persist a fact about the user or context to Supermemory long-term memory. Returns the stored memory ID.",
+        parameters: {
+          type: "object",
+          properties: {
+            content: { type: "string", description: "Fact text to persist verbatim." }
+          },
+          required: ["content"]
+        }
+      },
+      {
+        name: "memory_recall",
+        description: "Retrieve up to k semantically relevant facts from Supermemory long-term memory. Returns an array of {id, content, score, createdAt} objects.",
+        parameters: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Free-text query to search memory." },
+            k: {
+              type: "integer",
+              minimum: 1,
+              maximum: 50,
+              description: "Max results (default 10)."
+            }
+          },
+          required: ["query"]
+        }
+      }
+    ];
+  }
+  async handleToolCall(name, args, ctx) {
+    if (name === "memory_write") {
+      const content = String(args.content ?? "");
+      const id = await this.write(content, ctx);
+      return JSON.stringify({ ok: true, id });
+    }
+    if (name === "memory_recall") {
+      const query = String(args.query ?? "");
+      const k = typeof args.k === "number" ? args.k : 10;
+      const facts = await this.recall(query, ctx, k);
+      return JSON.stringify({ ok: true, facts });
+    }
+    throw new MemoryAdapterError(`Unknown tool name: ${name}`, {
+      adapterId: ADAPTER_ID2,
+      code: "invalid_input"
+    });
+  }
+  async shutdown() {
+    this.#client = void 0;
+  }
+  // ── helpers ────────────────────────────────────────────────────────
+  #prefix() {
+    return this.#opts.containerTagPrefix ?? "theokit";
+  }
+  #renderContent(content) {
+    if (typeof content === "string") return content.trim();
+    return content.map((m) => `${m.role}: ${m.content}`).join("\n").trim();
+  }
+  #mapResult = (r) => {
+    const obj = r ?? {};
+    const memory = obj.memory ?? obj;
+    const rawId = String(memory.id ?? obj.id ?? "");
+    const content = String(memory.content ?? memory.text ?? obj.content ?? "");
+    const score = typeof obj.score === "number" ? obj.score : void 0;
+    const createdAt = typeof memory.createdAt === "string" ? memory.createdAt : void 0;
+    return {
+      id: mkMemoryId(ADAPTER_ID2, rawId),
+      content,
+      ...score !== void 0 ? { score } : {},
+      ...createdAt !== void 0 ? { createdAt } : {}
+    };
+  };
+  #sdk() {
+    if (this.#client === void 0) {
+      this.#client = new SupermemoryClient({
+        apiKey: this.#opts.apiKey,
+        ...this.#opts.baseUrl !== void 0 ? { baseURL: this.#opts.baseUrl } : {}
+      });
+    }
+    return this.#client;
+  }
+  #translateError(err, op) {
+    if (err instanceof MemoryAdapterError) return err;
+    const status = err?.status ?? err?.statusCode;
+    const message = err?.message ?? String(err);
+    if (status === 401 || status === 403) {
+      return new MemoryAdapterError(`Supermemory auth failed (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "auth_failed",
+        cause: err
+      });
+    }
+    if (status === 429) {
+      return new MemoryAdapterError(`Supermemory rate limited (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "rate_limited",
+        cause: err
+      });
+    }
+    if (status === 404) {
+      return new MemoryAdapterError(`Supermemory not found (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "not_found",
+        cause: err
+      });
+    }
+    if (status === void 0 && message.toLowerCase().includes("network")) {
+      return new MemoryAdapterError(`Supermemory network error (${op}): ${message}`, {
+        adapterId: ADAPTER_ID2,
+        code: "network",
+        cause: err
+      });
+    }
+    return new MemoryAdapterError(`Supermemory error (${op}): ${message}`, {
+      adapterId: ADAPTER_ID2,
+      code: "unknown",
+      cause: err
+    });
+  }
+};
+
+// src/index.ts
+function supermemoryMemory(options) {
+  return definePlugin({
+    name: "@theokit/memory-supermemory",
+    version: "0.1.0",
+    kind: "memory",
+    createProvider: () => new SupermemoryAdapter(options)
+  });
+}
+
+export { supermemoryMemory };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/translate.ts","../src/adapter.ts","../src/index.ts"],"names":["ADAPTER_ID","MemoryAdapterError"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `MemoryContext` → Supermemory containerTags translation (T3.2).\n *\n * EC-C fix: every component runs through a strict identifier sanitizer\n * (regex `^[a-zA-Z0-9_-]+$`) before being joined with `:`. Rejects with\n * `MemoryAdapterError(code: \"invalid_input\")` on invalid input, so a\n * value like `userId: \"user:123\"` cannot silently land in a different\n * bucket via tag mis-parsing.\n *\n * @internal\n */\n\nimport type { MemoryContext } from \"@theokit/sdk\";\nimport { MemoryAdapterError } from \"@theokit/sdk\";\n\nconst SAFE_IDENT = /^[a-zA-Z0-9_-]+$/;\nconst ADAPTER_ID = \"supermemory\";\n\nexport function sanitizeIdentifier(value: string, fieldName: string): string {\n  if (typeof value !== \"string\" || value.length === 0) {\n    throw new MemoryAdapterError(`Supermemory adapter: ${fieldName} must be a non-empty string`, {\n      adapterId: ADAPTER_ID,\n      code: \"invalid_input\",\n    });\n  }\n  if (!SAFE_IDENT.test(value)) {\n    throw new MemoryAdapterError(\n      `Supermemory adapter: ${fieldName} \"${value}\" contains invalid characters (allowed: a-zA-Z0-9_-)`,\n      { adapterId: ADAPTER_ID, code: \"invalid_input\" },\n    );\n  }\n  return value;\n}\n\n/**\n * Build the array of containerTags for `documents.add`. Each component\n * is sanitized; collisions across tag namespaces (user/agent/tenant/tag)\n * are intentional — Supermemory treats containerTags as a set.\n *\n * @internal\n */\nexport function buildContainerTags(ctx: MemoryContext, prefix: string): string[] {\n  const safePrefix = sanitizeIdentifier(prefix, \"prefix\");\n  const tags: string[] = [`${safePrefix}:user:${sanitizeIdentifier(ctx.userId, \"userId\")}`];\n  if (ctx.agentId !== undefined) {\n    tags.push(`${safePrefix}:agent:${sanitizeIdentifier(ctx.agentId, \"agentId\")}`);\n  }\n  if (ctx.tenantId !== undefined) {\n    tags.push(`${safePrefix}:tenant:${sanitizeIdentifier(ctx.tenantId, \"tenantId\")}`);\n  }\n  if (ctx.tags !== undefined) {\n    for (const t of ctx.tags) {\n      tags.push(`${safePrefix}:tag:${sanitizeIdentifier(t, \"tag\")}`);\n    }\n  }\n  return tags;\n}\n\n/**\n * Pick the primary containerTag for `search.memories` (which takes a\n * single string, not an array). The user tag is canonical.\n *\n * @internal\n */\nexport function primaryContainerTag(ctx: MemoryContext, prefix: string): string {\n  const safePrefix = sanitizeIdentifier(prefix, \"prefix\");\n  return `${safePrefix}:user:${sanitizeIdentifier(ctx.userId, \"userId\")}`;\n}\n","/**\n * SupermemoryAdapter — `@theokit-memory-supermemory` core (T3.2, ADR D141).\n *\n * Wraps `supermemory` SDK v4. Implements `MemoryAdapter` so the SDK's\n * `pre_user_send` / `post_assistant_reply` hooks (D145) and\n * `agent.memory.*` direct API (D142) work end-to-end against Supermemory's\n * managed memory + RAG service.\n *\n * @public\n */\n\nimport {\n  extractRawId,\n  type MemoryAdapter,\n  type MemoryAdapterCapabilities,\n  MemoryAdapterError,\n  type MemoryContext,\n  type MemoryFact,\n  type MemoryId,\n  type MemoryToolSchema,\n  type MemoryTurnMessage,\n  mkMemoryId,\n} from \"@theokit/sdk\";\nimport type Supermemory from \"supermemory\";\nimport SupermemoryClient from \"supermemory\";\n\nimport { buildContainerTags, primaryContainerTag } from \"./translate.js\";\n\n/** Configuration accepted by the `supermemoryMemory(...)` factory. @public */\nexport interface SupermemoryAdapterOptions {\n  /** Supermemory API key. Falls back to `SUPERMEMORY_API_KEY`. */\n  apiKey: string;\n  /** Base URL override for self-hosted Supermemory deployments. */\n  baseUrl?: string;\n  /** Prefix for every containerTag (default `\"theokit\"`). Useful for test isolation (EC-S). */\n  containerTagPrefix?: string;\n}\n\nconst ADAPTER_ID = \"supermemory\";\n\nconst CAPS: MemoryAdapterCapabilities = {\n  history: false,\n  sessions: false,\n  tenancy: true,\n  reasoning: false,\n  toolSchemas: true,\n  prefetch: false,\n};\n\n/**\n * SDK-internal adapter class. Construct via `supermemoryMemory(...)`\n * factory from `./index.ts`, not directly.\n *\n * @internal\n */\nexport class SupermemoryAdapter implements MemoryAdapter {\n  readonly id = ADAPTER_ID;\n  readonly capabilities = CAPS;\n  readonly #opts: SupermemoryAdapterOptions;\n  #client?: Supermemory;\n\n  constructor(opts: SupermemoryAdapterOptions) {\n    this.#opts = opts;\n  }\n\n  isAvailable(): boolean {\n    return typeof this.#opts.apiKey === \"string\" && this.#opts.apiKey.length > 0;\n  }\n\n  async initialize(): Promise<void> {\n    // Lazy: defer the actual client construction until first call.\n    // initialize() is idempotent — see EC-3 / EC-I.\n  }\n\n  async write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId> {\n    const text = this.#renderContent(content);\n    if (text.length === 0) {\n      throw new MemoryAdapterError(\"write: empty content\", {\n        adapterId: ADAPTER_ID,\n        code: \"invalid_input\",\n      });\n    }\n    const containerTags = buildContainerTags(ctx, this.#prefix());\n    try {\n      const resp = await this.#sdk().documents.add({\n        content: text,\n        containerTags,\n        ...(ctx.metadata !== undefined ? { metadata: ctx.metadata as Record<string, string> } : {}),\n      });\n      return mkMemoryId(ADAPTER_ID, resp.id);\n    } catch (err) {\n      throw this.#translateError(err, \"write\");\n    }\n  }\n\n  async recall(query: string, ctx: MemoryContext, k = 10): Promise<MemoryFact[]> {\n    if (k <= 0) return [];\n    const containerTag = primaryContainerTag(ctx, this.#prefix());\n    try {\n      const resp = await this.#sdk().search.memories({\n        q: query,\n        containerTag,\n        limit: k,\n        rerank: true,\n      });\n      const results = resp.results ?? [];\n      return results.map(this.#mapResult);\n    } catch (err) {\n      throw this.#translateError(err, \"recall\");\n    }\n  }\n\n  async delete(id: MemoryId): Promise<void> {\n    const rawId = extractRawId(id, ADAPTER_ID);\n    try {\n      await this.#sdk().documents.delete(rawId);\n    } catch (err) {\n      throw this.#translateError(err, \"delete\");\n    }\n  }\n\n  getToolSchemas(): MemoryToolSchema[] {\n    return [\n      {\n        name: \"memory_write\",\n        description:\n          \"Persist a fact about the user or context to Supermemory long-term memory. \" +\n          \"Returns the stored memory ID.\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            content: { type: \"string\", description: \"Fact text to persist verbatim.\" },\n          },\n          required: [\"content\"],\n        },\n      },\n      {\n        name: \"memory_recall\",\n        description:\n          \"Retrieve up to k semantically relevant facts from Supermemory long-term memory. \" +\n          \"Returns an array of {id, content, score, createdAt} objects.\",\n        parameters: {\n          type: \"object\",\n          properties: {\n            query: { type: \"string\", description: \"Free-text query to search memory.\" },\n            k: {\n              type: \"integer\",\n              minimum: 1,\n              maximum: 50,\n              description: \"Max results (default 10).\",\n            },\n          },\n          required: [\"query\"],\n        },\n      },\n    ];\n  }\n\n  async handleToolCall(\n    name: string,\n    args: Record<string, unknown>,\n    ctx: MemoryContext,\n  ): Promise<string> {\n    if (name === \"memory_write\") {\n      const content = String(args.content ?? \"\");\n      const id = await this.write(content, ctx);\n      return JSON.stringify({ ok: true, id });\n    }\n    if (name === \"memory_recall\") {\n      const query = String(args.query ?? \"\");\n      const k = typeof args.k === \"number\" ? args.k : 10;\n      const facts = await this.recall(query, ctx, k);\n      return JSON.stringify({ ok: true, facts });\n    }\n    throw new MemoryAdapterError(`Unknown tool name: ${name}`, {\n      adapterId: ADAPTER_ID,\n      code: \"invalid_input\",\n    });\n  }\n\n  async shutdown(): Promise<void> {\n    this.#client = undefined;\n  }\n\n  // ── helpers ────────────────────────────────────────────────────────\n\n  #prefix(): string {\n    return this.#opts.containerTagPrefix ?? \"theokit\";\n  }\n\n  #renderContent(content: string | MemoryTurnMessage[]): string {\n    if (typeof content === \"string\") return content.trim();\n    return content\n      .map((m) => `${m.role}: ${m.content}`)\n      .join(\"\\n\")\n      .trim();\n  }\n\n  #mapResult = (r: unknown): MemoryFact => {\n    const obj = (r as Record<string, unknown>) ?? {};\n    // SDK shape: { memory?: { id, content, ... }, score, ... } or chunk shape.\n    const memory = (obj.memory as Record<string, unknown> | undefined) ?? obj;\n    const rawId = String(memory.id ?? obj.id ?? \"\");\n    const content = String(memory.content ?? memory.text ?? obj.content ?? \"\");\n    const score = typeof obj.score === \"number\" ? obj.score : undefined;\n    const createdAt = typeof memory.createdAt === \"string\" ? memory.createdAt : undefined;\n    return {\n      id: mkMemoryId(ADAPTER_ID, rawId),\n      content,\n      ...(score !== undefined ? { score } : {}),\n      ...(createdAt !== undefined ? { createdAt } : {}),\n    };\n  };\n\n  #sdk(): Supermemory {\n    if (this.#client === undefined) {\n      this.#client = new SupermemoryClient({\n        apiKey: this.#opts.apiKey,\n        ...(this.#opts.baseUrl !== undefined ? { baseURL: this.#opts.baseUrl } : {}),\n      });\n    }\n    return this.#client;\n  }\n\n  #translateError(err: unknown, op: string): MemoryAdapterError {\n    if (err instanceof MemoryAdapterError) return err;\n    const status =\n      (err as { status?: number; statusCode?: number })?.status ??\n      (err as { statusCode?: number })?.statusCode;\n    const message = (err as Error)?.message ?? String(err);\n    if (status === 401 || status === 403) {\n      return new MemoryAdapterError(`Supermemory auth failed (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"auth_failed\",\n        cause: err,\n      });\n    }\n    if (status === 429) {\n      return new MemoryAdapterError(`Supermemory rate limited (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"rate_limited\",\n        cause: err,\n      });\n    }\n    if (status === 404) {\n      return new MemoryAdapterError(`Supermemory not found (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"not_found\",\n        cause: err,\n      });\n    }\n    if (status === undefined && message.toLowerCase().includes(\"network\")) {\n      return new MemoryAdapterError(`Supermemory network error (${op}): ${message}`, {\n        adapterId: ADAPTER_ID,\n        code: \"network\",\n        cause: err,\n      });\n    }\n    return new MemoryAdapterError(`Supermemory error (${op}): ${message}`, {\n      adapterId: ADAPTER_ID,\n      code: \"unknown\",\n      cause: err,\n    });\n  }\n}\n","/**\n * `@theokit/memory-supermemory` — Supermemory memory adapter for @theokit/sdk.\n *\n * Usage:\n *\n * ```ts\n * import { Agent } from \"@theokit/sdk\";\n * import { supermemoryMemory } from \"@theokit/memory-supermemory\";\n *\n * const agent = await Agent.create({\n *   apiKey: process.env.OPENROUTER_API_KEY,\n *   model: { id: \"openai/gpt-4o-mini\" },\n *   local: {},\n *   plugins: [supermemoryMemory({ apiKey: process.env.SUPERMEMORY_API_KEY! })],\n *   memoryContext: { userId: \"demo\" },\n * });\n *\n * await agent.memory.write(\"User likes Brazilian jazz\", { userId: \"demo\" });\n * const facts = await agent.memory.recall(\"music preferences\", { userId: \"demo\" });\n * ```\n *\n * @public\n */\n\nimport type { Plugin } from \"@theokit/sdk\";\nimport { definePlugin } from \"@theokit/sdk\";\n\nimport { SupermemoryAdapter, type SupermemoryAdapterOptions } from \"./adapter.js\";\n\nexport type { SupermemoryAdapterOptions } from \"./adapter.js\";\n\n/**\n * Build a `Plugin { kind: \"memory\" }` ready to pass to\n * `Agent.create({ plugins: [...] })`.\n *\n * @public\n */\nexport function supermemoryMemory(options: SupermemoryAdapterOptions): Plugin {\n  return definePlugin({\n    name: \"@theokit/memory-supermemory\",\n    version: \"0.1.0\",\n    kind: \"memory\",\n    createProvider: () => new SupermemoryAdapter(options),\n  });\n}\n"]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@theokit/memory-supermemory",
+  "version": "0.1.0",
+  "description": "Supermemory memory adapter for @theokit/sdk — wraps supermemory@^4 with the MemoryAdapter contract (ADR D141).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@theokit/sdk": "workspace:^",
+    "supermemory": "^4.21.0"
+  },
+  "devDependencies": {
+    "@theokit/sdk": "workspace:*",
+    "supermemory": "^4.21.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}