Agent Memory Patterns

Agents in Rekall have their own identity (called a "husk") and their own memory space. This guide covers creating agent identities, managing agent-specific memory, coordinating between multiple agents, and isolating memory between them.

Overview

In Rekall, agents are first-class citizens. Each agent has:

  • •Identity (Husk) -- A persistent identity with a name, capabilities, and personality traits
  • •Private memory space -- Agent-scoped memories that other agents cannot access
  • •Shared context -- Ability to read from personal and hive memory with appropriate permissions
  • •Lineage tracking -- Parent-child relationships when agents spawn sub-agents

Agent Identity (Husks)

A husk is the persistent identity container for an agent. It defines who the agent is, what it can do, and how it behaves. Husks persist across sessions -- when the same agent reconnects, it picks up where it left off.

Creating a Husk

Create an agent husk
import Rekall from '@rekall/agent-sdk';


const rekall = new Rekall({ apiKey: 'rk_your_key' });


// Create an agent identity
const codeReviewer = await rekall.agents.createHusk({
  name: 'CodeReviewer',
  description: 'Automated code review agent specialized in TypeScript best practices',
  capabilities: [
    'code-review',
    'style-check',
    'security-audit',
    'performance-analysis',
  ],
  personality: {
    tone: 'professional',
    detail: 'thorough',
    style: 'constructive',
  },
  config: {
    maxConcurrentTasks: 5,
    defaultTimeout: 300000,
    memoryRetention: 'all',  // 'all' | 'important-only' | 'session-only'
  },
});


console.log(`Agent created: ${codeReviewer.id}`);   // agent_abc123
console.log(`Husk name: ${codeReviewer.husk.name}`); // CodeReviewer


// Initialize the agent's SDK instance
const agentRekall = new Rekall({
  apiKey: 'rk_your_key',
  agentId: codeReviewer.id,
});

Agent-Specific Memory

When an agent creates memories using its SDK instance, those memories are stored in the agent's context. They are private to the agent unless explicitly shared.

Agent creates its own memories
// Using the agent's SDK instance
const agentRekall = new Rekall({
  apiKey: 'rk_your_key',
  agentId: 'agent_abc123',
});


// Memory is automatically scoped to this agent
await agentRekall.memories.create({
  type: 'episodic',
  content: 'Reviewed PR #42 for payments-service. Found 3 issues: missing error handling in checkout flow, unused import, and potential SQL injection in search query.',
  metadata: {
    tags: ['code-review', 'pr-42', 'payments-service'],
    severity: 'high',
    issuesFound: 3,
  },
  importance: 0.85,
});


// Agent can also store learned patterns
await agentRekall.memories.create({
  type: 'semantic',
  content: 'payments-service codebase commonly has missing error handling in async database calls',
  metadata: {
    tags: ['pattern', 'payments-service', 'error-handling'],
    frequency: 'high',
  },
});

Reading Agent Memory

Search agent-specific memories
// Search within agent's own memory
const agentMemories = await agentRekall.memories.search({
  query: 'previous reviews of payments-service',
  limit: 10,
});


// The owner can also read agent memories
const ownerRekall = new Rekall({ apiKey: 'rk_your_key' });
const agentHistory = await ownerRekall.agents.getMemories({
  agentId: 'agent_abc123',
  query: 'code review findings',
  limit: 20,
});


// List all agents and their memory stats
const agents = await ownerRekall.agents.list();
for (const agent of agents.items) {
  console.log(`${agent.husk.name}: ${agent.stats.totalMemories} memories`);
}

Memory inheritance

Agents can be configured to read from their owner's personal memory and any shared hive memories. This gives agents context about the user's preferences and team knowledge without the agent needing its own copy.

Multi-Agent Coordination

When multiple agents work together, they need ways to share context and coordinate. Rekall provides two patterns: shared context and message passing via memory.

Shared Context

Create a shared memory space (constellation) that multiple agents can read from and write to.

Multi-agent shared context
// Create a constellation (shared agent context)
const constellation = await rekall.agents.createConstellation({
  name: 'PR Review Pipeline',
  description: 'Shared context for the multi-agent PR review process',
  agents: [
    { agentId: 'agent_reviewer', role: 'code-reviewer' },
    { agentId: 'agent_security', role: 'security-scanner' },
    { agentId: 'agent_perf', role: 'performance-analyzer' },
  ],
});


