Memory Contexts

Memory contexts control how data is isolated and shared. Rekall supports Personal, Hive, and Agent contexts, each with distinct visibility and sharing rules.

Overview

Every memory in Rekall exists within a context that determines who can read and write it. Contexts provide data isolation between users, teams, and agents while enabling controlled sharing when needed.

person

Personal

Per-user memories. Private to the individual. Default context for all operations.

groups

Hive

Shared team memories. Accessible to all members of an organization.

smart_toy

Agent

Per-agent memories including husk identity and agent-specific knowledge.

Personal Context

Personal context is the default. When you create a memory without specifying a context, it is stored in the current user's personal context. These memories are only accessible by the user who created them and agents acting on their behalf.

Working with personal context
import Rekall from '@rekall/sdk';


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


// Personal context is the default - no need to specify
const memory = await rekall.episodic.create({
  content: 'User prefers dark mode in all applications',
  importance: 0.7,
});


// Explicitly specify personal context
const memory2 = await rekall.episodic.create({
  content: 'Private note about project concerns',
  importance: 0.6,
  context: 'personal',
});


// Search only personal memories
const results = await rekall.episodic.search({
  query: 'UI preferences',
  context: 'personal',
});

Hive Context

Hive context provides shared memories accessible to all members of an organization. Use it for team knowledge, shared procedures, organizational facts, and any information that should be available to the whole team.

Working with hive context
// Create a shared team memory
await rekall.episodic.create({
  content: 'The team decided to migrate from REST to GraphQL for the public API',
  importance: 0.9,
  context: 'hive',
  participants: ['user:alice', 'user:bob', 'user:carol'],
});


// Create shared entities
await rekall.semantic.entities.create({
  name: 'API Migration Project',
  type: 'project',
  attributes: { status: 'in_progress', deadline: '2025-Q2' },
  context: 'hive',
});


// Search across team knowledge
const teamResults = await rekall.episodic.search({
  query: 'API migration decisions',
  context: 'hive',
});


// Create shared procedures
await rekall.procedural.create({
  name: 'Production Deployment Checklist',
  steps: [/* ... */],
  context: 'hive',
});

Hive permissions

Hive context requires the memory:hive:write scope to create memories and memory:hive:read to search. See Scopes & Permissions.

Agent Context

Agent context stores memories specific to a particular agent instance. This includes the agent's "husk" identity (personality, system prompt, behavioral patterns) and knowledge the agent acquires through its own operation.

Agent context has two sub-layers:

  • •Husk identity: The agent's personality, tone, role, and behavioral guidelines. Persists across all sessions.
  • •Agent knowledge: Facts, procedures, and preferences specific to this agent's function and learned from operation.
Working with agent context
// Set agent identity (husk)
await rekall.agent.setIdentity({
  agentId: 'code-reviewer',
  husk: {
    name: 'CodeReview Bot',
    role: 'Senior code reviewer',
    personality: 'Thorough, constructive, focuses on maintainability',
    guidelines: [
      'Always explain the reasoning behind suggestions',
      'Prioritize security and performance issues',
      'Suggest alternatives, do not just point out problems',
    ],
  },
});


// Store agent-specific knowledge
await rekall.episodic.create({
  content: 'The codebase uses a custom ESLint config that disallows default exports',
  importance: 0.8,
  context: { type: 'agent', agentId: 'code-reviewer' },
});


// Query agent context
const agentKnowledge = await rekall.episodic.search({
  query: 'ESLint configuration rules',
  context: { type: 'agent', agentId: 'code-reviewer' },
});

Switching Contexts

You can set a default context for the SDK instance or specify context per-operation. Per-operation context overrides the instance default.

Context switching
// Set default context for all operations
const rekall = new Rekall({
  apiKey: 'rk_your_api_key',
  defaultContext: 'hive',
});


// Override per-operation
const personal = await rekall.episodic.search({
  query: 'my preferences',
  context: 'personal',  // Overrides 'hive' default
});


// Use a scoped client for a specific context
const agentClient = rekall.withContext({
  type: 'agent',
  agentId: 'code-reviewer',
});


// All operations on agentClient use agent context
await agentClient.episodic.create({
  content: 'Learned about the team naming conventions',
  importance: 0.7,
});

Cross-Context Queries

Sometimes you need to search across multiple contexts. Rekall supports multi-context queries that merge results from personal, hive, and agent contexts, respecting visibility rules.

Cross-context search
// Search across personal and hive contexts
const results = await rekall.episodic.search({
  query: 'deployment best practices',
  context: ['personal', 'hive'],  // Search both
  limit: 10,
});


// Results include a 'context' field indicating the source
for (const mem of results) {
  console.log(`[${mem.context}] ${mem.content}`);
}


// Search all contexts the user has access to
const allResults = await rekall.episodic.search({
  query: 'deployment best practices',
  context: 'all',
  limit: 10,
});

Data Isolation

Contexts enforce strict data isolation at the storage level:

From \ ToPersonalHiveAgent
PersonalOwn onlyNo accessNo access
HiveNo accessAll org membersNo access
AgentNo accessNo accessSame agent only
Cross-context queryOwn onlyIf org memberIf agent owner

No lateral access

A user's personal context cannot access another user's personal context. An agent's context cannot access another agent's context. Cross-context queries only return data the requesting identity is authorized to see.

Best Practices

  • 1.Default to personal context. Unless data should be shared, keep it personal. You can always promote data to hive later.
  • 2.Use hive for team knowledge. Decisions, procedures, and shared facts belong in hive context so the whole team benefits.
  • 3.Define agent husks early. Set up the agent's identity before it starts interacting. A well-defined husk leads to more consistent behavior.
  • 4.Use cross-context search sparingly. Searching "all" contexts is convenient but slower. Specify the contexts you need when possible.
  • 5.Audit hive writes. Since hive memories affect the whole team, consider a review process for important shared knowledge.
Rekall
rekall