Configuration

PRIMA Memory

PRIMA Memory has no settings file. It reads a small number of environment variables from the env block of its MCP server entry, which the AI Business OS installer writes for you. A standard install needs no changes. Use this page when you want to move a folder or add a safety check.

Where the Settings Live

Each variable sits in the env block of the PRIMA Memory server entry in your workspace’s MCP configuration. This example sets the host mode, as the installer does, and adds a workspace check.

"env": {
  "PRIMA_EXPECTED_HOST": "claude-code",
  "PRIMA_EXPECTED_WORKSPACE": "/Users/you/Example Consulting"
}

PRIMA Memory reads the variables once, when it starts, so restart Claude Code after you change any of them. PRIMA Memory treats a variable as not set when its value is empty, contains only spaces, or contains the characters ${.

PRIMA Memory Variables

Variable	Effect	Default
`PRIMA_EXPECTED_HOST`	Holds PRIMA Memory to your Claude Code conversations when set to `claude-code`. The server refuses to start if the value is one it does not accept, or if `PRIMA_SESSIONS_DIR` points anywhere other than the Claude Code store	The installer sets `claude-code`. Leave it as it is
`PRIMA_EXPECTED_WORKSPACE`	An absolute workspace path. The server refuses to start if the workspace it resolves differs from this path, ignoring capital letters and trailing slashes	Not set, so there is no check
`PRIMA_WORKSPACE_DIR`	The workspace root. PRIMA Memory uses it to choose which Claude Code conversations to read, to place the index and to find the shared project log	The folder the server started in
`PRIMA_DB_DIR`	The folder that holds `index.db` and the `extracts/` folder	`<workspace>/.prima-memory`
`PRIMA_STATE_LOG_DIR`	The shared project log folder, normally `<workspace>/.claude/state/sessions`	Found automatically
`PRIMA_SESSIONS_DIR`	The conversation store to read. Leave it unset. If you do set it, use the exact Claude Code store path, written as `<home>/.claude/projects` with no trailing slash	Not set
`PRIMA_VSCODE_TRANSCRIPTS_DIR`	The VS Code `workspaceStorage` folder to read Copilot Chat transcripts from	The standard VS Code location for your operating system
`PRIMA_CODEX_SESSIONS_DIR`	The Codex sessions folder	`~/.codex/sessions`

You might point PRIMA_VSCODE_TRANSCRIPTS_DIR or PRIMA_CODEX_SESSIONS_DIR at a folder that does not exist. PRIMA Memory then treats that source as not installed and does not fall back to the standard location.

Variables PRIMA Memory Reads From Elsewhere

You do not normally set these, but they affect PRIMA Memory when present.

Variable	Effect
`CLAUDE_PROJECT_DIR`	When the host provides it, one of the places PRIMA Memory looks for the shared project log
`APPDATA`	Used on Windows to find the VS Code folder, with `<home>\AppData\Roaming` as the fallback
`HF_TOKEN`, `HF_ACCESS_TOKEN`	Read by the embedding library, which sends the value to Hugging Face as an access token when it downloads the model (see Privacy and Your Data). PRIMA Memory needs neither
`PATH`, `NODE_PATH`	Set by the `start.sh` launcher, described below
`VERIFY_SKIP_MODEL`	Set to `1` to make the developer check `npm run verify:universal` skip its live embedding test

How PRIMA Memory Chooses Its Host Mode

The installer sets PRIMA_EXPECTED_HOST to claude-code, and with that setting PRIMA Memory always reads the Claude Code conversations for your workspace. Leave PRIMA_EXPECTED_HOST and PRIMA_SESSIONS_DIR as the installer left them. The startup log names the mode and the paths in use, so you can check what the server chose.

PRIMA Memory takes the workspace from PRIMA_WORKSPACE_DIR when it has a value, and otherwise from the folder the server started in.

Safety Checks

PRIMA_EXPECTED_WORKSPACE and PRIMA_EXPECTED_HOST turn two silent mistakes into a refusal to start. Without them, a server that starts in the wrong folder creates a fresh, empty index there and returns no history, with no error. With them, the server checks what it resolved before it answers any request. If anything differs, it stops and states the reason.

[prima-memory] FATAL: workspace mismatch — PRIMA_EXPECTED_WORKSPACE is "/Users/you/Example Consulting" but this server resolved "/Users/you" (from process.cwd()). Refusing to serve: continuing would read and write the wrong workspace's index at "/Users/you/.prima-memory/index.db".
[prima-memory] Not starting. Fix the paths in this workspace's .mcp.json env block, or unset PRIMA_EXPECTED_WORKSPACE / PRIMA_EXPECTED_HOST to allow auto-detection.

To add the workspace check, set PRIMA_EXPECTED_WORKSPACE to the absolute path of your workspace and restart Claude Code.

Fixed Behaviour

These values are part of the code and have no setting.

Behaviour	Value
Time spent updating the index before each search	Up to 20 seconds
Text embedded from each exchange	The first 2,000 characters
Lowest similarity a semantic match needs	0.3 on a scale of 0 to 1
Embedding model	all-MiniLM-L6-v2, quantised Xenova build, 384 dimensions
Size that makes a session substantial enough for an extract	50 messages, 10 files changed or 30 minutes
Characters per message in `get_session_details`	2,000, 5,000 or unlimited, by detail level
Default number of results	5

The Launcher Script

PRIMA Memory includes start.sh, a bash script that can start the server. The script follows five rules.

It leaves the working folder unchanged, because the server takes its workspace from the folder it started in.
It resolves its own folder to an absolute path, so it works when called through a relative path.
It uses the first node on the existing PATH. Only when it finds none does it add /opt/homebrew/bin and /usr/local/bin and look again.
It sets NODE_PATH to the server’s own node_modules folder.
It starts dist/index.js with that node, passing on any arguments.

With no node anywhere, the script prints an error naming the folders it checked and exits with status 127. The script needs bash, and PRIMA Memory has no Windows launcher.