Namespaces

Namespaces allow you to isolate memories between different agents, workspaces, or contexts within a single CortexaDB database file.

Overview

Every memory in CortexaDB belongs to a namespace. The default namespace is "default". Namespaces provide:

Isolation - Queries only return results from the target namespace
Organization - Group memories by agent, user, or topic
Access Control - Readonly namespaces for shared knowledge

Basic Usage

Creating a Namespace

# Get a namespace handle
agent_a = db.namespace("agent_a")
agent_b = db.namespace("agent_b")

Writing to a Namespace

agent_a.remember("Agent A's private memory")
agent_b.remember("Agent B's private memory")

Querying a Namespace

# Only searches within agent_a's memories
hits = agent_a.ask("What do I know?")

# Only searches within agent_b's memories
hits = agent_b.ask("What do I know?")

Deleting from a Namespace

agent_a.delete_memory(memory_id)

Ingesting Documents

agent_a.ingest_document("Long document...", chunk_size=512)

Default Namespace

When you use the top-level db.remember() and db.ask(), memories are stored in and queried from the "default" namespace.

# These are equivalent:
db.remember("text")
db.namespace("default").remember("text")

Readonly Namespaces

You can create readonly namespace handles for shared knowledge that shouldn't be modified:

shared = db.namespace("shared_knowledge", readonly=True)

# Reading works fine
hits = shared.ask("query")

# Writing raises CortexaDBError
shared.remember("text")  # Error!

This is useful for multi-agent systems where some agents should only read from a shared knowledge base.

Graph Edge Rules

Graph edges are namespace-scoped. You cannot create edges between memories in different namespaces:

agent_a = db.namespace("agent_a")
agent_b = db.namespace("agent_b")

mid1 = agent_a.remember("Memory in A")
mid2 = agent_b.remember("Memory in B")

# This will raise an error - cross-namespace edges are forbidden
db.connect(mid1, mid2, "relates_to")

Graph traversal during queries also respects namespace boundaries — BFS will not cross into other namespaces.

Common Patterns

Multi-Agent System

db = CortexaDB.open("agents.mem", embedder=embedder)

# Each agent has its own namespace
planner = db.namespace("planner")
researcher = db.namespace("researcher")
writer = db.namespace("writer")

# Agents store memories independently
planner.remember("Task: Write a blog post about AI")
researcher.remember("Found 3 relevant papers on AI agents")
writer.remember("Draft: AI agents are transforming...")

# Each agent queries only its own memories
planner_context = planner.ask("What tasks are pending?")

Shared Knowledge Base

# Admin writes to shared namespace
shared = db.namespace("shared")
shared.remember("Company policy: All code must be reviewed")

# Agents read from shared namespace (readonly)
agent = db.namespace("shared", readonly=True)
hits = agent.ask("What are the code review rules?")

Per-User Memory

def get_user_memory(db, user_id):
    return db.namespace(f"user_{user_id}")

alice = get_user_memory(db, "alice")
alice.remember("Alice prefers dark mode")

bob = get_user_memory(db, "bob")
bob.remember("Bob prefers light mode")

Next Steps

Core Concepts - How namespaces fit into the architecture
Query Engine - How namespace scoping affects queries
Python API - Namespace API reference

Namespaces

On this page