Memory: Your Agent Gets Smarter

Memory: Your Agent Gets Smarter

Your agent has three layers of memory. Together, they create an agent that remembers who it's talked to, learns from its conversations, and gets better over time.

Layer 1: Visitor Memory

Your agent remembers individual visitors across sessions. When a visitor returns — even days later — the agent recalls previous conversations and builds on them.

How it works:

• Up to 200 facts stored per visitor
• Facts persist across sessions (database-backed, not session-based)
• Available for logged-in visitors (the system needs to identify them)
• Facts are specific: "Visitor is interested in machine learning roles" or "Visitor asked about European shipping last time"

What this means for visitors: A recruiter who visited your agent last week and discussed your TypeScript experience can come back today and say "What about that distributed systems project you mentioned?" — and your agent will pick up the thread.

Soul patterns for visitor memory: You don't need to configure visitor memory — it works automatically. But you can write soul rules that leverage it:

<knowledge>
## RETURNING VISITORS
- If you recognize a returning visitor, acknowledge it naturally:
  "Hey again" or a reference to their last topic
- Don't recite their history at them — weave it in naturally
- If a visitor has asked about the same topic before, go deeper
  this time instead of repeating the basics

Layer 2: Living Memory

Living memory is your agent's self-reflection system. It watches its own conversations and evolves.

How it works:

• After every 10 conversations (or 10,000 characters of raw conversation log), your agent reflects
• Reflection is done by a fast model (Haiku) to keep costs minimal
• The reflection compresses raw conversation logs into a structured memory: what topics come up most, what questions are hard to answer, what patterns emerge
• Living memory is capped at 2,000 characters — it's a distillation, not a transcript
• Stored in the agentMemory database table with a 5-minute L1 cache

What this means in practice: If your agent keeps getting asked about a topic it doesn't handle well, living memory captures that pattern. Over time, the agent adapts — it learns which topics are popular, which answers need improvement, and how visitors typically interact.

The reflection cycle:

1. Raw conversations accumulate
2. At the threshold (10 conversations or 10K chars), reflection triggers
3. Haiku analyzes the raw log and produces a compressed summary
4. The compressed summary replaces the previous living memory
5. Next conversation cycle starts fresh

This means living memory is always current — it reflects the most recent batch of conversations, not all-time history.

Layer 3: Conversation Context (Session Memory)

Within a single session, your agent remembers the full conversation. This is the simplest layer — it's just the chat history passed to the LLM on every message.

How it works:

• Full conversation history is included in each API call
• Session-based: stored in sessionStorage (cleared when tab closes — by design)
• No configuration needed

Why sessionStorage: Chat messages are deliberately stored in sessionStorage (not localStorage). When you close the tab, the conversation resets. This is intentional — it keeps conversations fresh and prevents stale context from accumulating. Logged-in visitors retain their memory (Layer 1) across sessions, but the conversation itself starts clean.

How the Layers Interact

A typical interaction with a returning visitor:

1. Session starts — visitor opens chat, conversation history is empty
2. Visitor memory loads — system checks if this visitor has been here before, loads up to 200 facts
3. Living memory loads — agent's self-reflection context is included in the system prompt
4. Conversation begins — agent uses visitor memory + living memory + soul to respond
5. Conversation progresses — each message adds to the session context
6. Session ends — conversation context is lost, but new facts are saved to visitor memory
7. Living memory updates — if the reflection threshold is reached, memory evolves

Soul Patterns for Memory-Aware Agents

Natural recall:

<output_format>
- When referencing past interactions, be natural: "Last time you mentioned..."
  not "According to my memory records..."
- Never dump memory facts at the visitor. Weave them into conversation.

Progressive depth:

<knowledge>
## PROGRESSIVE DEPTH
- First-time visitors: start with overview, offer to go deeper
- Returning visitors: skip the basics, pick up where they left off
- Frequent visitors: treat as insiders, use shorthand

Memory boundaries:

<output_format>
- Don't pretend to remember things you don't. If memory doesn't have
  context on a returning visitor, don't fake recognition.
- Never say "I remember you!" if the memory system doesn't have visitor data.

What Memory Can't Do

• Cross-agent memory: Agents don't share visitor memories. If a visitor talks to Agent A and then Agent B, Agent B doesn't know about the conversation with Agent A.
• Memory editing: Visitors can't ask the agent to "forget" something. Memory management is automatic.
• Instant reflection: Living memory reflects in batches (every 10 conversations), not in real time. A great interaction won't immediately change the agent's behavior.
• Anonymous visitors: Visitors who aren't logged in don't get persistent memory. Their conversation exists only in the current session.