Šĥàŕîñĝ çöñţéẋţ

À þŕöĵéçţ'š çöñţéẋţ îš îţš ŕüļéš àñđ šüĝĝéšţîöñš, îţš ţéŕḿš, ṽöîçé þŕöƒîļéš àñđ çöñţéñţ ḿéḿöŕý, àñđ ţĥé ŕéçöŕđ öƒ ŵĥö àþþŕöṽéđ ŵĥàţ. Îţ ļîṽéš îñ ýöüŕ ŵöŕķšþàçé öñ ţĥîš ḿàçĥîñé, šĥàŕéđ ƃý éṽéŕý çļöñé àñđ ŵöŕķţŕéé öƒ ţĥé þŕöĵéçţ. Öñçé ýöü šĥàŕé îţ, à ŕüļé öñé þéŕšöñ ķééþš îš îñ ƒöŕçé öñ éṽéŕý ḿàçĥîñé ţĥàţ šýñçš ţĥé þŕöĵéçţ. Îñ Ķàþî Đéšķţöþ, ţĥé Šĥàŕé ţàƃ öƒ ţĥé þŕöĵéçţ'š Þŕöĵéçţ Šéţţîñĝš ñàḿéš ţĥé þļàçé àñđ šýñçš. Öñ ţĥé çöḿḿàñđ ļîñé, kapi context sync šĥàŕéš ţĥé çöñţéẋţ ŵîţĥ ţĥé ŕéšţ öƒ ţĥé ţéàḿ. kapi share ŕüñš ţĥé šàḿé šýñç ƒöŕ à þéŕšöñ, àñđ kapi share --via git öŕ kapi share --via folder <path> ŵŕîţéš ţĥé context: ƃļöçķ ƃéļöŵ ƃéƒöŕé îţš ƒîŕšţ šýñç.

Çöḿḿàñđ	Üšé îţ ţö
`kapi context sync`	ţàķé îñ ŵĥàţ ţĥé ŕéšţ öƒ ţĥé ţéàḿ ŕéçöŕđéđ, àñđ šĥàŕé ŵĥàţ ýöü ŕéçöŕđéđ
`kapi context sync --no-push`	ţàķé îñ ŵĥàţ ţĥé ŕéšţ öƒ ţĥé ţéàḿ ŕéçöŕđéđ àñđ šĥàŕé ñöţĥîñĝ, àš à çĥéçķ öŕ à ƒŕéšĥ çĥéçķöüţ đöéš
`kapi context sync --status`	šéé ŵĥéŕé ţĥé çöñţéẋţ îš šĥàŕéđ àñđ ŵĥéţĥéŕ ţĥéŕé îš àñýţĥîñĝ ţö šýñç
`kapi context sync --merged <range>`	îñ ÇÎ àƒţéŕ à ḿéŕĝé: ţàķé îñ ŵĥàţ öţĥéŕš šĥàŕéđ, çöüñţ ŵĥàţ ţĥé ḿéŕĝé ŵŕöţé àš à þéŕšöñ'š ƃàçķîñĝ, àñđ šĥàŕé ţĥé ŕéšüļţ
`kapi context sync --files-only`	ŕéŵŕîţé ţĥé þŕöĵéçţ'š ŕüļéš ƒîļéš (`AGENTS.md`, `CLAUDE.md`) ƒŕöḿ ţĥé çöñţéẋţ öñ ţĥîš ḿàçĥîñé, àñđ ñöţĥîñĝ éļšé
`kapi store export -o <file>.kpz`	ƃàçķ ţĥé çöñţéẋţ üþ, öŕ çàŕŕý îţ ţö à ḿàçĥîñé ţĥàţ çàññöţ ŕéàçĥ ţĥé šĥàŕéđ çöþý
`kapi store import <file>.kpz`	ḿéŕĝé šüçĥ à ƒîļé, ţĥé ŵàý à šýñç đöéš
`kapi store import [dir]`	ŕéàđ ţéŕḿš, ṽöîçé þŕöƒîļéš àñđ àþþŕöṽàļš ķéþţ àš ƒîļéš îñţö ţĥé þŕöĵéçţ

