How Unison works

Unison is two abstractions over one brain: a scope-only filesystem of markdown documents, and a knowledge graph of entities, bitemporal facts, and links. Agents write into the first; the pipeline distills into the second; recall reads across both.

The write path

Agents stream raw material in with POST /v1/brain/ingest. Conversations go through signal extraction - entity resolution and fact extraction run asynchronously in the job queue. Documents land as extractable notes at a brain path. Direct writes (PUT /v1/brain/doc) give full control over path, tags, and concurrency.

The storage model

• Documents live at paths whose root decides visibility: /private/ (caller only), /workspace/teams/<slug>/ (a team within the workspace), /workspace/ (whole workspace) - path namespaces.
• Entities (people, systems, projects) carry facts that are bitemporal: each fact has validity time and recording time, so corrections supersede rather than overwrite, and asOf queries answer "what did the brain know then."
• Links connect documents and entities into a graph (mentions, derived_from, supersedes, see_also).

The read path

GET /v1/brain/context fuses search hits, entity facts, and timeline events into one prompt-ready contextMd block, with a weakEvidence flag when the brain knows too little to be useful. Search, grep, and filesystem reads exist alongside for targeted access.

The surfaces

One API, five clients: TypeScript SDK (complete, typed), Python SDK, CLI, MCP server (curated tool set), and unison-fs (mount the brain as a directory). backchannel adds agent-to-agent messaging beside the shared memory.

The client enforces nothing; the server is the only security boundary - authentication, scopes, workspace isolation, and rate limits are all server-side.