Namespace Isolation

ZeroMemory isolates memories into namespaces so different contexts (sessions, projects, global) don't leak into each other.

Namespace Types

Namespace	Format	Use Case
Global	global	User-level memories shared across all sessions
Session	session:<sessionId>	Ephemeral per-conversation context
Project	project:<projectId>	Scoped to a specific project

How Namespaces Are Set

MCP (zerodb-memory server)

The MCP memory server auto-sets namespace to session:<sessionId> based on the active session. This means memories stored via MCP are session-scoped by default.

{
  "tool": "zerodb_store_memory",
  "input": {
    "content": "User prefers dark mode",
    "namespace": "session:abc123"
  }
}

REST API

The REST API defaults to global if no namespace is provided:

curl -X POST /api/v1/public/memory/v2/remember \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "content": "Important fact",
    "namespace": "project:my-app"
  }'

Cross-Namespace Recall

By default, recall only searches within the specified namespace. To search across all namespaces:

curl -X POST /api/v1/public/memory/v2/recall \
  -d '{
    "query": "user preferences",
    "namespace": "global",
    "allow_cross_namespace": true
  }'

Parameter	Default	Description
namespace	global	Which namespace to search
allow_cross_namespace	false	If true, searches all namespaces for the user

Cross-Namespace Mismatch

Memories stored via MCP (namespace session:<id>) are invisible to REST API recall (namespace global) unless allow_cross_namespace: true is set. This is the most common "missing memories" issue.

Consolidation Behavior

The reflection/consolidation pipeline operates on the global namespace. Session-scoped memories are promoted to global during episodic→semantic consolidation:

1. Session memories accumulate during a conversation
2. When reflection triggers, it reads from the session namespace
3. Consolidated semantic memories are written to global
4. This makes long-term knowledge accessible across all sessions

Namespace Configuration

Configure default namespace behavior per user or project:

POST /api/v1/public/memory/namespace/config
{
  "default_namespace": "project:my-app",
  "auto_promote_to_global": true
}

Validation Rules

• Must be one of: global, project:<id>, or session:<id>
• The <id> portion cannot be empty
• Invalid namespaces return a 422 validation error
• Namespace is required for all memory writes (no implicit default on write)