# ADR-002: Namespace System

**Status:** Accepted  
**Date:** 2026-02-16  
**Supersedes:** None  
**Author(s):** Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>  
**Approver(s):** Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>

## 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

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.

## Related ADRs

| ADR | Title | Relationship |
|-----|-------|-------------|
| [ADR-009](ADR-009-project-model.md) | Project Model | Projects are namespace-scoped entities that use the naming convention |
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors and agents are identified and resolved via namespaced names |
| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools use namespaced identifiers for discovery and conflict resolution |
| [ADR-012](ADR-012-skill-system.md) | Skill System | Skills use namespaced names and resolve tool name conflicts via qualification |
| [ADR-023](ADR-023-server-mode.md) | Server Mode | Server mode introduces server-prefixed namespaces for multi-server resolution |

## Acceptance

### Votes For

| Voter | Comment |
|-------|---------|
| Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> | A universal naming scheme avoids ambiguity and makes entity resolution predictable across all contexts |

**Total: 1**

### Votes Against

| Voter | Comment |
|-------|---------|

**Total: 0**

### Abstentions

| Voter | Comment |
|-------|---------|

**Total: 0**
