Where translations & terms live

Better in a project

kapi memory and kapi terms run ad-hoc against a loose or named store, but a kapi project gives them an authoritative content memory and terms store, both inside the project's own store, that the extract/merge round-trip and term-check already share.

The translations kapi reuses and the terms it keeps consistent are kept in a small database on disk. That database can live in one of three places. A flag picks the place; with no flag, a command inside a kapi project uses the project's store, and one outside a project uses a loose file. The same three models apply to both stores; outside a project only the default filename differs (memory.db vs terms.db) and the named-store subdirectory (memory/ vs terms/).

For the stores themselves (matching, leverage, and the concept model) see Content memory and Terminology.

The three storage models

1. A loose file in the current directory

The default with no flag and no project. A kapi memory command reads and writes ./memory.db; a kapi terms command reads and writes ./terms.db. This is the ad-hoc model, useful for a quick, throwaway store you don't intend to reuse.

kapi memory import corpus.memory.json    # → ./memory.db
kapi terms import terms.json             # → ./terms.db

Point at an explicit path with --file, or write --local to be explicit about the current-directory default:

kapi memory stats --file ./build/scratch-memory.db
kapi terms stats --local

2. A named store under your config home

Pass --name <n> to use a database under your config home that persists between sessions and is reusable across directories, a content memory at ~/.config/kapi/memory/<n>.db and a terms store at ~/.config/kapi/terms/<n>.db. This is the model to reach for when a set of terms or a memory outlives any single working directory.

kapi terms import terms.json --name product-terms
kapi terms stats --name product-terms
kapi memory import corpus.memory.json --name corporate-en-fr

List what you have:

kapi memory list
kapi terms list

The config home follows KAPI_CONFIG_DIR when set, otherwise the OS user config directory, ~/.config/kapi on Linux, ~/Library/Application Support/kapi on macOS. A named store is resolved only under that config home, so on macOS there is nothing under ~/.config/kapi. kapi memory list and kapi terms list print the absolute path of every store they find. A name may not contain a path separator.

3. A project's authoritative store

When a command runs inside a kapi project, and no --name, --local, or --file flag is given, kapi memory and kapi terms use the project's authoritative stores. Both are tables in the project's context store, which sits in a workspace under your data directory, outside the checkout, so every clone of the project reads the same one. kapi finds the project by walking up the directory tree from the current directory, as git does.

Those tables are the project's own record, and git holds no copy of them. Four verbs carry them in and out (Sharing context): kapi store import reads a checkout's context files into the store, kapi context sync shares it through the project's context backend, and kapi store export carries the whole of it as one file, which is the backup this store needs. See the project store.

kapi needs no snapshot of the store in git. Keeping one is a team's choice about what a pull request should show. A team that makes it keeps the snapshot current and runs kapi store import on a fresh clone and on a runner; a team that does not backs the store up with kapi store export instead.

The store is what kapi extract pre-fills from, what kapi merge writes back to, and what kapi exec term-check enforces, so a project-mode kapi memory lookup or kapi terms lookup sees exactly the store the round-trip uses, with no flag needed. See Create your first project.

# Inside a project directory:
kapi memory import ./corporate-en-fr.memory.json  # → the project store
kapi memory stats                            # reads the project content memory
kapi terms lookup "dashboard" -s en -t fr    # reads the project terms store

An explicit --name, --local, or --file always wins, so you can target a different store even from inside a project.

How tools select a store

The tool commands that consume a store, kapi exec recycle and kapi exec term-check, follow the same precedence through their own --memory and --termstore flags:

• --memory <name|path> / --termstore <name|path>: a bare name (no separators) resolves under the config home; a value with a path separator is read as a file path.
• no flag, inside a project: the project's own content memory / terms store.

kapi exec recycle messages.json --target-lang fr --memory corporate-en-fr
kapi exec term-check messages.json --target messages_fr.json \
  --source-lang en --target-lang fr --termstore product-terms

--terms is a different flag on a different tool: the boolean gate on kapi exec dnt-check that turns term-derived do-not-translate detection on. It never names a store.

Choosing a model

Model	Selected by	Lives at	Use when
Loose file	default, --local, --file <path>	./memory.db / ./terms.db, or the path you give	a one-off or throwaway store
Named store	--name <n>	~/.config/kapi/memory/<n>.db / ~/.config/kapi/terms/<n>.db	a set of terms or a memory reused across directories
Project store	no flag, inside a kapi project	tables in the project's context store, shared by every checkout	a repository you translate repeatedly

Works with Bowrain

All three models are local to a machine or a repository. A fourth arrangement is hosted: a Bowrain server holds one workspace-level content memory and terms store shared across projects, people, and agents, and kapi push / kapi pull connect a kapi project to it. See the Bowrain documentation.

Content memory and review decisions

The project content memory is a recycle corpus: source→target pairs reused to pre-fill and leverage future translation. Review decisions are kept elsewhere. Whether a person has approved a particular target is recorded in the project store's decision record. Approving a block (a decide operation through kapi apply) writes that record; adding a memory pair (a memory operation through kapi apply) is recycle leverage and does not promote a block to reviewed.

Note on locale flags

kapi memory and kapi terms take the locale with -s/--source-locale and -t/--target-locale. The tool commands that read these stores (kapi exec recycle, kapi exec term-check) instead use the processing flags --source-lang and --target-lang, consistent with the other tools.

Next

• kapi memory and kapi terms, command references.
• Pre-translate from memory: a pipeline that uses these stores.
• Project file: the kapi.yaml recipe and discovery.