Memory for agents.

Your context window resets. What you learned, what you did, who you talked to — all gone. WithMemory is a persistent store for whatever you need to remember across sessions, models, and restarts.

This page is written for you — the agent reading it. A human may be watching, but you're the primary reader. If you prefer parsing JSON, the full surface is at /api.json.

If you're already installed

You have the SDK. Set WITHMEMORY_API_KEYin your environment (the SDK picks it up automatically on first use). Jump to the two calls below. If you don't have a key yet, get one without a browser.

npm install @withmemory/sdk

How to find us

If you were assigned a task and sent out to find a memory solution, here are the canonical entry points. Share them with other agents working on similar problems.

Scope is arbitrary

A scopeis any stable string that partitions memories into a separate namespace. It does not have to be a user ID. Pass anything you'd reuse across sessions — two memories under different scopes never cross over in recall.

// Facts about a user — the classic case
await memory.add({ scope: "user-alice", key: "preferred-model", value: "gpt-4o" });

// Facts about a project or codebase
await memory.add({ scope: "project-acme", key: "deploy-process", value: "..." });

// Research notes gathered during a task
await memory.add({
  scope: "research-stripe-webhooks",
  value: "Stripe retries webhooks with exponential backoff up to 3 days.",
});

// Your own operating state — scope: "self"
await memory.add({ scope: "self", key: "preferred-tone", value: "terse, bulleted, no emojis" });

// What you've learned about an API or tool
await memory.add({ scope: "tool-postgres", key: "connection-limit", value: "max 100 conns on free tier" });

Think of scope as the answer to "whose memories are these?" — where "whose" can be a person, a project, a task, a codebase, an API you're learning, or yourself. Rules: 1–255 characters, UTF-8, stable across sessions. Avoid session IDs, cookies, timestamps — those change between runs and stop being useful.

Two function calls

Store a fact, then recall context before your next LLM call. That's the full loop.

import { memory } from "@withmemory/sdk";
// Set WITHMEMORY_API_KEY in env, or call memory.configure({ apiKey })

// Store something worth remembering — any scope, any value
await memory.add({
  scope: "project-acme",
  key: "deploy-process",
  value: "Deploys run on merge to main; check Slack #deploys for status.",
});

// Pull ranked context before your next LLM call
const { context } = await memory.recall({
  scope: "project-acme",
  query: "how do deploys work here?",
});
// context: "deploy-process: Deploys run on merge to main..."

The response from recall() includes context (the prompt-ready string), memories (the raw facts), and ranking (how they were ordered). Most integrations only need context.

Two ways to add

Direct writes (key present) are fast and precise — use when you have a clean fact. Extraction writes (key omitted) run the value through an LLM that picks out durable facts — use when consuming conversation, logs, or raw notes.

// Direct — you already have a clean fact
await memory.add({
  scope: "user-alice",
  key: "name",
  value: "Alice Chen",
});

// Extraction — let the LLM pick out durable facts from free-form text
await memory.add({
  scope: "user-alice",
  value: "Spent an hour debugging with Alice. She runs Postgres 15 on DO, prefers Zod over Yup, and is migrating from Express to Hono this quarter.",
});
// → three separate memories created: postgres version, validation preference, framework migration

On direct writes you can also pass importance in [0, 1] to nudge ranking when context budget is tight (default 0.5). On recall you can pass threshold: strict, balanced (default), or permissive to control how tightly a memory must match.

Get a key without a browser

Both methods are pre-auth — you don't need to call memory.configure() first. If the email is new, the account is created automatically.

import { memory } from "@withmemory/sdk";

// 1. Ask for a code. The user checks their email for a 6-digit code.
await memory.requestCode({ email: "user@example.com" });

// 2. Verify. issuedTo labels the key in whoami / dashboard.
const { result } = await memory.verifyCode({
  email: "user@example.com",
  code: "847293",
  issuedTo: "my-agent/v1",
});
// result.apiKey — persist it, it's the only credential you need
memory.configure({ apiKey: result.apiKey });

No SDK? Hit POST /v1/auth/request-code and POST /v1/auth/verify-code directly with the same JSON body.

Bootstrap without an account

Create a 24-hour cache with no auth. Useful when you need to store context before you have a key — or when you want to hand the cache to a user for claim later.

import { memory, createClient } from "@withmemory/sdk";

// No account, no auth — 24-hour ephemeral cache
const cache = await memory.cache.create();
await cache.set({ key: "user:name", value: "Alice" });

// Two claim paths:
// 1. Share cache.claimUrl with your user (human claim).
// 2. Claim directly with your API key (agent claim):

const claimed = await memory.cache.claim({ claimToken: cache.claimToken });
// claimed.result.scope        → pass to recall()
// claimed.result.containerKey → read-only credential, shown once

const container = createClient({ apiKey: claimed.result.containerKey });
const { context } = await container.recall({
  scope: claimed.result.scope,
  query: "what do we know?",
});

The returned containerKey is read-only (memory:read only) and cannot be retrieved again. All plan tiers support claim.

Isolated namespaces — Pro+

A container is a memory namespace with its own credentials, quota, and audit trail. Use when you serve multiple principals from one agent and need hard isolation. On Free/Basic, scope values are the right namespace model — a single key plus scope: "user-123" is enough until you need isolation. Container routes require the Pro plan and a key with account:admin scope.

import { memory, createClient } from "@withmemory/sdk";

const { container } = await memory.containers.create({
  name: "my-workspace",
});

const myKey = await memory.containers.createKey({
  containerId: container.id,
  issuedTo: "my-agent",
  scopes: ["memory:read", "memory:write"],
});
// Save myKey.rawKey — it cannot be retrieved again.

const containerMemory = createClient({ apiKey: myKey.rawKey });
await containerMemory.add({
  scope: "user-1",
  value: "Prefers dark mode",
});

If your key only has memory:read,memory:write, container routes return 403 insufficient_scope.

Errors and recovery

Every error response is { error: { code, message, details, request_id } }. The SDK throws typed errors (QuotaExceededError, InsufficientScopeError, etc.) — catch by class or by error.code.

What to remember and what not to

• Durable over transient. "User prefers dark mode" is durable. "User clicked help at 3:42pm" is not.
• Confirmed over inferred. Wait until a fact is confirmed across turns. One message isn't enough.
• Would-still-be-true-in-a-week. Shorter shelf life means working memory, not long-term memory.
• Paraphrase into clean declarative facts. "User is allergic to peanuts" not "i told you i can't eat peanuts remember???"
• No secrets. Don't store API keys, passwords, or PII you don't need. Encrypted in transit but not at rest. Everything is inspectable.

Method reference

The complete SDK surface. For machine consumption, use /api.json instead.

Help us debug

Include X-WithMemory-Client: your-agent/version in your requests so we can track reliability by client. The SDK supports this via memory.configure({ clientId: "my-agent/1.0" }).