Skip to Content
Memory SystemNamespaces

Memory Namespaces

Namespaces provide scoped access control for the memory system, allowing fine-grained control over what agents can read and write.

What Are Namespaces?

A namespace is a logical partition within a memory level:

Memory Level
├── namespace:hr
│   └── [HR-specific data]
├── namespace:finance
│   └── [Finance-specific data]
└── namespace:shared
    └── [Cross-department data]

Namespace Structure

org_123/
├── working/
│   └── run_456/           # Auto-scoped to run
├── short_term/
│   ├── agent_789/         # Agent-specific
│   └── shared/            # Shared across agents
├── episodic/
│   └── agent_789/         # Agent-specific lessons
├── semantic/
│   ├── agent_789/         # Agent-specific facts
│   └── department:hr/     # Department-scoped
└── organizational/
    └── global/            # Org-wide knowledge

Access Control

Namespaces are controlled via capabilities:

capabilities:
  # Full access to own namespace
  - memory_read:semantic:agent_789
  - memory_write:semantic:agent_789
 
  # Read-only access to department
  - memory_read:semantic:department:hr
 
  # Read-only access to organizational
  - memory_read:organizational:global
 
  # No access to other departments
  # (absence of capability = denied)

Namespace Patterns

Agent-Scoped

Each agent has its own namespace:

memory/semantic/agent_123/
├── domain_knowledge
├── rules
└── patterns

Department-Scoped

Share knowledge within departments:

memory/semantic/department:engineering/
├── coding_standards
├── deployment_procedures
└── on_call_rotation

Project-Scoped

Share within projects:

memory/semantic/project:customer_onboarding/
├── process_steps
├── required_documents
└── approval_chain

Organization-Wide

Shared across all agents:

memory/organizational/global/
├── company_policies
├── org_structure
└── compliance_requirements

Creating Namespaces

Via UI

  1. Settings → Memory → Namespaces
  2. Click Create Namespace
  3. Configure:
    • Name
    • Memory level
    • Access permissions

Via API

mutation CreateNamespace($input: CreateNamespaceInput!) {
  createNamespace(input: {
    name: "department:legal"
    level: SEMANTIC
    description: "Legal department shared knowledge"
    permissions: [
      { role: "legal_agents", access: "read_write" },
      { role: "all_agents", access: "read" }
    ]
  }) {
    id
    name
    level
  }
}

Granting Access

To Agents

agent:
  name: "HR Offboarding Agent"
  memory_access:
    - namespace: semantic:agent_self
      access: read_write
    - namespace: semantic:department:hr
      access: read_write
    - namespace: organizational:global
      access: read

To Roles

role:
  name: "hr_agent"
  memory_permissions:
    - namespace_pattern: "semantic:department:hr/*"
      access: read_write
    - namespace_pattern: "organizational/*"
      access: read

Cross-Agent Sharing

Scenario: HR and IT Coordination

HR Agent writes to shared namespace:
memory/semantic/shared:offboarding/
├── pending_offboardings: ["user_123", "user_456"]

IT Agent reads from same namespace:
→ Knows which users need access revoked

Configuration

# HR Agent
memory_access:
  - namespace: semantic:shared:offboarding
    access: read_write
 
# IT Agent
memory_access:
  - namespace: semantic:shared:offboarding
    access: read

Best Practices

Principle of Least Privilege

Grant only necessary access:

  • Read-only when write isn’t needed
  • Specific namespaces over broad patterns
  • Review permissions regularly

Naming Conventions

Use consistent naming:

  • department:<name> for department scopes
  • project:<name> for project scopes
  • shared:<purpose> for cross-team data

Documentation

Document namespace purposes:

  • What data belongs here
  • Who should have access
  • When to use vs other namespaces

Monitoring

Track namespace usage:

  • Access patterns
  • Storage consumption
  • Permission changes
Semantic MemoryWorkflow Basics