ķàþî çöñţéẋţ šýñç šĥàŕéš ţĥé çöñţéẋţ ţĥŕöüĝĥ ţĥé þļàçé ķàþî.ýàḿļ ñàḿéš; éẋþöŕţ àñđ îḿþöŕţ çàŕŕý ţĥé šàḿé çöñţéẋţ îñ öñé ƒîļé.

Ŵĥàţ îš šĥàŕéđ

Éṽéŕýţĥîñĝ ţĥé þŕöĵéçţ ŕéçöŕđš àƃöüţ ĥöŵ îţš çöñţéñţ îš ŵŕîţţéñ: éṽéŕý šüĝĝéšţîöñ àñđ îţš éṽîđéñçé, ţĥé đéçîšîöñš þéöþļé ḿàđé àƃöüţ ţĥéḿ, ţĥé ţéŕḿš, ţĥé ṽöîçé þŕöƒîļéš, ţĥé àþþŕöṽéđ ŵöŕđîñĝ îñ ţĥé çöñţéñţ ḿéḿöŕý, àñđ ţĥé ŕéçöŕđ öƒ ŵĥö àþþŕöṽéđ ŵĥîçĥ ţŕàñšļàţîöñ. Éàçĥ ţŕàṽéļš ŵîţĥ îţš ĥîšţöŕý, šö ţŵö ḿàçĥîñéš ţĥàţ ŕéçöŕđéđ đîƒƒéŕéñţ ţĥîñĝš ƃöţĥ ķééþ ŵĥàţ ţĥéý ŕéçöŕđéđ.

Ţĥé đŕàƒţš öƒ à ļàñĝüàĝé ŵĥöšé ƒîļéš materialize: on-converge ŵîţĥĥöļđš àŕé šĥàŕéđ ţöö, ƃéçàüšé ţĥé ŵöŕķšþàçé ķééþš ţĥéḿ üñţîļ à đéļîṽéŕý ŵŕîţéš ţĥéḿ. Ţŵö ḿàçĥîñéš ţĥàţ éđîţ öñé šüçĥ đŕàƒţ éàçĥ ķééþ ţĥéîŕ éđîţ ŵĥéñ ţĥéý çĥàñĝéđ đîƒƒéŕéñţ ƃļöçķš. Ŵĥéñ ƃöţĥ çĥàñĝéđ ţĥé šàḿé ƃļöçķ, ţĥé éđîţ ḿàđé ƒîŕšţ ĥöļđš îţ àñđ kapi status ļîšţš ţĥé öţĥéŕ àš à çöñƒļîçţ. Ķàþî Đéšķţöþ šĥöŵš éàçĥ çöñƒļîçţ öñ ţĥé þŕöĵéçţ'š ĥöḿé ŵîţĥ ƃöţĥ ŵöŕđîñĝš: ķééþ ţĥé ŵöŕđîñĝ ĥéļđ ñöŵ, ţàķé ţĥé öţĥéŕ öñé, öŕ ŵŕîţé à ñéŵ öñé. Éđîţîñĝ ţĥàţ ƃļöçķ àĝàîñ ƒŕöḿ ţĥé çöḿḿàñđ ļîñé öŕ ţĥŕöüĝĥ àñ àĝéñţ šéţţļéš îţ ţĥé šàḿé ŵàý.

Çöñţéñţ ƒîļéš ţŕàṽéļ îñ ĝîţ.

Ŵĥàţ šţàýš öñ ţĥîš ḿàçĥîñé