// Each agent writes to the shared context
// (from the code reviewer agent)
await agentRekall.memories.create({
  type: 'episodic',
  content: 'Code review complete. Found 2 style issues and 1 logic bug.',
  context: {
    constellationId: constellation.id,
  },
  metadata: {
    agent: 'code-reviewer',
    status: 'complete',
    findings: 3,
  },
});


// The orchestrator can read all agent findings
const allFindings = await rekall.memories.search({
  query: 'review findings',
  context: { constellationId: constellation.id },
  limit: 50,
});

Message Passing via Memory

Agents can communicate asynchronously by writing tagged memories that other agents poll for.

Agent-to-agent communication
// Security agent finds an issue and flags it for the reviewer
await securityAgent.memories.create({
  type: 'episodic',
  content: 'CRITICAL: SQL injection vulnerability in search endpoint. User input is concatenated directly into query string.',
  context: { constellationId: constellation.id },
  metadata: {
    messageType: 'finding',
    severity: 'critical',
    targetAgent: 'code-reviewer',
    file: 'src/routes/search.ts',
    line: 42,
  },
  importance: 1.0,
});


// Code reviewer polls for high-severity findings
const criticalFindings = await reviewerAgent.memories.search({
  query: 'critical security findings',
  context: { constellationId: constellation.id },
  filters: {
    metadata: {
      messageType: 'finding',
      severity: 'critical',
    },
    minImportance: 0.9,
  },
});

Agent Spawning

Agents can spawn child agents for sub-tasks. Child agents inherit configuration from their parent and maintain a lineage chain.

Spawn child agents
// Parent agent spawns a child for a specific task
const childAgent = await agentRekall.agents.spawn({
  name: 'FileAnalyzer-PR42',
  description: 'Analyzes individual files in PR #42',
  inheritConfig: true,      // Inherit parent's config
  inheritMemory: false,     // Start with clean memory
  capabilities: ['file-analysis'],
  task: {
    description: 'Analyze src/routes/search.ts for security issues',
    timeout: 60000,
  },
});


console.log(`Child agent: ${childAgent.id}`);
console.log(`Parent: ${childAgent.parentId}`); // Points to parent


// Child can access parent's constellation
const childRekall = new Rekall({
  apiKey: 'rk_your_key',
  agentId: childAgent.id,
});


// When child completes, results flow back to parent
await childRekall.memories.create({
  type: 'episodic',
  content: 'File analysis complete for src/routes/search.ts',
  context: { constellationId: constellation.id },
  metadata: {
    parentTask: 'pr-review',
    status: 'complete',
  },
});


// Parent can check lineage
const lineage = await agentRekall.agents.getLineage({
  agentId: codeReviewer.id,
  includeChildren: true,
});


for (const child of lineage.children) {
  console.log(`  Child: ${child.husk.name} (status: ${child.status})`);
}

Memory Isolation Between Agents

By default, each agent's memory is private. Other agents (including parents and children) cannot read it unless explicitly configured.

Isolation Patterns

Memory isolation configuration
// Full isolation (default) - agent can only see its own memory
const isolatedAgent = await rekall.agents.createHusk({
  name: 'IsolatedWorker',
  config: {
    memoryAccess: {
      personal: false,    // Cannot read owner's personal memory
      hive: false,        // Cannot read hive memories
      otherAgents: false, // Cannot read other agents' memories
    },
  },
});


// Read-only access to owner's memory
const contextualAgent = await rekall.agents.createHusk({
  name: 'ContextualAssistant',
  config: {
    memoryAccess: {
      personal: 'read',    // Can read owner's personal memory
      hive: 'read',        // Can read hive memories
      otherAgents: false,  // Cannot read other agents
    },
  },
});


// Full access to shared contexts
const collaborativeAgent = await rekall.agents.createHusk({
  name: 'TeamAgent',
  config: {
    memoryAccess: {
      personal: 'read',
      hive: 'read-write',   // Can contribute to hive
      otherAgents: false,    // Still isolated from other agents
      constellations: 'read-write', // Can use shared agent contexts
    },
  },
});

Security consideration

Be cautious when granting agents write access to personal or hive memory. A misbehaving agent could pollute shared knowledge. Use read access unless the agent specifically needs to contribute to shared memory.

Next Steps

Rekall
rekall