Project data storage

Every project must declare where its Knowledge, KV, and PersistentValue data may be stored:

{
  "workflowCode": {
    "projectInfo": {
      "dataStorage": {
        "mode": "local"
      }
    }
  }
}

mode accepts only these values:

Mode	Allowed locations	Runtime requirement
local	Local only	Desktop and CLI can run offline. Server storage access and Server execution are rejected.
server	Server only	Login and a cloud binding with the same package.json.id UUID are required. Local runs also use server data.
both	Local and server	Source code selects the location explicitly. Login is required only when server storage is actually accessed.

This declaration is a runtime permission boundary, not display metadata. A forbidden location fails directly and never falls back to, copies, deletes, or merges data from the other location. A legacy project without a declaration can open only Project Info in Desktop until it is updated; CLI, Core, and Server stop before evaluating the user module. New projects explicitly default to both.

Core 0.2 Context

Core 0.2 exposes two independent locations through context.storage:

await context.storage.local.kv.setValue("draft", { saved: true });
await context.storage.server.persistentValue.setValue("release", "ready");

Each location provides the same kv and persistentValue APIs. Top-level methods access the current project directly, while .conversation accesses the current conversation in that project. KV and PersistentValue use separate storage domains, so an identical key never overlaps across the two kinds. context.kv, context.persistentValue, .workflow, and a global scope do not exist.

A local project can use only context.storage.local, and a server project can use only context.storage.server. A both project may explicitly access either location during one run, but the two locations remain separate datasets. runWorkflow(..., { kvMode: "isolated" }) isolates project and conversation KV for both local and server storage.

Server identity

Server data is isolated by project UUID. To access context.storage.server, the top-level package.json.id must be the UUID of the bound cloud project and the caller must have access to that project. CLI can obtain the server connection from WORKFLOW_SERVER_URL, WORKFLOW_SERVER_ADMIN_KEY, or workspace login configuration. The server location is unavailable without a valid login and binding.

Server Web exposes server data only. Projects declared as server or both can run and access data. A local project or one without a declaration is blocked everywhere except the read-only settings explanation.

Desktop data source

Desktop combines local and cloud project summaries by the same UUID in the Knowledge and KV workspaces. local and server show only their declared location. both provides a Local/Server segmented control and remembers the selection separately. A disk icon, teal color, and text identify local data; a cloud icon, information blue, and text identify server data, so color is never the only signal.

The first switch from a local project to server data prompts for login. After login, Desktop creates or restores the cloud binding with the same UUID and synchronizes the complete project declaration. A failed switch keeps the previous source and discards cached server results. This operation does not migrate local data.

info

Changing the declaration controls future access only. It does not migrate existing KV, PersistentValue, or Knowledge data.