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

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

curl https://api.remem.io/v1/namespaces \
  -H "Authorization: Bearer <portal_jwt>" \
  -H "X-Tenant-Id: <workspace_uuid>"

Create a namespace

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

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

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

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"]
      }
    ]
  }'

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.

Data-plane API usage

Write into one namespace

Use the namespace key on ingest:

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

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

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

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:

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

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

{
  "query": "latest experiments",
  "mode": "rich",
  "namespaces": ["research", "shared"]
}

Write with explicit namespace

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

Create a dedicated API key for the OpenClaw agent.
Set that key’s default namespace to the agent’s write target.
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.

Getting Started

Using Remem

Memory Layer

Integrations

Namespaces

Namespaces

Hierarchy

What a namespace isolates

Read and write model

Stable key vs display name

Managing namespaces in the portal

Management API

List namespaces

Create a namespace

Update a namespace

Create a namespace-scoped API key

Update API key scopes

Data-plane API usage

Write into one namespace

Read from one namespace

Read across several namespaces

Read across all readable namespaces

CLI usage

MCP usage

Configure a default write namespace

Read with namespace scope

Write with explicit namespace

OpenClaw plugin behavior

Recommended patterns

See also

​Namespaces

​Hierarchy

​What a namespace isolates

​Read and write model

​Stable key vs display name

​Managing namespaces in the portal

​Management API

​List namespaces

​Create a namespace

​Update a namespace

​Create a namespace-scoped API key

​Update API key scopes

​Data-plane API usage

​Write into one namespace

​Read from one namespace

​Read across several namespaces

​Read across all readable namespaces

​CLI usage

​MCP usage

​Configure a default write namespace

​Read with namespace scope

​Write with explicit namespace

​OpenClaw plugin behavior

​Recommended patterns

​See also

Namespaces

Hierarchy

What a namespace isolates

Read and write model

Stable key vs display name

Managing namespaces in the portal

Management API

List namespaces

Create a namespace

Update a namespace

Create a namespace-scoped API key

Update API key scopes

Data-plane API usage

Write into one namespace

Read from one namespace

Read across several namespaces

Read across all readable namespaces

CLI usage

MCP usage

Configure a default write namespace

Read with namespace scope

Write with explicit namespace

OpenClaw plugin behavior

Recommended patterns

See also