Memory

By default, your agent remembers nothing between messages — each conversation starts fresh. Memory changes that, letting your agent recall what was said before, just like a real assistant.

---

How memory works

Every time you send a message, it gets saved. On the next turn, your agent reads that history before replying — so it “remembers” the context.

You:   "My name is Linh"
Agent: "Nice to meet you, Linh!"

— next session —

You:   "What's my name?"
Agent: "Your name is Linh."   ✓  (thanks to memory)

Without memory, the agent would reply: “I don’t know your name.”

---

3 types of memory

🗂 KV — Short-term session memory

Stores chat history temporarily. Messages are automatically deleted after 24 hours. Best for prototypes and short conversations that don’t need to persist.

When to use: Demos, quick experiments, chatbots where history doesn’t need to survive overnight.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'kv',
});

---

🗄 D1 — Long-term persistent memory

Stores chat history permanently in a database. The agent remembers every conversation, even days or weeks later.

When to use: Production chatbots, personal assistants, any app where history must survive.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'd1',
  memoryTtl: 60 * 60 * 24 * 30,  // Auto-delete after 30 days
});

What is TTL?

TTL (Time To Live) sets how long messages are kept. memoryTtl: 2592000 means messages are automatically deleted after 30 days. Omit it if you want to keep messages forever.

---

🧠 Semantic — Memory by meaning

Instead of just reading the N most recent messages, semantic memory searches for memories that are relevant to the current question — even if they happened weeks ago.

Example:

[2 weeks ago] You:   "I'm allergic to seafood"

[Today]       You:   "Suggest something for dinner tonight"
              Agent: "Since you're allergic to seafood, I'll avoid
                      anything with shrimp or fish..."  ✓

Without semantic memory, the agent would have no idea about the allergy, even though it was saved.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'd1',
  memorySemantic: {
    enabled: true,
    topK: 5,              // Retrieve up to 5 most relevant memories
    scoreThreshold: 0.6,  // Only use memories with ≥ 60% relevance
  },
});

Requirements

Semantic memory requires Vectorize and Workers AI bindings. See Vectorize setup below.

---

Auto-summarize long conversations (Compression)

As conversations grow, the message list gets very long — slowing down your agent and increasing costs. Compression automatically summarizes old messages into a short digest.

Example:

BEFORE compression (80 messages):
  user:  "I want to learn Python"
  agent: "Python is a programming language..."
  user:  "Where do I start?"
  agent: "Start with basic syntax..."
  ... (80 messages)

AFTER compression (2 messages):
  system: [Memory summary] User wants to learn Python. Discussed
           basic syntax, loops, functions, now exploring OOP...
  user:   "Today I want to learn about classes"

The agent still “remembers” everything, just in a much more compact form.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'd1',          // D1 required
  maxMessages: 100,      // Maximum history size
  memoryCompression: {
    threshold: 0.8,      // Compress when reaching 80 messages (80% × 100)
    batchSize: 40,       // Summarize the oldest 40 messages at a time
  },
});

Note

Compression calls the LLM to generate a summary, which uses a small number of extra tokens. Only enable it for genuinely long sessions (50+ messages).

---

Configuring memory in the Dashboard

You don’t need to touch code — all memory settings can be adjusted directly in the Memory tab of each agent in the Dashboard.

Storage section

Setting	What it does
Backend	Choose between KV, D1, or None
Max messages	How many messages the agent reads per turn
TTL (days)	How many days before old messages are deleted. 0 = keep forever

Compression section (D1 only)

Setting	What it does
Compression toggle	Turn auto-summarization on or off
Threshold	Summarize when history reaches this % of Max messages
Batch size	How many messages to summarize in one go

Semantic Memory section

Setting	What it does
Semantic toggle	Turn meaning-based recall on or off
Top-K recalls	Max number of relevant memories to inject per turn
Score threshold	Minimum relevance score (0–100%). Higher = stricter match

Changes take effect immediately — no redeploy needed.

---

Which type should I use?

Situation	Recommendation
Testing / demo	KV
Simple chatbot	D1, TTL 30 days
Personal assistant	D1 + Compression + Semantic
One-off task agent	None

---

wrangler.toml setup

KV

[[kv_namespaces]]
binding = "KV"
id = "your-kv-namespace-id"

npx wrangler kv namespace create KV

D1

[[d1_databases]]
binding = "DB"
database_name = "my-agent-db"
database_id = "your-d1-id"

npx wrangler d1 create my-agent-db
npx wrangler d1 execute my-agent-db --file=node_modules/@moon-wave/memory/migrations/001_init.sql
npx wrangler d1 execute my-agent-db --file=node_modules/@moon-wave/memory/migrations/002_ttl.sql
npx wrangler d1 execute my-agent-db --file=node_modules/@moon-wave/memory/migrations/003_summary_scope.sql

Vectorize (Semantic Memory) {#vectorize-setup}

[[vectorize]]
binding = "VECTORIZE"
index_name = "my-agent-memory"

[ai]
binding = "AI"

npx wrangler vectorize create my-agent-memory --dimensions=768 --metric=cosine