---
title: "Namespace Isolation"
description: "How ZeroMemory isolates memories using namespaces — global, session, and project scopes."
canonical: "https://docs.ainative.studio/docs/zeromemory/namespaces"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Namespace Isolation

Source: https://docs.ainative.studio/docs/zeromemory/namespaces

> How ZeroMemory isolates memories using namespaces — global, session, and project scopes.

# 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.

```json
{
  "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:

```bash
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:

```bash
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 |

:::warning 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:

```bash
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)