Troubleshooting

Most PRIMA Memory problems show up in one of two places. One is a warning at the top of a search result. The other is the log the server writes when Claude Code starts it, and this page lists the problems by what you see.

Reading the Startup Log

PRIMA Memory writes its diagnostic lines to standard error, and Claude Code may keep them in its MCP logs. Most lines begin with [prima-memory]. A healthy start in Claude Code mode includes lines like these, and the example leaves out a few others.

[prima-memory] startup self-check — host: claude-code, platform: darwin
[prima-memory] diag: process.cwd() = "/Users/you/Example Consulting"
[prima-memory] diag: host env = PRIMA_EXPECTED_HOST
[prima-memory] transcripts: 912 file(s) at "/Users/you/.claude/projects"
[prima-memory] shared session log (solo mode): 37 entry file(s) at "/Users/you/Example Consulting/.claude/state/sessions"
[prima-memory] index database: "/Users/you/Example Consulting/.prima-memory/index.db"
[prima-memory] vector store: OK
[prima-memory] semantic coverage complete: 140 session file(s) embedded.

Check three things in the log. The host should read claude-code and the working folder should be your workspace. The index database should sit inside that same workspace.

The transcripts line counts every conversation file under ~/.claude/projects, across all your workspaces. It is therefore normally larger than the number of files PRIMA Memory searches for this workspace.

When you cannot reach the log, ask Claude to run get_index_status. Any reply shows that the server is running and how much of your history it can see.

Claude Says It Has No PRIMA Memory Tools

The server did not start, or Claude Code has not loaded it.

1. Restart Claude Code in the workspace, since both the install and the update steps end with a restart.
2. Ask Claude to run get_index_status again in the new session and show you the reply.
3. If the tools are still missing, look in the startup log for a line beginning FATAL and use the matching row in the next section.
4. If the log has no PRIMA Memory lines at all, check that the AI Business OS installer finished without errors. If it did not, see Getting Help.

The Server Refuses to Start

Log line begins	Cause	Fix
FATAL: workspace mismatch	PRIMA_EXPECTED_WORKSPACE names a different folder from the one the server started in	Start Claude Code from the workspace folder, or correct the path in the variable
FATAL: host mismatch	PRIMA_EXPECTED_HOST holds a value the server does not accept, or PRIMA_SESSIONS_DIR points anywhere other than the Claude Code store	Set PRIMA_EXPECTED_HOST to claude-code and remove PRIMA_SESSIONS_DIR
start.sh: no `node` found	Node.js is not installed, or not where the launcher looks	Install Node.js 22.5 or later, then restart Claude Code
FATAL startup failure, FATAL uncaught exception or FATAL unhandled rejection	An unexpected error stopped the server	Note the lines that follow and contact support through Getting Help

Configuration explains both PRIMA_EXPECTED_ variables.

Searches Return No History

Every search may come back empty in a workspace where you know you have worked. PRIMA Memory may then be reading the wrong place.

1. Ask Claude to run get_index_status and look at the number of session files on disk.
2. If the number is zero, check the startup log for the working folder and the host mode.
3. If the working folder is not your workspace, the server started in another folder and created an empty index there. Set PRIMA_EXPECTED_WORKSPACE so this mistake stops the server in future, then restart Claude Code from the workspace.
4. If the startup log names any host mode other than Claude Code, set PRIMA_EXPECTED_HOST to claude-code and restart Claude Code.
5. Look for the warning No session directory found for workspace, which means Claude Code has not yet saved a conversation for this workspace path.

A brand-new workspace has little or no history, so empty results are normal at first.

Results Say Some Files Are Not Yet in the Semantic Index

The warning reads N of M session files are not yet in the semantic index. PRIMA Memory updates the index for up to 20 seconds before each search. A long history therefore takes several searches to cover, although keyword search already covers those files. To index everything at once, run rebuild_index.

A startup log line beginning semantic coverage incomplete reports the same gap.

Semantic Search Fails and Results Are Keyword-Only

The warning reads Semantic search failed (...) — results below are keyword-only. The most common cause is a model download that failed. That happens, for example, when the computer is offline the first time a semantic search runs.

1. Check that the computer can reach the internet, for example by opening a website.
2. Restart Claude Code, because the server does not try to load the model again until it restarts.
3. Ask Claude to run rebuild_index with confirm set to true once Claude Code is back.

The rebuild matters. During the failed attempt PRIMA Memory marked the conversation files it tried to embed as done. Later searches skip them until a rebuild clears that record.

Note

After a failed download get_index_status can count every file as embedded while its exchange counts read (index empty), so rely on the exchange counts and rebuild the index.

Some Text Failed to Embed

The warning reads N exchange(s) failed to embed during sync. The server log names the source, the session, the file and the message lengths for each failure. A failure here often has the same cause as a failed semantic search. Follow the steps in the section above.

Searches Are Slow

Your first searches after you install PRIMA Memory can take up to 20 seconds each while PRIMA Memory embeds new conversations, and so can searches after a long break. The log line sync paused after 20s with N file(s) still to index confirms the cause, and running rebuild_index once moves that work into the background. A keyword search (mode: "keyword") never waits for the index.

A Session Found by Search Will Not Open

get_session_details opens Claude Code conversations from the current workspace and entries in the shared project log. It cannot open sessions labelled [VS Code] or [Codex], and it cannot open a conversation whose file you have deleted. Ask Claude to answer from the search result instead, or open the original tool.

A Rebuild Seems Stuck

Ask Claude to run get_index_status and compare the progress figure over a few minutes. The rebuild pauses whenever another PRIMA Memory tool call is running, so a busy session slows it down. If Claude Code closed during the job, the job resumes when the server next starts. The startup log then records a line beginning resuming index rebuild.

The Index Was Recreated After an Update

The log line found a 2.4.x index built on the sqlite-vec extension — recreated it means you updated from version 2.4 or earlier. Those versions stored vectors in a format the current version cannot read. PRIMA Memory therefore deleted the old index file and started a new one, leaving your conversations untouched. Run rebuild_index to fill the new index straight away.

The Vector Store Reports a Fault

The log line FAULT: vector store unusable means PRIMA Memory could not open its index database. The server keeps running and keyword search still works.

1. Close Claude Code in the workspace so the server stops and releases the files.
2. Delete the index.db, index.db-wal and index.db-shm files from the .prima-memory/ folder, leaving the extracts/ folder in place.
3. Start Claude Code again in the workspace, then ask Claude to run rebuild_index.

Windows

PRIMA Memory is built and tested on macOS, and Windows has no direct support. It may run through WSL or Git Bash. The start.sh launcher needs bash, and PRIMA Memory has no Windows launcher. PRIMA Memory finds a workspace’s conversations by converting its path into a folder name. Nobody has yet checked that conversion against the folder names Claude Code writes on Windows.

Still Stuck

Getting Help lists the ways to get support. Include the startup log lines that begin [prima-memory] and the reply from get_index_status. Leave out any conversation text you would not want to share.