Core Concepts

The Seven Memory Types

Rekall's memory architecture is inspired by cognitive science. Each memory type serves a distinct purpose and is optimized for different storage, retrieval, and lifecycle patterns. You can use any combination of types in a single agent.

Memory Contexts

Every memory in Rekall belongs to one of three contexts, which determines its visibility and sharing scope. Contexts control who can read and write a memory.

// Personal memory: only visible to this user
await rekall.memories.create({
  type: 'episodic',
  content: 'User prefers dark mode and compact layouts.',
  context: 'personal', // default
});

// Hive memory: shared with all team members
await rekall.memories.create({
  type: 'semantic',
  content: 'The production database is hosted on AWS us-east-1.',
  context: 'hive',
  metadata: {
    hiveId: 'hive_engineering_team',
  },
});

// Agent memory: private to this specific agent
await rekall.memories.create({
  type: 'procedural',
  content: 'When user asks about billing, first check their plan status, then check for outstanding invoices, then provide options.',
  context: 'agent',
  metadata: {
    agentId: 'agent_support_01',
  },
});

How Agents Interact with Memory

Agents interact with Rekall memory through a straightforward cycle that runs on every turn of a conversation or task:

Decay & Consolidation

Rekall implements a biologically-inspired memory lifecycle where memories naturally weaken over time unless reinforced, and short-lived memories are periodically consolidated into durable long-term knowledge. This prevents memory bloat and ensures that the most relevant information rises to the top.

Strength Decay

Every memory has a strength value between 0.0 and 1.0. New memories start at 1.0 and decay according to a modified Ebbinghaus forgetting curve. The decay rate depends on the memory type:

Memory Consolidation

Rekall's consolidation engine runs periodically (configurable, default every 6 hours) and performs the following:

• Pattern detection: Identifies recurring themes across episodic memories and creates consolidated long-term memories
• Preference extraction: Analyzes interaction patterns to infer user preferences with confidence scores
• Knowledge graph enrichment: Extracts entities and relationships from episodic memories and adds them to the semantic knowledge graph
• Garbage collection: Removes memories whose strength has decayed below a configurable threshold (default 0.05)

// Multiple episodic memories about deployment issues:
// - "Deployment failed due to DNS timeout" (3 days ago)
// - "Deployment failed again, DNS resolution slow" (2 days ago)
// - "Fixed deployment by increasing DNS timeout to 30s" (1 day ago)

// After consolidation, Rekall creates:
// Long-term memory: "Deployments are susceptible to DNS timeout failures.
//   Resolution: increase DNS timeout to 30 seconds."
// Procedural memory: "When deployment fails, check DNS resolution first,
//   then increase timeout if needed."
// Semantic memory: Entity "deployment-process" -> "requires" -> "DNS timeout >= 30s"

Retrieval Strengthening

Every time a memory is retrieved (via get, search, or automatic recall), its strength is boosted. This implements the testing effect from cognitive science: memories that are actively used become stronger and more durable.

The strengthening amount depends on how much time has passed since the last retrieval. Retrieving a memory immediately after the last access provides a smaller boost than retrieving it after a longer interval. This implements spaced repetition -- memories benefit more from distributed practice than from massed practice.

// Memory created at strength 1.0
// Day 1: strength = 1.00
// Day 3: strength = 0.85 (natural decay)
// Day 3: retrieved -> strength = 0.95 (boosted)
// Day 7: strength = 0.82 (slower decay after reinforcement)
// Day 7: retrieved -> strength = 0.93 (boosted again)
// Day 14: strength = 0.84 (even slower decay)
// ...
// Unretrieved memories eventually reach 0.05 threshold and are garbage collected

Next Steps

Now that you understand the core concepts, dive deeper into individual memory types or start building.