Agent Memory

Agent Memory gives each agent its own persistent memory stored in Cortex. Agents can remember patterns, conventions, insights, and decisions across sessions.

Memory types

TypePurposeExample
patternRecurring code or workflow patterns"User prefers early returns over nested ifs"
conventionProject-specific conventions"API responses use camelCase"
insightDiscovered knowledge"The auth module uses JWT with RS256"
decisionRecorded decisions with context"Chose PostgreSQL over SQLite for concurrency"

How it works

Agents with memory: true in their markdown definition can store and recall memories:

markdown
---
name: reviewer
memory: true
---

# Code Reviewer

Reviews code for quality and security issues.

Storing memories

Memories are created automatically via the agent_end hook or manually through agent tools:

typescript
{
  id: string;
  agentName: string;
  content: string;           // The memory text
  type: AgentMemoryType;     // pattern | convention | insight | decision
  project: string;           // Project scope (default: "global")
  confidence: number;        // 0.0–1.0 (default: 0.7)
  createdAt: string;
  lastUsedAt: string;
  usageCount: number;
}

Recalling memories

The recall() method uses token-based matching (AND logic — all query terms must match):

  1. Splits query into whitespace-separated tokens
  2. Filters memories where all tokens appear in the content
  3. Sorts by token match count, then by usage count
  4. Returns top N results (default: 10)

Recalled memories are injected into the prompt as:

xml
<agent-memory>
- [pattern] User prefers early returns over nested ifs
- [convention] API responses use camelCase
</agent-memory>

Operations

MethodDescription
store(agentName, entry)Create a memory
recall(agentName, opts?)Query memories with filtering
touch(agentName, memoryId)Update lastUsedAt + increment usageCount
forget(agentName, memoryId)Delete a memory
stats(agentName)Count by type
prune(agentName, opts?)Delete low-confidence or stale entries (default: < 0.3)

Cortex storage

{ns}:agent:{name}:memory:{id} → {ns}:agentmem:content → "User prefers early returns"
{ns}:agent:{name}:memory:{id} → {ns}:agentmem:type → "pattern"
{ns}:agent:{name}:memory:{id} → {ns}:agentmem:project → "global"
{ns}:agent:{name}:memory:{id} → {ns}:agentmem:confidence → "0.7"
{ns}:agent:{name}:memory:{id} → {ns}:agentmem:usageCount → "5"