---
adr_number: 2
title: Namespace System
status_history:
- - '2026-02-16'
  - Proposed
  - Jeffrey Phillips Freeman
- - '2026-02-16'
  - Accepted
  - Jeffrey Phillips Freeman
tier: 1
authors:
- Jeffrey Phillips Freeman
superseded_by: null
related_adrs:
- number: 9
  title: Project Model
  relationship: Projects are namespace-scoped entities that use the naming convention
- number: 10
  title: Actor and Agent Architecture
  relationship: Actors and agents are identified and resolved via namespaced names
- number: 11
  title: Tool System
  relationship: Tools use namespaced identifiers for discovery and conflict resolution
- number: 12
  title: Skill System
  relationship: Skills use namespaced names and resolve tool name conflicts via qualification
- number: 23
  title: Server Mode
  relationship: Server mode introduces server-prefixed namespaces for multi-server resolution
acceptance:
  votes_for:
  - voter: Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>
    comment: A universal naming scheme avoids ambiguity and makes entity resolution predictable across all contexts
  votes_against: []
  abstentions: []
---
## Context

CleverAgents manages a wide variety of named entities — actors, tools, skills, resources, resource types, actions, projects, and plans. These entities must be uniquely identifiable, scopeable to different ownership levels (local machine, personal server account, organization), and discoverable across deployment boundaries. Without a uniform naming scheme, entity references would be ambiguous, collision-prone, and incompatible between local and server modes.

The system must also support connecting to multiple servers simultaneously and resolving names unambiguously in that context.

## Decision Drivers

- Entities (actors, tools, skills, resources, projects, plans) must be uniquely identifiable across deployment boundaries
- Must support multiple ownership scopes: local machine, personal server account, and organization
- Local-first development must work with zero server configuration
- System must handle simultaneous connections to multiple servers without name collisions
- Naming scheme must be uniform across all entity types to reduce cognitive overhead
- Transition from local-only to shared/collaborative usage should not require structural migration

## Decision

All named entities in CleverAgents use a universal **namespace-qualified name** format: `[[server:]namespace/]name`. Four namespace types define ownership and storage scope. The `local/` namespace is the default when no namespace is specified.

## Design

### Name Format

The fully qualified form is `server:namespace/name`. Components may be omitted with well-defined defaults:

| Form | Resolution |
|------|------------|
| `name` | `local/name` (default namespace is `local`) |
| `namespace/name` | Uses the specified namespace on the default server |
| `server:namespace/name` | Fully qualified — explicit server and namespace |

### Namespace Types

**`local/`** — Reserved namespace for machine-local entities. Stored in the local SQLite database. Fast iteration, no sharing, no server dependency. This is the default namespace when none is specified.

**`<username>/`** (e.g., `freemo/`, `jsmith/`) — Personal server namespace created when a user registers. Stored on the server, synced to the local machine when connected. Enables reusable entities across machines. Only the owning user can create or modify items.

**`<orgname>/`** (e.g., `cleverthis/`, `acme/`) — Organization namespace created when an organization is registered. Shared across team members. All entity types can be centrally managed under the org namespace.

**Built-in provider namespaces** (`openai/`, `anthropic/`, `google/`, etc.) — Reserved for built-in LLM actors. Automatically available when API keys are configured (via environment variables in local mode, or server-side keys in server mode). Cannot be used for custom actors.

### Server-Qualified Names

When connected to multiple servers, the server prefix disambiguates:

- `dev:freemo/code-coverage` — personal namespace on the `dev` server
- `prod:cleverthis/deploy-action` — org namespace on the `prod` server

### Resolution Rules

1. If the server prefix is omitted, the default server is assumed — unless the namespace is `local`, which always resolves locally.
2. If the namespace is omitted, `local` is used (configurable via `core.namespace`).
3. Names are stable identifiers; kebab-case is recommended.

### Entities Using This System

All of the following entity types follow the `namespace/name` convention: actors, tools, skills, resources, resource types, actions, projects, and plans.

## Constraints

- The `local/` namespace is reserved and must never be synced to a server.
- Built-in provider namespaces (`openai/`, `anthropic/`, `google/`, etc.) are reserved and must not be used for custom entity registration.
- Entity names within a namespace must be unique per entity type. The tuple `(namespace, entity_type, name)` is the uniqueness key.
- The `core.namespace` configuration key controls the default namespace prefix applied when creating entities without an explicit namespace.

## Consequences

### Positive
- A single naming convention applies uniformly to all entity types, reducing cognitive overhead.
- Local-first development requires zero server configuration — `local/` is always available.
- Transitioning from local to shared usage is a namespace change, not a structural migration.
- Multi-server support is built into the naming scheme from the start, avoiding future retrofitting.

### Negative
- Entity names become longer when fully qualified, which may be verbose in CLI usage.
- Name resolution logic must be implemented in every subsystem that handles entity references.
- Namespace synchronization between client and server adds operational complexity.

### Risks
- Namespace collisions between user and organization names must be prevented at registration time.
- If the default namespace configuration is changed inadvertently, entity resolution may silently resolve to the wrong scope.

## Alternatives Considered

None — specification-driven requirement. The universal namespace system is a foundational design choice that enables the local-first-to-collaborative progression and multi-server deployment model prescribed by the specification.

## Compliance

- **Registration validation**: The `agents <entity> add` commands validate that the namespace is well-formed, not reserved (for custom entities), and that the user has write permissions to the target namespace.
- **Name format tests**: Unit tests verify that entity name parsing correctly handles all forms (`name`, `namespace/name`, `server:namespace/name`) and rejects malformed inputs.
- **Integration tests**: Multi-namespace scenarios (local + server, multiple servers) are exercised in integration test suites.
- **Code review**: New entity types must demonstrate they follow the namespace convention before merging.