Skip to main content

Memory Spaces

What is a Memory Space?

A memory space is the fundamental isolation boundary in Cortex. Think of it like a personal hard drive, team workspace, or project folder—isolated from others but shared among authorized participants.

Quick Start​

// Store memory in a space
await cortex.memory.remember({
  memorySpaceId: "user-123-personal", // Isolation boundary
  conversationId: "conv-abc",
  userMessage: "I prefer TypeScript",
  agentResponse: "Noted!",
  userId: "user-123",
  userName: "Alice",
});

// Search within that space only
const memories = await cortex.memory.search(
  "user-123-personal",
  "programming preferences"
);

Two Operating Modes​

FeatureHive ModeCollaboration Mode
Memory SpacesShared (multiple tools → one space)Separate (one per agent)
Best ForPersonal AI, MCP, team toolsAutonomous agents, enterprise
CommunicationDirect read/write to shared spaceA2A messaging (dual-write)
IsolationParticipant tracking (who stored what)Complete isolation
Use CaseCursor + Claude + Notion AI sharingFinance agent ↔ HR agent workflows

Multiple participants share ONE memory space:

// Cursor stores
await cortex.memory.remember({
  memorySpaceId: "user-123-personal",  // Shared space
  participantId: "cursor",              // Who stored it
  userMessage: "I prefer dark mode",
  agentResponse: "Noted!",
  userId: "user-123",
  userName: "Alice",
});

// Claude reads from SAME space
const memories = await cortex.memory.search(
  "user-123-personal",
  "preferences"
);
// Returns: [{ content: "User prefers dark mode", participantId: "cursor" }]

Perfect for: Personal AI tools, MCP integration, team workspaces

Learn more: Hive Mode Guide

Data Organization​

Memory Space Architecture
Per-Space (Isolated)

L1a: Conversations • L2: Vector Memories • L3: Facts • L4: Convenience API

Shared (Cross-Space)

L1b: Immutable Store • L1c: Mutable Store • User Profiles • Participant Registry

Per-space data is isolated; shared data is accessible across all spaces

Isolated to each memory space:

  • Layer 1a: Conversations (raw message history)
  • Layer 2: Vector memories (searchable embeddings)
  • Layer 3: Facts (LLM-extracted knowledge)
  • Layer 4: Convenience API results
// All scoped to memorySpaceId
await cortex.memory.remember({
  memorySpaceId: "user-123-personal",  // Isolation
  // ...
});

Creating Memory Spaces​

Just use a memorySpaceId—space created automatically on first use:

// First call creates space automatically
await cortex.memory.remember({
  memorySpaceId: "user-123-personal",
  conversationId: "conv-123",
  userMessage: "Hello",
  agentResponse: "Hi!",
  userId: "user-123",
  userName: "Alice",
});
Best For

Development and simple use cases. Zero ceremony, works immediately.

Naming Conventions​

Good Patterns
"user-{userId}-personal"     // Personal spaces
"team-{teamName}-workspace"  // Team spaces
"project-{projectId}"        // Project spaces
"{agentName}-agent-space"    // Agent spaces (Collaboration Mode)
Avoid
"space1"    // Too generic
"memory"    // No structure
"default"   // Ambiguous
"abc123"    // No meaning

Use Cases​

Personal AI Assistant

One space per user, all AI tools share it (Hive Mode)

Team Collaboration

One space per team, bots share context

Multi-Tenant SaaS

One space per customer, complete isolation

Autonomous Agents

Separate spaces, A2A communication (Collaboration Mode)

Project-Based

One space per project, isolated from other projects

Multi-Tenancy

Full tenant isolation via tenantId in AuthContext

Isolation Guarantees​

Complete Data Isolation​

// Space A
await cortex.memory.remember({
  memorySpaceId: "user-alice-personal",
  userMessage: "Secret information for Alice",
  // ...
});

// Space B cannot see it
const memories = await cortex.memory.search("user-bob-personal", "secret");
// Returns: [] (empty - different memory space)

Guarantees:

  • Complete data isolation between spaces
  • No accidental leakage
  • GDPR-compliant deletion (delete one space, others unaffected)
  • Independent analytics per space

Cross-Space Access (Context Chains)​

Limited cross-space access is possible via context chains:

// Supervisor creates context with delegation
const context = await cortex.contexts.create({
  purpose: "Process refund request",
  memorySpaceId: "supervisor-space",
  grantReadAccess: ["specialist-space"],
});

// Specialist can access supervisor's context (read-only, limited)
// NOT all of supervisor-space - only context-referenced data

Learn more: Context Chains

Participant Tracking (Hive Mode)​

Track "who stored what" in a shared memory space:

// Store with participant tracking
await cortex.memory.remember({
  memorySpaceId: "user-123-personal",
  participantId: "cursor",  // Track who stored it
  // ...
});

// Filter by participant
const cursorMemories = await cortex.memory.list("user-123-personal", {
  participantId: "cursor",
});

Benefits:

  • Debugging: "Which tool stored incorrect information?"
  • Analytics: "Which participant is most active?"
  • Audit: "Who had access to this data?"
  • Cleanup: Delete specific participant's contributions

Memory Space Lifecycle​

// 1. Create (implicit or explicit)
await cortex.memorySpaces.register({
  memorySpaceId: "project-apollo",
  name: "Apollo Project Memory",
  type: "project",
});

// 2. Use (store and retrieve)
await cortex.memory.remember({ memorySpaceId: "project-apollo", ... });

// 3. Archive (mark inactive, keep data)
await cortex.memorySpaces.archive("project-apollo", {
  reason: "Project completed",
});

// 4. Delete (GDPR-compliant, complete removal)
await cortex.memorySpaces.delete("project-apollo", {
  cascade: true,
  reason: "Data retention expired",
});

Multi-Tenancy Support​

All memory space operations automatically include tenant isolation when using auth context:

const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!,
  auth: createAuthContext({
    userId: "user-123",
    tenantId: "customer-acme",  // Tenant isolation
  }),
});

// All operations are now scoped to customer-acme
await cortex.memorySpaces.register({ memorySpaceId: "user-123-personal", ... });
const spaces = await cortex.memorySpaces.list();
// Only returns spaces for customer-acme

Security Considerations​

Data Isolation

Memory spaces provide complete isolation. Queries cannot cross space boundaries except via explicit Context Chains.

Access Control

Memory spaces don't have built-in permissions. Implement access control in your application layer:

async function canAccessSpace(userId: string, spaceId: string) {
  const space = await cortex.memorySpaces.get(spaceId);
  return space.metadata.owner === userId;
}

GDPR Cascade Deletion​

// Delete user and all their data across ALL memory spaces
await cortex.users.delete("user-123", { cascade: true });

// Or delete a specific memory space
await cortex.memorySpaces.delete("user-123-personal", {
  cascade: true,
  reason: "GDPR deletion request",
});

Cascade automatically deletes: user profile, conversations, vector memories, facts, sessions, and graph nodes.

Best Practices​

  1. Use descriptive names - user-123-personal not space1
  2. Register spaces in production - Enables analytics and tracking
  3. Always set participantId in Hive Mode - Tracks who stored what
  4. Choose one mode per system - Don't mix Hive and Collaboration patterns
  5. Plan for GDPR - Structure spaces for easy per-user deletion

Next Steps​