Sharing context

A project's context is its rules and suggestions, its terms, voice profiles and content memory, and the record of who approved what. It lives in your workspace on this machine, shared by every clone and worktree of the project. Once you share it, a rule one person keeps is in force on every machine that syncs the project. In Kapi Desktop, the Share tab of the project's Project Settings names the place and syncs. On the command line, kapi context sync shares the context with the rest of the team. kapi share runs the same sync for a person, and kapi share --via git or kapi share --via folder <path> writes the context: block below before its first sync.

Command	Use it to
kapi context sync	take in what the rest of the team recorded, and share what you recorded
kapi context sync --no-push	take in what the rest of the team recorded and share nothing, as a check or a fresh checkout does
kapi context sync --status	see where the context is shared and whether there is anything to sync
kapi context sync --merged <range>	in CI after a merge: take in what others shared, count what the merge wrote as a person's backing, and share the result
kapi context sync --files-only	rewrite the project's rules files (AGENTS.md, CLAUDE.md) from the context on this machine, and nothing else
kapi store export -o <file>.kpz	back the context up, or carry it to a machine that cannot reach the shared copy
kapi store import <file>.kpz	merge such a file, the way a sync does
kapi store import [dir]	read terms, voice profiles and approvals kept as files into the project

kapi context sync shares the context through the place kapi.yaml names; export and import carry the same context in one file.

What is shared

Everything the project records about how its content is written: every suggestion and its evidence, the decisions people made about them, the terms, the voice profiles, the approved wording in the content memory, and the record of who approved which translation. Each travels with its history, so two machines that recorded different things both keep what they recorded.

The drafts of a language whose files materialize: on-converge withholds are shared too, because the workspace keeps them until a delivery writes them. Two machines that edit one such draft each keep their edit when they changed different blocks. When both changed the same block, the edit made first holds it and kapi status lists the other as a conflict. Kapi Desktop shows each conflict on the project's home with both wordings: keep the wording held now, take the other one, or write a new one. Editing that block again from the command line or through an agent settles it the same way.

Content files travel in git.

What stays on this machine

Redaction withholds sensitive values before content reaches a model or a service, and keeps the originals in a vault on the machine that read them (.kapi/vault/). The vault is never shared and never exported, and no flag changes that. When a project moves to another machine, the placeholders come with it and the originals stay behind. The drafts of a language waiting for review travel with their withheld values replaced, and read whole only on the machine that withheld them.

Rules you widened to every project travel with the project that decided them. A machine that pulls the project, or reads its export, holds them in its own workspace and applies them to every project there. The derived stores and caches under .kapi/work/ are rebuilt from your content files.

Sharing context through a backend

Name the place the context is shared in kapi.yaml, where every checkout reads it:

kapi.yaml

context:
  backend: git                  # local (the default), file, git or s3
  ref: refs/kapi/context        # git: a ref in this repository, outside every branch

Backend	Keeps the context in	Recipe fields	Access
local	this machine only
git	a ref of the project's own repository	ref (default refs/kapi/context), remote (default origin)	the repository's own: whoever can push a branch can push the ref
file	a directory, such as a mounted team share	path	the filesystem's
s3	an S3-compatible bucket	bucket, prefix, region, endpoint	the standard AWS environment, shared configuration and profile

Credentials never go in the recipe. Then sync before you work and when you are done:

kapi context sync

Pulled 3 operations from git origin refs/kapi/context in 0.1s.
Context: 2 to push, 0 to pull (as of 2026-09-26 10:03).
Pushed 2 operations to git origin refs/kapi/context in 0.2s.
Context: 0 to push, 0 to pull (as of 2026-09-26 10:03).

A sync first reads what others shared and merges it here, then shares what this machine recorded, and then rewrites the project's rules files so the next agent session reads what the team decided. Running it twice changes nothing. Each machine only adds files of its own to the shared copy, so two people syncing at once both succeed.

