Rebuilding the Index

PRIMA Memory keeps its semantic index up to date by itself, a little before each search. A rebuild clears the index and embeds every conversation file again in one background job. You need one when the index falls well behind your history or when you want it to forget conversations you have deleted.

When to Rebuild

• Search results carry the warning that some session files are not yet in the semantic index.
• get_index_status reports that coverage is incomplete.
• Search results seem stale or miss sessions you know exist.
• You have just installed PRIMA Memory in a workspace with a long history.
• A semantic search failed because the model could not download, and you have since restarted Claude Code (see Troubleshooting).
• You deleted conversation files and want their copied text out of the index.

You do not need to rebuild on a schedule. Before each semantic or combined search PRIMA Memory embeds new and changed conversations for up to 20 seconds, which keeps a normal workspace covered.

Check Coverage First

Ask Claude to run get_index_status. The tool needs no settings and returns a report like this one.

Semantic index status:

Session files on disk: 140
Embedded: 128
Not yet embedded: 12

Exchanges by source:
  transcript: 3954 indexed / 3954 embedded
  state-log: 37 indexed / 37 embedded
Total: 3991 exchanges from 128 files

Rebuild job: none running

Coverage incomplete — 12 session file(s) are keyword-only. Run rebuild_index to embed them.

Line	Meaning
Session files on disk	Conversation files PRIMA Memory can read from every source
Embedded	Files PRIMA Memory has finished indexing
Not yet embedded	Files that semantic search cannot see yet, although keyword search can
Exchanges by source	For each source, the exchanges stored in the index and how many of them have a vector
Rebuild job	Whether a rebuild is running, with its progress and start time
Last line	A one-line verdict on whether semantic search covers your whole history

Start a Rebuild

1. Ask Claude to run the PRIMA Memory rebuild_index tool with confirm set to true.
2. Read the reply, which states how many session files the job has queued.
3. Carry on working while the job runs in the background.

Any value of confirm other than true cancels the request, and nothing changes.

Index rebuild started in the background: 140 session file(s) queued, newest first.

Semantic results improve as embedding progresses; keyword search is unaffected throughout. The job survives a server restart and resumes where it stopped. Track progress with get_index_status.

Note

A rebuild empties the semantic index before it starts embedding. Until the job finishes, semantic search covers only the files embedded so far, while keyword search keeps covering everything. The rebuild never touches your conversation files and leaves the session extracts in place.

While the Rebuild Runs

• The job embeds the newest conversations first, so recent work becomes searchable by meaning soonest.
• The job pauses whenever Claude calls another PRIMA Memory tool, and carries on once that call has finished, so searches stay responsive.
• Search results carry a warning giving the job’s progress, such as Index rebuild in progress (60/140 session files embedded, newest first).
• PRIMA Memory skips its usual update before each search, because the rebuild already owns the index.
• Asking for a second rebuild reports the progress of the running job and does not start another one.

To follow progress, ask Claude to run get_index_status. While a job runs, the report’s job line reads like running — 60/140 files (43%), started 14/10/2026, 09:30:00.

If Claude Code Closes During a Rebuild

PRIMA Memory saves the state of the job in its database. When the server next starts, it finds the unfinished job and resumes it. Files it has already finished take almost no time to skip, so the job continues from where it stopped. The startup log records a line saying how many files were already done.

When the Rebuild Finishes

The report from get_index_status changes in two places.

Rebuild job: none running (last rebuild completed)

Coverage complete — semantic search spans the full corpus.

PRIMA Memory also writes a line to its startup log giving the number of files processed and any embedding errors. Conversation files that appeared after the job queued its list are not part of the job. If the verdict still reports missing files, the next search or rebuild picks them up.

The time a rebuild takes depends on the size of your history, because PRIMA Memory runs the embedding model on a single processor thread.

Starting Again From Nothing

A rebuild keeps the session extracts and the database file. To remove both and start with an empty folder, delete the .prima-memory/ folder as Privacy and Your Data describes.