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 single .kapi/work/store.db, 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; 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; 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 and kapi terms resolve the project's authoritative stores, both of which live as tables inside the project's single database at <project-root>/.kapi/work/store.db. The project is found by walking up the directory tree from the current directory, git-style.

Those tables are a projection of what the project commits: the terms bundle the recipe binds with defaults.terms_source and the content-memory bundle it binds with defaults.memory_source. Edit the bundle, and the store follows; delete the store, and it is rebuilt. See the project store.

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 content memory / terms store in .kapi/work/store.db.

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 \
  --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 <root>/.kapi/work/store.db	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, held in the project store's working set and committed to .kapi/state/*.jsonl by kapi commit. Approving a unit (kapi apply with kind:"review") writes that record; adding a memory pair (kapi apply with kind:"memory") 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.