Project

A Project groups membership, selected knowledge, and proposed changes. A local repository directory can bind to it so Agents find the right Memory while working. Server issues the Project identity; a directory name cannot replace it.

This page retains the historical /workspace URL. Current APIs use project_id. See the core data model for its relationship to Organization.

What a Project manages

State	Location	Purpose
Name, description, members	Server	Project identity and access
Org Selection	Server	Select published Organization Memory for this Project
Project Ref / Commit	Server, synchronized to daemon	Version Project-owned and selected Org content as an installable snapshot
Project-carried Drafts	Persisted locally, then synchronized to Server	Proposals targeting Project publication by default, or explicit Organization publication
Local directory bindings	Daemon	Resolve a working directory to project_id
Installed generations and search index	Daemon-managed files / SQLite	Local Agent reads and retrieval

Membership authorization and content selection are separate concerns. Selecting a Memory puts it in the baseline; a personal Bundle, directory binding, or Agent request does not change membership permissions.

Create and configure in Memory

Use New Project… in the Memory project selector. Organization members can create projects; the creator becomes the project owner and can edit its details, add or remove existing organization members, select Memory, and delete the project. These permissions do not grant organization administration or publication authority.

Open Project Settings beside the selector to configure the current project. Repositories on This Mac and cache settings apply locally; other members bind their own directories. The selector ends with New Project… for both members and organization administrators.

Organization administrators can open Settings → Organization → Projects to view all organization projects and manage their details and members, including projects they have not joined. Reading their Memory still requires project membership.

From selection to readable content

Project-owned Memory + selected Organization Memory
  → Server generates Project Commit / Ref
  → daemon installs the snapshot
  + this Project's open/submitted Draft changes
  → Effective Memory

For example, Payments selects the deployment rollback checklist. All work directories bound to Payments refer to the same Server Project. An edit creates a Draft carried by Payments. After synchronization, another installation can present that Project's proposal too. It is not an independently published file in one directory, nor another Project's unpublished change.

Unpublished changes overlay only the carrying Project. A Project merge publishes only Project-owned content and notifies members. An optional Org contribution becomes an independently approved Org Review. Org updates refresh selecting Projects while preserving their Project adaptations.

GET /api/v1/projects/{project_id}/memories reads published Project-owned Memory. It includes neither current selection projections nor local Draft overlays and cannot replace Effective Memory.

Directory binding

A binding is:

Normalized Server URL + canonical local directory → Server project_id

The daemon stores bindings in central SQLite project_bindings. From a subdirectory, it chooses the longest bound ancestor. An unbound Git worktree can also resolve through the main checkout's repository root. Moving or rebinding a directory changes local resolution, not Server Project identity.

Both managed host-plugins and manually started mcp serve require a working-directory binding. They validate it at startup and every tools/call, failing if the binding disappears or changes. Unbound directories cannot fall back to the Desktop-selected Project.

Two bound Agent processes can therefore serve different repositories concurrently. Switching the Desktop selection does not redirect managed processes. A tool request cannot choose an arbitrary project_id to bypass binding.

The runtime no longer reads or migrates ~/.clumsies/config.toml, and legacy ws_id is not Project identity. See Adapter and Runtime for installation and entry-point details.

Project Local Storage

An installation can choose where a Project stores generations and its search database. The setting is keyed by Server URL and project_id, applies only locally, and is not Server Project metadata.

The chosen directory is the parent of a daemon-managed subtree. Central Drafts, queued operations, credentials, cached snapshot objects, and shared models do not move. If a custom location is unavailable, the daemon reports it instead of silently creating another active cache. See Runtime for moves and recovery.

Investigating missing Memory

Check the data flow in order: the directory's bound Project, its Org Selection, the installed Project Commit, any Draft overlay, and index readiness. A publication awaiting local synchronization, an unselected resource, and a Draft overriding the baseline are different problems.

Continue with Organization Memory, Core data model, and Architecture. Implementation sources: binding resolution, MCP entry point, Project projection, and local storage.