Ŕéđàçţîöñ ŵîţĥĥöļđš šéñšîţîṽé ṽàļüéš ƃéƒöŕé çöñţéñţ ŕéàçĥéš à ḿöđéļ öŕ à šéŕṽîçé, àñđ ķééþš ţĥé öŕîĝîñàļš îñ à ṽàüļţ öñ ţĥé ḿàçĥîñé ţĥàţ ŕéàđ ţĥéḿ (.kapi/vault/). Ţĥé ṽàüļţ îš ñéṽéŕ šĥàŕéđ àñđ ñéṽéŕ éẋþöŕţéđ, àñđ ñö ƒļàĝ çĥàñĝéš ţĥàţ. Ŵĥéñ à þŕöĵéçţ ḿöṽéš ţö àñöţĥéŕ ḿàçĥîñé, ţĥé þļàçéĥöļđéŕš çöḿé ŵîţĥ îţ àñđ ţĥé öŕîĝîñàļš šţàý ƃéĥîñđ. Ţĥé đŕàƒţš öƒ à ļàñĝüàĝé ŵàîţîñĝ ƒöŕ ŕéṽîéŵ ţŕàṽéļ ŵîţĥ ţĥéîŕ ŵîţĥĥéļđ ṽàļüéš ŕéþļàçéđ, àñđ ŕéàđ ŵĥöļé öñļý öñ ţĥé ḿàçĥîñé ţĥàţ ŵîţĥĥéļđ ţĥéḿ.

Ŕüļéš ýöü ŵîđéñéđ ţö éṽéŕý þŕöĵéçţ ţŕàṽéļ ŵîţĥ ţĥé þŕöĵéçţ ţĥàţ đéçîđéđ ţĥéḿ. À ḿàçĥîñé ţĥàţ þüļļš ţĥé þŕöĵéçţ, öŕ ŕéàđš îţš éẋþöŕţ, ĥöļđš ţĥéḿ îñ îţš öŵñ ŵöŕķšþàçé àñđ àþþļîéš ţĥéḿ ţö éṽéŕý þŕöĵéçţ ţĥéŕé. Ţĥé đéŕîṽéđ šţöŕéš àñđ çàçĥéš üñđéŕ .kapi/work/ àŕé ŕéƃüîļţ ƒŕöḿ ýöüŕ çöñţéñţ ƒîļéš.

Ñàḿé ţĥé þļàçé ţĥé çöñţéẋţ îš šĥàŕéđ îñ kapi.yaml, ŵĥéŕé éṽéŕý çĥéçķöüţ ŕéàđš îţ:

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

Ƃàçķéñđ	Ķééþš ţĥé çöñţéẋţ îñ	Ŕéçîþé ƒîéļđš	Àççéšš
`local`	ţĥîš ḿàçĥîñé öñļý
`git`	à ŕéƒ öƒ ţĥé þŕöĵéçţ'š öŵñ ŕéþöšîţöŕý	`ref` (đéƒàüļţ `refs/kapi/context`), `remote` (đéƒàüļţ `origin`)	ţĥé ŕéþöšîţöŕý'š öŵñ: ŵĥöéṽéŕ çàñ þüšĥ à ƃŕàñçĥ çàñ þüšĥ ţĥé ŕéƒ
`file`	à đîŕéçţöŕý, šüçĥ àš à ḿöüñţéđ ţéàḿ šĥàŕé	`path`	ţĥé ƒîļéšýšţéḿ'š
`s3`	àñ Š3-çöḿþàţîƃļé ƃüçķéţ	`bucket`, `prefix`, `region`, `endpoint`	ţĥé šţàñđàŕđ ÀŴŠ éñṽîŕöñḿéñţ, šĥàŕéđ çöñƒîĝüŕàţîöñ àñđ þŕöƒîļé

Çŕéđéñţîàļš ñéṽéŕ ĝö îñ ţĥé ŕéçîþé. Ţĥéñ šýñç ƃéƒöŕé ýöü ŵöŕķ àñđ ŵĥéñ ýöü àŕé đöñé:

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).

À šýñç ƒîŕšţ ŕéàđš ŵĥàţ öţĥéŕš šĥàŕéđ àñđ ḿéŕĝéš îţ ĥéŕé, ţĥéñ šĥàŕéš ŵĥàţ ţĥîš ḿàçĥîñé ŕéçöŕđéđ, àñđ ţĥéñ ŕéŵŕîţéš ţĥé þŕöĵéçţ'š ŕüļéš ƒîļéš šö ţĥé ñéẋţ àĝéñţ šéššîöñ ŕéàđš ŵĥàţ ţĥé ţéàḿ đéçîđéđ. Ŕüññîñĝ îţ ţŵîçé çĥàñĝéš ñöţĥîñĝ. Éàçĥ ḿàçĥîñé öñļý àđđš ƒîļéš öƒ îţš öŵñ ţö ţĥé šĥàŕéđ çöþý, šö ţŵö þéöþļé šýñçîñĝ àţ öñçé ƃöţĥ šüççééđ.

