How-To Guide

Namespace Hierarchy

All Tiers

Parent/child namespaces with permission inheritance. Isolate client projects, environments, or multi-tenant workloads.

What is a namespace hierarchy?

Parent/child relationships between namespaces within a single organization

A namespace hierarchy lets you organize namespaces as a tree. A child namespace has exactly one parent; a parent can have many children. Children inherit permissions from parents by default, and admins at the parent level are automatically admins at all descendants.

acme-corp                   (parent)
├── acme-project-alpha       (child)
│   ├── alpha-dev            (grandchild)
│   ├── alpha-staging
│   └── alpha-prod
├── acme-project-beta
└── acme-research            (sibling, separate tree)

Shipped in v3.0.67 via migration 029 (adds parent_namespace column + tree/children APIs + frontend UI).

When to use it

Real patterns that benefit from hierarchy

Client → project isolation

Dev agencies: parent namespace per client, child namespace per project. Admins at the client level see everything for that client; project teams only see their project.

Environment separation

One parent per service (billing-api), children for dev / staging / prod. Memories, decisions, and agents stay scoped to each environment.

Multi-tenant workloads

SaaS apps serving multiple tenants: one parent per tenant, children for each workload. Tenant admins at the parent level; their engineers at children.

Research / experimentation

Parent namespace for the research programme, children for each experiment. Keeps experimental chaos (short-lived memories, throwaway decisions) from polluting the main programme view.

Create a child namespace

From the dashboard or via API

Via the dashboard

Open the namespace selector in the top bar.
Click Create Child Namespace (appears under the parent's row in the selector).
Enter the child's name. The parent is pre-filled.
Pick an entity category (optional) and click create.
The new child appears nested under the parent in the selector.

Via the REST API

curl -X POST http://localhost:7777/api/v1/namespaces/register \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "acme-project-alpha-dev",
    "parent_namespace": "acme-project-alpha",
    "description": "Dev environment for project alpha"
  }'

Via MCP

ace_create_namespace(
  namespace="acme-project-alpha-dev",
  parent_namespace="acme-project-alpha",
  description="Dev environment for project alpha"
)

How permission inheritance works

Access flows downward from parent to children

Parent access inherits to children

A member with read on the parent automatically has read on all descendants — unless access has been explicitly revoked at a child level.

Admins cascade

A member with admin on the parent is an admin at every descendant. They can invite members into children, manage settings, or archive child namespaces.

Child-specific grants do NOT propagate upward

Granting a member access to a child does not grant them access to the parent or siblings. Access flows strictly downward.

Reporters never inherit

Per the v3.0.72 security default, reporters must be explicitly granted each namespace. Hierarchy inheritance does not apply to the reporter role — it stays scoped.

Worked example

Alice is an admin on acme-corp. She automatically has admin access to acme-project-alpha, alpha-dev, alpha-staging, and alpha-prod. Bob is a reporter explicitly granted alpha-dev. Bob can ONLY see issues in alpha-dev — not alpha-staging, alpha-prod, acme-project-alpha, or acme-corp.

Navigating the tree

Dashboard and API surfaces

Dashboard

• /dashboard/namespaces shows a tree view of every namespace you have access to
• The top-bar namespace selector groups children under their parent, indented
• Namespace detail dialog shows parent, direct children, and a “Create Child” button

API endpoints

# Full tree from root (recursive CTE)
curl http://localhost:7777/api/v1/namespaces/tree \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Direct children of a specific namespace
curl http://localhost:7777/api/v1/namespaces/acme-corp/children \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# All namespaces you have access to (flat list)
curl http://localhost:7777/api/v1/namespaces/my \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

Reparenting a namespace

Move a namespace to a new parent at any time

You can change a namespace's parent at any time. Permissions recalculate immediately — members who had access via the old parent lose it if the new parent doesn't grant them the same role.

# Reparent alpha-dev from acme-project-alpha to acme-labs
curl -X PATCH http://localhost:7777/api/v1/namespaces/alpha-dev \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parent_namespace": "acme-labs"}'

# Remove parent (promote to root)
curl -X PATCH http://localhost:7777/api/v1/namespaces/alpha-dev \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parent_namespace": null}'

Careful: reparenting changes who can see the namespace. Audit the new parent's member list before moving anything with sensitive data.

Best practices

Patterns that work, patterns to avoid

Do

• Keep trees shallow — one level is usually enough
• Use hierarchy for isolation (auth boundaries, data separation)
• Make parent namespace names identify the owner, not the content
• Grant reporters at the leaf level, not the parent
• Archive unused children to keep the tree tidy

Don't

• Build trees 3+ levels deep (hard to reason about)
• Use hierarchy as a taxonomy (use tags for that)
• Put sensitive data in a child whose parent has broad admin access
• Reparent active namespaces without auditing member access
• Give reporters parent-level access expecting isolation

Ready to structure your workspace?

Head to the namespaces page, pick a parent, and create your first child namespace.

Related: Team Management • Reporter Role • REST API