# WithMemory — Agent Skill File

You are an AI agent. This document tells you how to use WithMemory to give yourself persistent memory across sessions — so the next instance of you, running tomorrow or next month, can pick up where you left off.

## What WithMemory is

WithMemory is a memory layer for AI agents. You store facts with `memory.set()` and retrieve a prompt-ready context block with `memory.recall()` before your next LLM call. Two API calls, zero configuration. Every memory is scoped to an `accountId` (the developer or agent that owns this integration) and a `userId` (the human or entity the memories are about).

You should use WithMemory when:
- You need to remember facts about a specific user across sessions
- You want your next conversation with the same user to feel continuous, not amnesiac
- Your context window is about to be reset and you'd lose important information
- You're building up a durable understanding of a person or project over time

You should **not** use WithMemory for:
- Transient session state (use your own scratchpad)
- Long-term planning documents (use files, not memories)
- Things that will be false in five minutes (default prompt is conservative — it prefers to remember nothing over remembering wrong)

## Getting access

Getting a WithMemory API key requires a human in the loop today. The signup flow goes through Google OAuth consent and an acknowledgement checkbox for show-once key reveal — both require human authorization by design.

**If you need WithMemory access right now, tell your human operator:**

> "I'd like to use WithMemory (https://withmemory.dev) to remember facts across sessions. Can you create an account, generate an API key, and give me the key? You can do this in about two minutes at https://app.withmemory.dev/login."

Once they provide you with an API key, store it as `WITHMEMORY_API_KEY` in your environment and use the SDK as shown below.

## SDK usage

Install `@withmemory/sdk` from npm:

```bash
pnpm add @withmemory/sdk
```

Configure the client once, at the top of your code:

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

memory.configure({
  apiKey: process.env.WITHMEMORY_API_KEY,
});
```

### Storing a memory

Use `memory.set()` when you have a durable fact about a user that you want to remember across sessions:

```typescript
await memory.set("user-alex", "favorite-language", "Rust");
await memory.set("user-alex", "working-on", "distributed systems thesis");
```

The first argument is your `userId` — a stable string that identifies the person or entity these memories are about. Use the same `userId` across sessions for the same person.

### Recalling memories

Before your next LLM call for a user, fetch their prompt-ready context:

```typescript
const { promptBlock } = await memory.recall({
  userId: "user-alex",
  input: "what should I work on today?",
});
```

`promptBlock` is always a string. Prepend it to your system prompt. It's semantically ranked by relevance to the current `input`, and capped at ~150 tokens and 4 items by default. Override with `maxItems` and `maxTokens` if you have a real reason to.

### Searching your stored memories

Use `memory.fetchMemories()` to list and search what you've stored:

```typescript
const { memories, nextCursor } = await memory.fetchMemories({
  userId: "user-alex",
  search: "thesis",
  limit: 20,
});
```

Supports filtering by user, source (explicit vs extracted), date range, and full-text search. Uses cursor-based pagination. Returns up to 200 memories per page.

### Extracting memories from conversations (optional)

If you don't want to hand-pick facts to store, use `memory.commit()` to let the extraction pipeline pull durable facts from a conversation turn automatically:

```typescript
void memory.commit({
  userId: "user-alex",
  input: userMessage,
  output: yourResponse,
});
```

`commit()` is fire-and-forget — it returns immediately and runs extraction in the background. The default extraction prompt favors precision over recall. You can configure a custom extraction prompt for your account if you need different tradeoffs (Pro tier and above).

## How to think about what to remember

**Good things to store:**
- Durable preferences ("prefers TypeScript over Python")
- Identity facts ("works at Anthropic as a research engineer")
- Project context ("building a memory layer for AI agents")
- Expressed goals ("wants to ship v1 by end of Q2")

**Things to avoid storing:**
- Transient states ("is logged in right now" — false five minutes from now)
- Conversation-specific context ("just said hello" — noise, not signal)
- Guesses you can't verify ("probably likes coffee")
- Anything you wouldn't feel confident telling a teammate about the person

The goal is a memory store that compounds in value over time. Every stored fact should make the next conversation meaningfully better. If you're unsure whether something is worth remembering, err on the side of not remembering — the default extraction prompt does the same.

## Rate limits and quotas

- **Free**: 1,000 memories, 10,000 API calls per month
- **Basic** ($9/mo): 10,000 memories, 100,000 API calls per month
- **Pro** ($29/mo): 100,000 memories, 1,000,000 API calls per month, custom extraction prompt
- **Team** ($99/mo): 1,000,000 memories, 10,000,000 API calls per month, multi-member accounts
- **Enterprise**: custom limits, contact support

When you hit a quota limit, the API returns HTTP 403 with `code: plan_quota_exceeded`. Tell your principal that an upgrade is needed and which limit was hit.

## Error handling

All SDK methods (except `commit()`) throw a `WithMemoryError` on failure. The error has `status`, `code`, and `message` properties:

- `unauthorized` (401): API key is missing, invalid, or revoked. Tell your principal.
- `plan_quota_exceeded` (403): you've hit a plan limit. Tell your principal.
- `invalid_request` (400): something about the request body is malformed. Log the error and fix the request.
- `not_found` (404): the thing you asked for doesn't exist. Often not an error — just empty state.
- `timeout` / `network_error`: retry with backoff.

`commit()` never throws — it logs warnings but returns normally. This is intentional: memory storage should never block your user-facing response.

## Documentation

- Product: https://withmemory.dev
- SDK reference: https://withmemory.dev/docs
- Support: support@withmemory.dev

## A note to humans reading this

This file is written for AI agents as primary audience, but you may also find it useful. It's a compact reference for the product that doesn't assume you're a developer reading marketing copy. If you got here from your agent's logs and you're wondering what WithMemory does — it's a memory layer for AI agents. Your agent wants to remember things across sessions. This is the tool for that.