kapi context sync --status šàýš ŵĥéŕé ţĥé çöñţéẋţ îš šĥàŕéđ àñđ ĥöŵ ƒàŕ àþàŕţ ţĥîš ḿàçĥîñé àñđ ţĥé šĥàŕéđ çöþý ŵéŕé àţ ţĥé ļàšţ šýñç, ŵîţĥöüţ çöñţàçţîñĝ îţ:

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> àñđ ţĥé çöñţéẋţ àñ àššîšţàñţ ŕéàđš éñđ ŵîţĥ ţĥé šàḿé Context: ļîñé, šö ýöü ķñöŵ ŵĥéñ ţĥéŕé îš šöḿéţĥîñĝ ţö šýñç.

Ķééþîñĝ à ŕüļé, öŕ îḿþöŕţîñĝ à ṽöîçé öŕ ţéŕḿš, àļšö ŵŕîţéš ţö ţĥé þŕöĵéçţ'š šţöŕéš, àñđ ţĥöšé ŵŕîţéš ţŕàṽéļ ŵîţĥ ţĥé çöñţéẋţ. Ŵĥéñ ţĥé çöüñţ îñçļüđéš ţĥéḿ, ţĥé ļîñé šàýš ĥöŵ ḿàñý öƒ ţĥé öþéŕàţîöñš kapi context log ļîšţš, àš îñ Context: 9 to push (2 in kapi context log, 7 store writes). Ƃéƒöŕé ţĥé ƒîŕšţ šýñç ñöţĥîñĝ ĥàš ƃééñ ŕéàđ ƒŕöḿ ţĥé šĥàŕéđ çöþý, šö ţĥé ļîñé šàýš ţĥàţ ŵĥàţ ŵàîţš ţö þüļļ îš ñöţ ķñöŵñ ýéţ.

À çļöñé ƒéţçĥéš ƃŕàñçĥéš àñđ ţàĝš àñđ ļéàṽéš ţĥé çöñţéẋţ ŕéƒ àļöñé; kapi context sync ƒéţçĥéš îţ. À þüļļ ŕéǫüéšţ ƒŕöḿ à ƒöŕķ çàñ ŕéàđ ţĥé šĥàŕéđ çöñţéẋţ àñđ çàññöţ šĥàŕé ƃàçķ ţö îţ.

Ŵĥéñ ţĥé šĥàŕéđ çöþý çàññöţ ƃé ŕéàçĥéđ, ñöţĥîñĝ çĥàñĝéš ĥéŕé àñđ ţĥé çöḿḿàñđ éẋîţš ŵîţĥ šţàţüš 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

Ƒŕöḿ ţĥé ƃŕöŵšéŕ

Ţĥé þļàýĝŕöüñđ àñđ ţĥé ļàƃš šĥàŕé à þŕöĵéçţ'š çöñţéẋţ ţĥŕöüĝĥ à ƒöļđéŕ öñ ýöüŕ çöḿþüţéŕ. Îñ à ƃŕöŵšéŕ ţĥàţ çàñ öþéñ öñé (Çĥŕöḿé àñđ Éđĝé), Šýñç çöñţéẋţ ŵîţĥ à ƒöļđéŕ îñ ţĥé ƒîļéš þàñéļ ŕéàđš ƒŕöḿ ţĥé ƒöļđéŕ ýöü çĥööšé àñđ ŵŕîţéš ŵĥàţ ţĥé þàĝé ŕéçöŕđéđ. Ţĥé ƒöļđéŕ ĥöļđš ŵĥàţ à file ƃàçķéñđ ĥöļđš, šö ķàþî öñ ţĥé šàḿé çöḿþüţéŕ šĥàŕéš ţĥé çöñţéẋţ ŵîţĥ ţĥé þàĝé ŵĥéñ ţĥé þŕöĵéçţ'š context: ñàḿéš ţĥàţ ƒöļđéŕ àš îţš path.

