cleveragents-core/docs/adr/ADR-002-namespace-system.md

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	Project Model	Projects are namespace-scoped entities that use the naming convention
ADR-010	Actor and Agent Architecture	Actors and agents are identified and resolved via namespaced names
ADR-011	Tool System	Tools use namespaced identifiers for discovery and conflict resolution
ADR-012	Skill System	Skills use namespaced names and resolve tool name conflicts via qualification
ADR-023	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