Memory Namespaces

Namespaces partition memories within an organization into isolated collections. They enable data separation by team, project, sensitivity level, or any logical boundary.

What Namespaces Do

• Isolate data -- memories in namespace A are invisible to queries scoped to namespace B
• Control access -- policies can allow/deny access per namespace
• Set retention -- each namespace can have its own retention period
• Classify sensitivity -- mark namespaces as normal, sensitive, or restricted

Creating a Namespace

curl -X POST https://api.hippocortex.dev/v1/organizations/org_abc123/namespaces \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Data",
    "slug": "customer-data",
    "teamId": "team_789",
    "description": "All customer-facing memory data",
    "defaultAccess": "team",
    "sensitivity": "sensitive",
    "retentionDays": 365
  }'

Fields

Field	Type	Default	Description
name	string	required	Human-readable name
slug	string	auto	URL-safe identifier
teamId	string	null	Owning team (optional)
description	string	null	What this namespace is for
defaultAccess	string	team	Default access level: public, org, team, private
sensitivity	string	normal	Data sensitivity: normal, sensitive, restricted
retentionDays	number	null	Auto-delete after N days (null = no auto-delete)
metadata	object	{}	Arbitrary key-value data

Assigning Memories to a Namespace

When capturing events, include namespace_id in the request body:

curl -X POST https://api.hippocortex.dev/v1/capture \
  -H "Authorization: Bearer hx_live_..." \
  -H "X-Organization-ID: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user_interaction",
    "sessionId": "sess_123",
    "payload": { "message": "Hello" },
    "namespace_id": "ns_456"
  }'

The API validates that the namespace belongs to the specified organization.

Scoping Rules

How Namespace Scoping Works in Retrieval

When POST /v1/synthesize is called with an X-Organization-ID header:

1. The policy engine evaluates which namespaces the principal can access
2. Only memories from allowed namespaces are returned
3. If a specific namespaceId is provided in the body, results are restricted to that namespace

Without X-Organization-ID, the standard tenant-scoped retrieval is used (backward compatible).

Default Access Levels

Level	Who Can Access
public	Anyone in the organization
org	All org members (same as public currently)
team	Only members of the owning team
private	Only the namespace creator + admins

Access policies override these defaults. See Policies.

Listing Namespaces

curl "https://api.hippocortex.dev/v1/organizations/org_abc123/namespaces?sensitivity=sensitive" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"

Filter by teamId or sensitivity.

Updating a Namespace

curl -X PATCH https://api.hippocortex.dev/v1/organizations/org_abc123/namespaces/ns_456 \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "retentionDays": 180 }'

Deleting a Namespace

curl -X DELETE https://api.hippocortex.dev/v1/organizations/org_abc123/namespaces/ns_456 \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"

Deleting a namespace removes the namespace record. Memories that were assigned to it retain their namespace_id but will no longer be retrievable through namespace-scoped queries.