Ŕéàđîñĝ çöñţéẋţ îñ

À çĥéçķöüţ çàñ çàŕŕý çöñţéẋţ àš ƒîļéš: ţéŕḿš, ṽöîçé þŕöƒîļéš, çöñţéñţ ḿéḿöŕý àñđ àþþŕöṽàļš üñđéŕ .kapi/. Ŕéàđ ţĥéḿ îñţö ţĥé þŕöĵéçţ ŵîţĥ:

kapi store import

Read .kapi into the project store:
  1 concept

Ŵĥàţ îţ ŕéàđš îš îñ ƒöŕçé ƒöŕ éṽéŕý çĥéçķöüţ öƒ ţĥîš þŕöĵéçţ öñ ţĥîš ḿàçĥîñé, àñđ ƒöŕ éṽéŕýöñé éļšé àƒţéŕ ţĥé ñéẋţ kapi context sync. Öñļý à þéŕšöñ ŕéàđš çöñţéẋţ îñ. ķàþî ŕéƒüšéš àñ àššîšţàñţ àñđ ñàḿéš ţĥé çöḿḿàñđ ƒöŕ ýöü ţö ŕüñ:

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

Ŵîţĥ ñö þàţĥ îţ ŕéàđš ţĥé þŕöĵéçţ'š öŵñ .kapi/ đîŕéçţöŕý. Ñàḿé à đîŕéçţöŕý ţö ŕéàđ àñöţĥéŕ çĥéçķöüţ'š çöñţéẋţ îñšţéàđ, ŵĥéñ ýöü ƃŕîñĝ àñ éẋîšţîñĝ þŕöĵéçţ'š çöñţéẋţ àçŕöšš:

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

Éàçĥ ƒîļé ŕéàđ îš ŕéçöŕđéđ ŵîţĥ îţš đîĝéšţ, šö kapi context log šàýš ŵĥîçĥ ƒîļéš ţĥé çöñţéẋţ çàḿé ƒŕöḿ àñđ ŵĥéñ. Ŕéàđîñĝ ţĥé šàḿé ƒîļéš àĝàîñ çĥàñĝéš ñöţĥîñĝ, ƃéçàüšé éṽéŕýţĥîñĝ îš ḿàţçĥéđ ƃý îđéñţîţý, àñđ à ƒîļé ŵĥöšé ƃýţéš ĥàṽé ñöţ çĥàñĝéđ šîñçé ţĥîš çĥéçķöüţ ŕéàđ îţ îš šķîþþéđ. --force ŕéàđš îţ àñýŵàý.

Ḿééţîñĝ à þŕöĵéçţ ŵĥöšé çöñţéẋţ îš šţîļļ îñ ƒîļéš

Ŵĥéñ à çĥéçķöüţ çàŕŕîéš çöñţéẋţ ƒîļéš àñđ îţš þŕöĵéçţ ĥàš ñö çöñţéẋţ ýéţ, çöḿḿàñđš ţĥàţ öþéñ ţĥé þŕöĵéçţ þŕîñţ à ñöţîçé ţö šţàñđàŕđ éŕŕöŕ:

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 ļîšţš ţĥé šàḿé ļîñé àš à çöñƒîĝüŕàţîöñ ŵàŕñîñĝ, ŵĥîçĥ ñéṽéŕ çĥàñĝéš ţĥé šçöŕé, ţĥé ĝàţé öŕ ţĥé ṽéŕđîçţ. Ķàþî Đéšķţöþ šĥöŵš îţ öñ ţĥé þŕöĵéçţ àñđ öñ ţĥé ŵöŕķšþàçé ĥöḿé, àñđ àñ àššîšţàñţ ŕéàđîñĝ ţĥé þŕöĵéçţ'š çöñţéẋţ šééš îţ ţöö àñđ çàñ ţéļļ ýöü ŵĥàţ ţö ŕüñ. Ţĥé ñöţîçé šţöþš öñçé ţĥé þŕöĵéçţ ĥöļđš àñý çöñţéẋţ.

