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 (.kapi/memory.db) and terms 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, and which one a command uses is decided by a flag — or, with no flag, by whether a .kapi project is in scope. The same three models apply to both stores; only the default filename differs (memory.db vs terms.db) and the named-store subdirectory (tm/ vs termbases/).

For the stores themselves — matching, leverage, and the concept model — see Content memory and Terminology; this recipe covers where those stores live and the flags that select each.

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 resolves the project's authoritative content memory at <project-root>/.kapi/memory.db, and kapi terms resolves the project terms store (the recipe's defaults.terms key, else <project-root>/.kapi/terms.db). The project is found by walking up the directory tree from the current directory, git-style.

This is the same memory.db that kapi extract pre-fills from and kapi merge writes back to, and the same terms store that 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  # → <project-root>/.kapi/memory.db
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 --terms flags:

• --memory <name|path> / --terms <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 .kapi/memory.db / project terms store.

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

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	<root>/.kapi/memory.db / project terms store	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 is not the review state

The project content memory is a recycle corpus — source→target pairs reused to pre-fill and leverage future translation. It is not where a review decision lands. Whether a person has approved or signed off a particular target is a workflow decision, recorded in the project's separate state store (.kapi-state.json, defaults.state) — the committed third artifact a project keeps alongside its content memory and terms store. Approving a unit (kapi apply with kind:"review") writes the state store; adding a memory pair (kapi apply with kind:"tm") is recycle leverage and does not promote a unit 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.