@theokit/memory-mem0

Mem0 cloud memory adapter for @theokit/sdk.

Wraps mem0ai MemoryClient with the MemoryAdapter contract from ADR D141. Cloud-only path per ADR D148 (the OSS local mode duplicates work already shipped in @theokit/sdk Memory).

Unique among @theokit/memory-* adapters: Mem0 supports history(id) — version tracking per memory as facts evolve.

Install

pnpm add @theokit/memory-mem0 mem0ai

Usage

import { Agent } from "@theokit/sdk";
import { mem0Memory } from "@theokit/memory-mem0";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  local: {},
  plugins: [mem0Memory({ apiKey: process.env.MEM0_API_KEY! })],
  memoryContext: { userId: "alice" },
});

// Persist + recall (server-side fact extraction)
const id = await agent.memory.write("User likes Brazilian jazz");
const facts = await agent.memory.recall("music?");

// Version history — Mem0-unique capability
const revisions = await agent.memory.adapter()?.history(id);

Security Disclosure (CVE-2026-XXXX / CVSS 8.1)

On 2026-04-17, a high-severity injection vulnerability (CVSS 8.1) was disclosed in Mem0 OSS backends — PGVector, MySQL, and Neptune — allowing SQL or Cypher injection via crafted memory text/metadata. The Mem0 managed cloud (the only path this adapter uses) is reported unaffected by the disclosure.

Recommendations:

• If you use this adapter's default configuration (cloud), you are NOT exposed to CVE-2026-XXXX.
• If you self-host Mem0 OSS, upgrade to mem0ai >= 3.0.5 and avoid the PGVector / MySQL / Neptune backends until patched.
• Sanitize untrusted user input before passing it to agent.memory.write regardless — defense in depth.

This adapter (D148) explicitly does NOT support the OSS local mode to avoid this surface entirely. For local persistence, use @theokit/sdk's built-in Memory + Active Memory subsystems.

Options

| Field | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Mem0 API key. Required. | | host | string | Mem0 cloud | Override host. | | organizationId | string | — | Multi-tenant org scope. | | projectId | string | — | Project scope. | | breaker.threshold | number | 5 | Consecutive 5xx failures to trip. | | breaker.cooldownMs | number | 120_000 | Cooldown duration. |

Circuit breaker (EC-K)

A per-instance circuit breaker trips after 5 consecutive 5xx failures and pauses calls for 2 minutes. 429 (rate limit) does NOT count toward the trip threshold — rate limits are caller-pace signals, not provider-down signals.

Per-adapter-instance (EC-R): two Agent.create({...}) calls with distinct mem0Memory({...}) instances have independent breakers. For shared protection across many agents, pass the SAME plugin instance:

const sharedPlugin = mem0Memory({ apiKey });
const a = await Agent.create({ plugins: [sharedPlugin] });
const b = await Agent.create({ plugins: [sharedPlugin] });

Failure modes

| HTTP status | Maps to | Trips breaker? | |---|---|---| | 401 / 403 | auth_failed | no | | 429 | rate_limited | no (EC-K) | | 404 | not_found | no | | 5xx | network | yes | | Network/timeout | network | yes |

License

Apache-2.0. See LICENSE.