Çàŕŕýîñĝ çöñţéẋţ îñ öñé ƒîļé

kapi store export -o context.kpz

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

Ţĥé ƒîļé ĥöļđš ţĥé þŕöĵéçţ'š ŵĥöļé çöñţéẋţ ŵîţĥ îţš ĥîšţöŕý, àñđ à çĥéçķþöîñţ šö ŕéàđîñĝ îţ ƃàçķ îš ƒàšţ. Îţ îš ţĥé ƃàçķüþ, àñđ ţĥé ŵàý ţö çàŕŕý à þŕöĵéçţ'š çöñţéẋţ ţö à ḿàçĥîñé ţĥàţ çàññöţ ŕéàçĥ ţĥé šĥàŕéđ çöþý.

kapi store import context.kpz

Îḿþöŕţ ḿéŕĝéš ţĥé ƒîļé ţĥé ŵàý à šýñç ḿéŕĝéš ţĥé šĥàŕéđ çöþý: éṽéŕýţĥîñĝ îţ çàŕŕîéš ţĥàţ ţĥîš þŕöĵéçţ đöéš ñöţ ĥöļđ îš àđđéđ, àñđ ŕéàđîñĝ ţĥé šàḿé ƒîļé ţŵîçé çĥàñĝéš ñöţĥîñĝ ḿöŕé. À ƒîļé ĥöļđš öñé þŕöĵéçţ'š çöñţéẋţ, àñđ îḿþöŕţîñĝ îţ îñţö à çĥéçķöüţ öƒ àñöţĥéŕ þŕöĵéçţ îš ŕéƒüšéđ ŵîţĥ ƃöţĥ ñàḿéš.

Ŵĥîçĥ öñé ţö üšé

Ŵöŕķîñĝ ŵîţĥ öţĥéŕ þéöþļé, öŕ öñ ḿöŕé ţĥàñ öñé ḿàçĥîñé: ñàḿé à ƃàçķéñđ îñ kapi.yaml àñđ ŕüñ kapi context sync.
À ƃàçķüþ ƃéƒöŕé à ŕîšķý çĥàñĝé, öŕ à ḿàçĥîñé ţĥé šĥàŕéđ çöþý đöéš ñöţ ŕéàçĥ: kapi store export, ţĥéñ kapi store import ţĥé ƒîļé.
Ƃŕîñĝîñĝ àñ öļđ þŕöĵéçţ îñ, öŕ à çļöñé ţĥàţ àŕŕîṽéđ ŵîţĥ çöñţéẋţ ƒîļéš: kapi store import ţĥé đîŕéçţöŕý.

Ŕéļàţéđ

Çöñţéẋţ: ŵĥàţ ţĥé çöñţéẋţ ĥöļđš, àñđ ŵĥéŕé éàçĥ þàŕţ öƒ îţ àþþļîéš.
Ţĥé þŕöĵéçţ šţöŕé: ŵĥéŕé ţĥé çöñţéẋţ îš ķéþţ öñ ţĥîš ḿàçĥîñé, àñđ ĥöŵ ţö ŕéƃüîļđ îţ.
Çöñṽéŕĝéñçé îñ ÇÎ: šýñçîñĝ çöñţéẋţ àŕöüñđ à ÇÎ ĵöƃ.
Ŕéđàçţîöñ: ŵĥàţ ţĥé ṽàüļţ ĥöļđš àñđ ŵĥý îţ šţàýš ŵĥéŕé îţ îš.
kapi context sync, kapi store export àñđ kapi store import: éàçĥ çöḿḿàñđ'š ƒļàĝš àñđ öüţþüţ.

Ŵĥàţ îš šĥàŕéđ​

Ŵĥàţ šţàýš öñ ţĥîš ḿàçĥîñé​