kapi context sync --status says where the context is shared and how far apart this machine and the shared copy were at the last sync, without contacting it:

Context backend: git (origin refs/kapi/context), declared in the recipe.
Context: 2 to push, 0 to pull (as of 2026-09-26 10:03).

kapi status, kapi context <path> and the context an assistant reads end with the same Context: line, so you know when there is something to sync.

Keeping a rule, or importing a voice or terms, also writes to the project's stores, and those writes travel with the context. When the count includes them, the line says how many of the operations kapi context log lists, as in Context: 9 to push (2 in kapi context log, 7 store writes). Before the first sync nothing has been read from the shared copy, so the line says that what waits to pull is not known yet.

A clone fetches branches and tags and leaves the context ref alone; kapi context sync fetches it. A pull request from a fork can read the shared context and cannot share back to it.

When the shared copy cannot be reached, nothing changes here and the command exits with status 5:

Error: workspace: the context backend could not be reached: git fetch origin refs/kapi/context: ...
Nothing changed here at the pull. 1 operation waits to be shared; run `kapi context sync` again when the backend is reachable

From the browser

The playground and the labs share a project's context through a folder on your computer. In a browser that can open one (Chrome and Edge), Sync context with a folder in the files panel reads from the folder you choose and writes what the page recorded. The folder holds what a file backend holds, so kapi on the same computer shares the context with the page when the project's context: names that folder as its path.

Reading context in

A checkout can carry context as files: terms, voice profiles, content memory and approvals under .kapi/. Read them into the project with:

kapi store import

Read .kapi into the project store:
  1 concept

What it reads is in force for every checkout of this project on this machine, and for everyone else after the next kapi context sync. Only a person reads context in. kapi refuses an assistant and names the command for you to run:

Error: agent claude-code/s4980103f5148 may not import context: reading a
checkout's context files puts them in force for everyone working in this
project, which a person decides: ask the person working here to run
`kapi store import`: refused by the context policy

With no path it reads the project's own .kapi/ directory. Name a directory to read another checkout's context instead, when you bring an existing project's context across:

kapi store import ../old-project/.kapi

Each file read is recorded with its digest, so kapi context log says which files the context came from and when. Reading the same files again changes nothing, because everything is matched by identity, and a file whose bytes have not changed since this checkout read it is skipped. --force reads it anyway.

Meeting a project whose context is still in files

When a checkout carries context files and its project has no context yet, commands that open the project print a notice to standard error:

note: this project carries context files (.kapi/memory/memory.json, .kapi/terms.json) and its store holds no context yet. They are read by `kapi store import`, and until then nothing in them is in force

kapi check lists the same line as a configuration warning, which never changes the score, the gate or the verdict. Kapi Desktop shows it on the project and on the workspace home, and an assistant reading the project's context sees it too and can tell you what to run. The notice stops once the project holds any context.

Carrying context in one file

kapi store export -o context.kpz

Wrote 3 context operations to context.kpz (8.2 KiB).

The file holds the project's whole context with its history, and a checkpoint so reading it back is fast. It is the backup, and the way to carry a project's context to a machine that cannot reach the shared copy.

kapi store import context.kpz

Import merges the file the way a sync merges the shared copy: everything it carries that this project does not hold is added, and reading the same file twice changes nothing more. A file holds one project's context, and importing it into a checkout of another project is refused with both names.

Which one to use

• Working with other people, or on more than one machine: name a backend in kapi.yaml and run kapi context sync.
• A backup before a risky change, or a machine the shared copy does not reach: kapi store export, then kapi store import the file.
• Bringing an old project in, or a clone that arrived with context files: kapi store import the directory.

Related

• Context: what the context holds, and where each part of it applies.
• The project store: where the context is kept on this machine, and how to rebuild it.
• Convergence in CI: syncing context around a CI job.
• Redaction: what the vault holds and why it stays where it is.
• kapi context sync, kapi store export and kapi store import: each command's flags and output.