Skip to main content

​
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.
OperationBehavior
Write (ingest)Targets exactly one namespace
Write with no namespace fieldFalls back to the API key’s default_namespace_id
Read (query, search) with no namespaces fieldSearches all namespaces the caller can read
Read with namespaces: ["*"]Also means all readable namespaces
Read with explicit keysIntersected 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:
  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.
  • 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