Managing Namespaces
Create namespaces and manage their threads, sources, memory, artifacts, and secrets.
Overview
Namespaces provide isolation boundaries within an app. Each namespace has its own threads, memory entries, sources, artifacts, and vault secrets. They are essential for multi-tenant applications, per-user isolation, or organizing data by project.
Creating a Namespace
Open the Namespace Dialog
- Navigate to your app and open the Namespaces tab
- Click Create Namespace
- The Create Namespace dialog appears
Fill in the Fields
| Field | Required | Description |
|---|---|---|
| Name | Yes | A descriptive identifier (e.g., customer-acme, project-alpha). Use lowercase with hyphens. |
| Description | No | Purpose of this namespace |
| Environment | No | Optionally bind the namespace to a specific environment |
| Embedding Model | No | Select the embedding model used for vector operations in this namespace. If not set, the workspace default is used. |
| Is Private | No | Checkbox to restrict visibility of this namespace |
Confirm Creation
Click Create Namespace. The namespace appears in the list and you can click into it to manage its contents.
Naming Convention
Use descriptive, lowercase names with hyphens. If you are using namespaces for
multi-tenancy, consider using customer IDs or project identifiers (e.g.,
tenant-12345, project-alpha).
Namespace Detail Tabs
When you open a namespace, you see five tabs:
| Tab | What It Contains |
|---|---|
| Threads | Conversation threads and their message histories |
| Sources | Knowledge documents scoped to this namespace |
| Memory | Persistent memory entries (facts, preferences, summaries, etc.) |
| Artifacts | Generated content (code, documents, reports) |
| Secrets | Vault secrets scoped to this namespace |
Managing Threads
Threads within a namespace track individual conversations.
- Automatic creation -- threads are created automatically when a new conversation starts via an endpoint or Cortex
- Manual creation -- you can also create threads manually for pre-seeded conversations
- Message history -- each thread has a full history of user, assistant, system, and tool messages
- Metadata -- threads can have custom metadata for filtering and organization
Use the Threads tab to browse, search, and inspect thread contents.
Working with Sources
The Sources tab manages knowledge documents scoped to this namespace:
- Upload documents specific to this namespace (same flow as workspace sources -- see Managing Sources)
- Namespace sources are only returned by source queries running within this namespace context
- Workspace-level sources remain accessible too -- a source query retrieves from both, with namespace sources taking priority
Workspace vs Namespace Sources
Workspace-level sources are shared across all namespaces. Namespace-level sources are isolated. When both exist, namespace sources take priority in query results.
Working with Memory
The Memory tab shows persistent memory entries scoped to the namespace:
- Memory entries can be created manually from this tab
- Memory entries are also created programmatically by
memory_updatesteps in your pipeline - Each entry has a type: fact, preference, summary, entity, instruction, or custom
- Memory entries are searchable via
memory_querysteps using semantic similarity
Viewing Artifacts
The Artifacts tab lists all artifacts generated by pipelines running within this
namespace. You can browse, preview, and download artifacts. Artifacts are created by
artifact_create steps and can be scoped to an execution, thread, or the namespace
itself.
Managing Secrets
The Secrets tab provides namespace-scoped vault secrets, separate from workspace-level secrets. This is essential for multi-tenant scenarios where each customer or project has its own credentials (API keys, tokens, connection strings).
Namespace secrets are referenced in tool configurations and step configs just like workspace secrets, but they are isolated to this namespace's execution context.
Reindexing a Namespace
If you change the embedding model or need to regenerate vectors for all sources in a namespace:
- Open the namespace from the Namespaces list
- Trigger Reindex from the namespace actions
- All sources in the namespace re-enter the processing pipeline with the current embedding model