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

Type	Purpose	Example
`pattern`	Recurring code or workflow patterns	"User prefers early returns over nested ifs"
`convention`	Project-specific conventions	"API responses use camelCase"
`insight`	Discovered knowledge	"The auth module uses JWT with RS256"
`decision`	Recorded 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):

Splits query into whitespace-separated tokens
Filters memories where all tokens appear in the content
Sorts by token match count, then by usage count
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

Method	Description
`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"

Agents — agent fundamentals
Project Memory — project-level memory
Rules Engine — hierarchical rules
Contextual Awareness — proactive notifications