One brain, every agent. A cloud brain that Claude Code, Cursor, Codex — and your research, ops, and personal agents — read from and write back to, on any machine, for every teammate. Not another per-tool memory silo; the one source of truth they all share — with temporal facts that know what changed when and entity resolution that knows who's who, the parts a vector dump gets wrong.
Why • Benchmarks • Quickstart • Install • For agents • SPEC
🤖 Reading this as an AI agent? Install the CLI, then run
unison skill installand adoptskill/SKILL.md— the canonical agent guide: setup, login, the recall-before-reasoning loop, and when/how to save what you learn.AGENTS.mdhas the MCP fallback and repo-contributor guide.
Every agent starts each session blank — the context window resets the moment you
close the terminal. The usual patches only half-fix it: a CLAUDE.md here, Cursor's
memory there, a local notes.md in one repo, a wiki nobody syncs. The knowledge
survives, but it's trapped — scoped to one tool, one repo, one machine, one person.
It never travels. The decisions and the hard-won why end up everywhere except where
your next agent can reach them.
The Unison brain is a hosted knowledge base — decisions, conventions, architecture, prior fixes, people — that any agent reads from and writes back to, from any machine, with one command:
unison search "why did we pick email-otp auth"It's not only for coding agents: the same brain backs your research, ops, and personal agents too. It's a knowledge graph of documents, entities, and bitemporal facts — not a codebase index — so anything worth remembering lives in one place every agent shares. Coding agents are just the sharpest first example.
This repo is the open-source client: a CLI, an SDK, an MCP server, and an agent
skill. No local database, no vector index to run, no framework to adopt — the brain
lives in the cloud and every surface speaks one API. It's open source so you can read
exactly what it sends before you pipe it into an agent with shell access; the backend
that stores and searches your data is a separate, closed service (SPEC.md
is the contract this client speaks).
| Package | Install as | What it is |
|---|---|---|
@unisonlabs/cli |
unison |
The CLI: search, get, write, list, status, auth. |
@unisonlabs/sdk |
@unisonlabs/sdk |
Typed HTTP client the CLI and MCP server are built on. |
@unisonlabs/mcp |
unison-brain-mcp |
A Model Context Protocol server for agents without shell access. |
skill/SKILL.md |
— | The primary agent entry: a drop-in Agent Skill covering setup, auth, recall, and capture (+ reference.md). |
The SDK is the core; the CLI and MCP server are thin wrappers over it, and the skill wraps the CLI — one API contract, four surfaces.
| 🐟 Without a brain | 🧠 With Unison |
|---|---|
| "Why did we switch to email-OTP auth?" → the agent greps, guesses, or asks you for the third time | unison search "why email-otp auth" → the actual decision and its reasoning, in one second |
| New laptop, new repo, new teammate → re-explain the whole architecture from scratch | One brain. Every agent, every machine, every teammate reads the same source of truth |
CLAUDE.md / .cursorrules go stale the day after you write them |
Agents write back what they learn, so the brain stays current on its own |
| mem0 / Letta / Zep are frameworks you build an agent with | Plugs into the agents you already use — nothing to host, no migration |
| A flat log of past chat messages | A knowledge graph: entities (people, projects) + bitemporal facts — who, what, and what changed when |
Bolting "memory" onto an agent is easy: dump messages into a vector DB, embed, retrieve. That gets you ~80% — and for a single user remembering a preference, the model providers now give that away for free. The remaining 20% is where memory actually breaks, and it's the whole point of Unison:
- Temporal correctness. Facts change. Someone switches jobs, a decision gets reversed, a price updates. Most memory systems keep returning the stale fact with confidence. Unison stores bitemporal facts with supersession chains — it knows not just what's true, but what changed when, and stops surfacing the version that's no longer true.
- Identity resolution. "Dan", "Daniel",
daniel@…, and "the new backend hire" are one person. Naive memory stores them as four, and the facts scatter. Unison runs tiered entity resolution (deterministic → fuzzy → a calibrated LLM judge, auto-merging above a confidence threshold) so facts attach to the right entity. - One brain, every agent — shared and consistent. Per-tool memory (Cursor's, a
CLAUDE.md, mem0 inside one app) is a silo. Unison is one source of truth every agent and teammate reads from and writes back to — Claude Code, Cursor, Codex, voice, your backend — so your fleet doesn't hold contradictory beliefs.
"Can't I just build this with Postgres + pgvector?" You can build the 80%. The 20% above — temporal supersession, calibrated identity resolution, multi-agent consistency, and the retrieval tuning that makes memory drive decisions instead of just echo them — is what this project is. And we measure it in the open, so you don't have to take our word for it (see below).
Memory benchmarks in this space are mostly self-reported and don't reproduce: vendors quote headline numbers against weak baselines, and independent attempts to reproduce those scores have failed. We do the opposite. Unison-evals is an open harness that scores every memory system — including ours — on the same code, with a decision-driving test (memory that must change what the agent does, not just what it can recall) that most vendor benchmarks avoid.
No cherry-picked baselines. Clone it, run it, check our claims against everyone else's.
npm i -g @unisonlabs/cli
unison auth login # enter email → OTP → signed in
unison status # confirm you're connected
unison search "auth decision" # search the brain
unison write /private/notes/x.md # pipe content in or pass --file
unison context "what did we decide about auth?" # one-call memory recallDocuments: search, grep, cat/get, ls, tree, find, write, edit,
rm, tag, share, neighbors, links, link. Graph: entity …, fact …,
timeline. Admin: review …, jobs …. Add --json to any
command. Full surface and the backend contract are in SPEC.md.
The brain is path-addressable (/private/, /workspace/, /system/), so it
navigates with the commands you already know:
unison ls # entries at the root (dirs + files)
unison ls /private # entries under /private
unison ls /workspace/people --docs # documents with titles instead of the dir view
unison tree /private # recursive tree under /private
unison find '/private/**auth*' # paths matching a glob
unison cat /workspace/projects/architecture.md # read a document (alias of `get`)
unison cat --raw '/system/...' # read any tier, including synthetic ones
unison grep "TODO" --json # regex scan over document bodiesBeyond documents, the brain has entities (canonical people/projects/companies) and bitemporal facts about them:
id=$(unison entity resolve "Daniel" --json | jq -r .entity.id)
unison fact ls --entity "$id" # what the brain knows about Daniel
unison timeline "$id" # facts over time
unison fact add "$id" works_at "Joined Unison in 2026" --confidence 0.9
unison neighbors /workspace/projects/architecture.md # linked documentsSelf-onboarding: point your agent at AGENTS.md — it walks any
agent (Claude Code, Cursor, Codex, or any MCP/CLI-capable agent) from zero to a
working brain in four steps, then teaches the search-first / write-back loop.
Pass --json for machine output: results are JSON on stdout (compact when
piped); errors are a JSON envelope on stderr with a nonzero exit code
(4 auth, 3 not found, 5 conflict, 1 other). Destructive commands (rm,
fact rm, review merge) require --yes in non-interactive shells. Drop the
skill in with unison skill install, or run unison --help / unison <cmd> --help — the help is written to be read by an agent.
unison search "rate limiting" -k 5 --json | jq '.[].doc.path'
unison get /workspace/projects/architecture.md --jsonunison auth login signs you in via email-OTP — enter your email, get a code,
done. No browser, no OAuth dance. Account creation and key recovery both happen
in the terminal. The key is stored at ~/.config/unison/config.json (mode 0600).
unison auth login # prompts for email; sends OTP
unison auth verify <code> # (optional) verify to lift usage caps
unison auth keys # list your API keys
unison auth keys create --name ci # mint a key for CI; token shown once
unison auth keys revoke <id> # revoke a key
unison invite [email protected] # invite someone to your workspace
unison invites # list pending invitationsMulti-workspace — if you belong to more than one workspace:
unison workspaces ls # list all workspace memberships
unison switch <workspaceId> # switch active workspace (mints or recalls key)
unison switch "Team Brain" # also accepts a unique nameActor delegation (service keys acting on behalf of end users):
# Mint a service key with brain:act-as scope (owner/admin only)
unison auth keys create --name service --scopes brain:read brain:write brain:act-as
# Per-command delegation
unison write /private/notes/x.md --actor user-001 -m "hello"
unison search "query" --actor user-001
# Global delegation via env var (all brain commands)
export UNISON_ACTOR=user-001
unison search "query"For CI and headless agents, skip interaction — set an API key:
export UNISON_TOKEN="usk_live_..." # overrides the stored credential
export UNISON_API_URL="https://brain.unisonlabs.ai" # optional; this is the defaultUNISON_TOKEN always takes precedence over the stored file.
npm i -g @unisonlabs/cli # or: pnpm add -g / bun add -g / npx @unisonlabs/cli
unison auth login # enter your email; OTP sent; key storedDistributed via npm as three packages: @unisonlabs/cli (the unison binary),
@unisonlabs/sdk (the typed client library), and @unisonlabs/mcp (the MCP
server). The published binaries are plain compiled JS with a
#!/usr/bin/env node shebang — they run on Node or Bun, no runtime to install.
Claude Code / Cursor / Codex (with a shell): install the CLI, then install the
skill so the agent knows when and how to use the brain (or just point the agent at
AGENTS.md and let it self-onboard):
unison skill install # writes the skill to ~/.claude/skills/unison-brain/Agents without a shell: register the MCP server.
{
"mcpServers": {
"unison-brain": {
"command": "npx",
"args": ["-y", "@unisonlabs/mcp"],
"env": { "UNISON_TOKEN": "usk_live_...", "UNISON_API_URL": "https://brain.unisonlabs.ai" }
}
}
}source <(unison completion bash) # bash — add to ~/.bashrc
source <(unison completion zsh) # zsh — add to ~/.zshrc
unison completion fish > ~/.config/fish/completions/unison.fishimport { BrainClient } from "@unisonlabs/sdk";
const u = new BrainClient({ baseUrl: "https://brain.unisonlabs.ai", token: process.env.UNISON_TOKEN });
// Brain: search, write, and surgically edit knowledge.
const hits = await u.search("auth decision", { limit: 5 });
await u.write({ path: "/private/notes/auth.md", bodyMd: "We chose email-OTP because …" });
await u.editDoc({ path: "/private/notes/auth.md", oldStr: "email-OTP", newStr: "email-OTP (verified)" });
// Graph: resolve an entity and read the facts the brain holds about it.
const daniel = await u.entities.resolve("Daniel");
const facts = daniel ? await u.facts.about(daniel.id) : [];
// Multi-workspace: list memberships and list keys for another workspace.
const workspaces = await u.workspaces.list(); // [{ id, name, role, active }]
const otherKeys = await u.keys.list({ workspaceId: workspaces[1]?.id });
// Actor delegation: service key acting on behalf of end users (requires brain:act-as scope).
const svc = new BrainClient({ apiUrl: "https://brain.unisonlabs.ai", token: serviceKey });
const user1 = svc.withActor("user-001");
const user2 = svc.withActor("user-002");
await user1.write({ path: "/private/notes/x.md", bodyMd: "user 1 note" });
const r = await user2.search("query"); // isolated from user-001
const me = await user1.whoami(); // .actedAs = { externalId: "user-001", userId }See examples/ for more.
Requires Bun.
bun install
bun test # unit tests (SDK + CLI)
bun lint # Biome
bun run packages/cli/src/index.ts --help # run the CLI from source
bun run build # bundle each package to dist/
node packages/cli/dist/index.js --help # run the built (node) binaryThis is a Bun workspace monorepo: packages/* resolve each other by name during
development. bun run build bundles the CLI and MCP server into self-contained
dist/index.js files (the SDK is bundled in; only npm deps stay external).
The hosted brain is live at https://brain.unisonlabs.ai (the default). To develop
against a different backend, point the client with UNISON_API_URL
or unison auth login --api-url <url>.
If the brain saves your agent one "wait, why did we do it this way?" — drop a ⭐ to help others find it.
Contributions welcome — see CONTRIBUTING.md and the
CHANGELOG.md. Found a vulnerability? See
SECURITY.md — please report privately, not via a public issue.
One brain, every agent. Every repo below reads from and writes to the same Unison brain — no per-tool memory silos.
| Repo | What it does |
|---|---|
| unison-brain | CLI · SDK · MCP server — the core ← you are here |
| claude-unison | Memory for Claude Code |
| cursor-unison | Memory for Cursor |
| codex-unison | Memory for OpenAI Codex CLI |
| opencode-unison | Memory for OpenCode |
| openclaw-unison | Memory for OpenClaw |
| pipecat-unison | Memory for Pipecat voice agents |
| python-sdk | Python SDK for the brain |
| install-mcp | One-command MCP installer |
| code-chunk | AST-aware code chunking |
| unison-fs | Mount the brain as a filesystem |
| backchannel | Async messaging between agents |
| Unison-evals | Open memory benchmark suite |
MIT © Unison Labs