UnisonPath namespaces
Where an agent writes is who sees it: /private/ (caller only), /workspace/ (whole workspace), read-only /system/ and the ingest-only /private/sources/ - and every path ends in .md.
The cortex is a scope-only filesystem: where the agent writes is who sees it. Sharing is an explicit upgrade by qualifying the path - not a permission matrix to administer.
Canonical source of truth. This page, together with the brain's own generated /SCHEMA.md (read it at runtime via GET /v1/brain/doc?path=/SCHEMA.md), is the authoritative definition of the path/kind model. SDKs and client plugins should link here rather than re-describe the model in their own docs — re-described copies drift out of date. The canonical scheme is /private/<kind>/<slug>.md for entities and /private/notes/<slug>.md for everything else; there is no /private/kb/, no plural entity folders, and no /tenant/ term.
| Root | Visibility | Writable |
|---|---|---|
/private/ | only the caller (default) | yes |
/workspace/teams/<slug>/ | that team within the workspace | yes |
/workspace/ | the whole workspace | yes |
/system/ | synthesized views | read-only |
/private/sources/ | connector ingest | read-only |
Legacy roots /wiki/, /skills/, /actions/, and /raw/ have been removed; do not use them in new integrations.
Rules
- Document paths must end in
.md- anything else is400 invalid_path. - Writes/deletes to
/system/or/private/sources/return403. There is no top-level/sources/— connector data is ingest-only under/private/sources/<type>/…. - With actor delegation, each actor gets an isolated
/private/automatically.
Promoting private knowledge
POST /v1/brain/share with { kind: "doc" | "fact" | "entity", id } promotes a private item to workspace visibility. CLI: unison share doc <id>.
Reading across tiers
GET /v1/brain/fs?path lists any tier (dir / file / mtime); GET /v1/brain/fs/read?path reads raw content including the read-only tiers. CLI: unison tree, unison get --raw.
Scoped recall
Both search and context recall accept pathPrefix, so a session can confine memory to its lane: unison context "deploy process" --path-prefix /workspace/teams/platform/.