> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remem.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Namespaces

> Split one workspace into isolated read and write areas for documents, agents, and API keys.

# Namespaces

Remem uses **workspaces** as the top-level customer boundary and **namespaces** as the isolation boundary inside one workspace.

Use namespaces when you want multiple agents, teams, or workflows to share one workspace but not all read and write the same memory.

## Hierarchy

```text theme={null}
Org
└── Workspace (backend: tenant)
    ├── Namespace: default
    ├── Namespace: work
    ├── Namespace: personal
    └── Namespace: research
```

Every workspace gets a `default` namespace. Additional namespaces are created under that same workspace.

## What a namespace isolates

Inside a workspace, namespace scope applies to:

* documents and chunks
* query results
* extracted facts and entities
* PageIndex trees/nodes
* audit and lifecycle records tied to tenant content

Namespaces do **not** create a separate workspace, a separate org, or a separate encryption domain. Remem still keeps one tenant-level DEK and one per-tenant Qdrant collection; namespace filtering happens inside that workspace boundary.

## Read and write model

Namespaces are enforced through API-key grants.

| Operation                                           | Behavior                                           |
| --------------------------------------------------- | -------------------------------------------------- |
| Write (`ingest`)                                    | Targets exactly one namespace                      |
| Write with no `namespace` field                     | Falls back to the API key's `default_namespace_id` |
| Read (`query`, `search`) with no `namespaces` field | Searches all namespaces the caller can read        |
| Read with `namespaces: ["*"]`                       | Also means all readable namespaces                 |
| Read with explicit keys                             | Intersected with the caller's readable grants      |

Permissions are per namespace:

* `read_write`
* `read_only`

If a caller names a namespace key that exists but is not granted, Remem returns `403`. If the key does not exist or is archived, Remem returns `404`.

## Stable key vs display name

Each namespace has:

* `key`: stable API-facing identifier like `work`, `research`, `team.alpha`
* `name`: human-readable label shown in the portal

Use the **key** in data-plane APIs, CLI commands, and MCP tools.

## Managing namespaces in the portal

In the Remem portal, open **Dashboard -> Namespaces** to:

* list active namespaces in the current workspace
* create a namespace
* rename a namespace
* archive or restore a namespace

When creating or editing an API key in the portal, you can also set:

* the key's **default namespace**
* which namespaces it can read or write

## Management API

Namespace management uses a **portal JWT**, not a `vlt_...` API key.

### List namespaces

```bash theme={null}
curl https://api.remem.io/v1/namespaces \
  -H "Authorization: Bearer <portal_jwt>" \
  -H "X-Tenant-Id: <workspace_uuid>"
```

### Create a namespace

```bash theme={null}
curl -X POST https://api.remem.io/v1/namespaces \
  -H "Authorization: Bearer <portal_jwt>" \
  -H "X-Tenant-Id: <workspace_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "research",
    "name": "Research"
  }'
```

### Update a namespace

```bash theme={null}
curl -X PATCH https://api.remem.io/v1/namespaces/<namespace_uuid> \
  -H "Authorization: Bearer <portal_jwt>" \
  -H "X-Tenant-Id: <workspace_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Archive",
    "status": "archived"
  }'
```

### Create a namespace-scoped API key

```bash theme={null}
curl -X POST https://api.remem.io/v1/auth/api-keys \
  -H "Authorization: Bearer <portal_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "<workspace_uuid>",
    "name": "research-agent",
    "default_namespace_id": "<research_namespace_uuid>",
    "scopes": [
      {
        "namespace_id": "<research_namespace_uuid>",
        "permissions": ["read", "write"]
      },
      {
        "namespace_id": "<shared_namespace_uuid>",
        "permissions": ["read"]
      }
    ]
  }'
```

### Update API key scopes

```bash theme={null}
curl -X PATCH https://api.remem.io/v1/auth/api-keys/<key_uuid>/scopes \
  -H "Authorization: Bearer <portal_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "default_namespace_id": "<research_namespace_uuid>",
    "scopes": [
      {
        "namespace_id": "<research_namespace_uuid>",
        "permissions": ["read", "write"]
      }
    ]
  }'
```

<Note>
  If you omit `scopes` when creating a key, Remem grants `read_write` on the workspace's `default` namespace. It does not automatically grant every namespace in the workspace.
</Note>

## Data-plane API usage

### Write into one namespace

Use the namespace **key** on ingest:

```bash theme={null}
curl -X POST https://api.remem.io/v1/documents/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vlt_..." \
  -d '{
    "title": "Research note",
    "content": "New ranking experiment...",
    "namespace": "research"
  }'
```

If you omit `namespace`, Remem writes into the API key's default namespace.

### Read from one namespace

```bash theme={null}
curl -X POST https://api.remem.io/v1/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vlt_..." \
  -d '{
    "query": "latest ranking experiments",
    "namespaces": ["research"]
  }'
```

### Read across several namespaces

```bash theme={null}
curl -X POST https://api.remem.io/v1/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vlt_..." \
  -d '{
    "query": "cross-team updates",
    "namespaces": ["research", "shared"]
  }'
```

### Read across all readable namespaces

```bash theme={null}
curl -X POST https://api.remem.io/v1/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vlt_..." \
  -d '{
    "query": "everything relevant from this week",
    "namespaces": ["*"]
  }'
```

## CLI usage

The CLI uses namespace **keys**:

```bash theme={null}
remem query "latest experiments" --namespace research
remem query "handoff notes" --namespace research --namespace shared
remem search "launch plan" --namespace '*'
```

Rules:

* repeat `--namespace` for multiple namespace keys
* quote `'*'` so your shell does not expand it
* writes without a namespace rely on the API key's default namespace

## MCP usage

The packaged MCP server supports namespace-aware read and write tools.

### Configure a default write namespace

```bash theme={null}
export REMEM_DEFAULT_NAMESPACE="research"
```

This is used by write tools such as `remem_ingest` when the tool call omits `namespace`.

### Read with namespace scope

```json theme={null}
{
  "query": "latest experiments",
  "mode": "rich",
  "namespaces": ["research", "shared"]
}
```

### Write with explicit namespace

```json theme={null}
{
  "title": "Research checkpoint",
  "content": "Tried reranker v3 today.",
  "namespace": "research"
}
```

If both the tool call and `REMEM_DEFAULT_NAMESPACE` omit a namespace, the backend falls back to the API key's default namespace.

## OpenClaw plugin behavior

The OpenClaw plugin currently does **not** expose explicit namespace config fields. It inherits namespace behavior from the API key you give it:

* searches run across all namespaces that key can read
* creates/updates fall back to the key's default namespace

The practical pattern is:

1. Create a dedicated API key for the OpenClaw agent.
2. Set that key's default namespace to the agent's write target.
3. Grant only the namespaces the agent should read.

That gives you namespace isolation today without extra plugin-side config.

## Recommended patterns

* Give each autonomous agent its own namespace.
* Use a separate shared namespace for handoff or supervisor visibility.
* Keep personal/private notes in a namespace served by a different API key.
* Use `read_only` grants for supervisor or analyst agents that should aggregate without writing.

## See also

* [Authentication](/authentication)
* [Documents & Ingestion](/documents)
* [Querying](/querying)
* [CLI](/cli)
* [MCP Integration](/mcp-integration)