How Indexing Works
PRIMA Memory never asks you to save anything. It reads the conversation files that Claude Code and a few other tools already keep on your computer. When you search, it builds its own index from them.
Where Your Conversations Come From
Section titled “Where Your Conversations Come From”Claude Code saves each conversation as a .jsonl file in ~/.claude/projects/, inside a folder named after the workspace. Claude Code forms that folder name from the workspace path by replacing every / and every space with -. The conversations for /Users/you/Example Consulting sit in ~/.claude/projects/-Users-you-Example-Consulting/. PRIMA Memory uses the same rule to find the folder for the workspace it serves, and it serves the workspace it starts in.
The Sources It Reads
Section titled “The Sources It Reads”In a standard Claude Code install PRIMA Memory reads these sources.
| Source | Location | Scope | Label in results |
|---|---|---|---|
| Claude Code conversations | ~/.claude/projects/<encoded-workspace-path>/*.jsonl |
The current workspace only | [transcript] |
| Shared project log | <workspace>/.claude/state/sessions/<PROJECT-ID>/*.md, skipping files whose names start with _ |
The whole log, including colleagues’ entries in a synced workspace | [shared log · author] |
| VS Code Copilot Chat | The GitHub.copilot-chat/transcripts/ folders inside VS Code’s workspaceStorage folder |
Every VS Code workspace on your user account, because Copilot records no workspace path | [VS Code] |
| Session history, the last search step | .claude/state/state.json and .claude/state/projects/*.json for the current month, then .claude/state/history/YYYY-MM.json newest first |
Read only when the conversations find nothing, and the archive only when the current month finds nothing | Session History Summaries |
| Codex | ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl |
Sessions whose recorded working folder is this workspace or a folder inside it, plus sessions that recorded no folder | [Codex] |
PRIMA Memory skips any source that is not on your computer. It reads every source and never changes one. When an installed source has a problem, such as an empty folder, files it cannot read or record types it does not recognise, PRIMA Memory writes a warning to its startup log.
The shared project log is a folder of short markdown entries, one file per entry. Each entry has a header naming the project, the author and the time. PRIMA Memory turns each entry into a searchable item labelled with its author. If your workspace has no .claude/state/sessions/ folder, PRIMA Memory reads nothing for this source and does not search the rest of your computer for one.
Host Mode
Section titled “Host Mode”PRIMA Memory reads the Claude Code conversations for your workspace and keeps its index inside that workspace. The AI Business OS installer sets PRIMA_EXPECTED_HOST to claude-code, which holds PRIMA Memory to this mode. Configuration describes the variable and the safety check it adds.
Keyword Search
Section titled “Keyword Search”Keyword search reads the conversation files directly each time you search. It needs no index, so it always covers your whole history, including sessions the semantic index has not reached yet.
A session matches a keyword search when any of these is true.
- Its title contains your whole query.
- The path of a file it changed contains your whole query.
- Every word of your query appears somewhere in its messages.
PRIMA Memory then scores each matching session and lists the highest scores first.
| Signal | Points |
|---|---|
| Title contains the whole query | 20 |
| Each changed file whose path contains the whole query | 10 |
| Each message that contains a query word, for each word it contains | 2 |
| Session started in the last seven days | Up to 10, falling to 0 at seven days |
| Files changed in the session | 1 per file, up to 5 |
Matching ignores capital letters and finds words inside longer words, so a search for room also matches “bedroom”.
Semantic Search
Section titled “Semantic Search”Semantic search finds sessions by meaning. PRIMA Memory uses the all-MiniLM-L6-v2 embedding model, in the quantised Xenova build of about 23 MB, and runs it on your computer through a WebAssembly runtime. The model turns text into a list of 384 numbers that represents its meaning. Texts with similar meanings get similar lists.
PRIMA Memory embeds your history one exchange at a time. An exchange is one of Claude’s replies. The first reply after a message you sent is stored together with your message, and any further replies in the same turn are stored on their own. The model reads the first 2,000 characters of each exchange. At search time PRIMA Memory embeds your query in the same way, compares it with every stored exchange, drops any match whose similarity falls below 0.3 on a scale of 0 to 1, and keeps the best exchange for each session.
Each entry in the shared project log counts as one exchange.
Combined Search
Section titled “Combined Search”Combined search is the default. PRIMA Memory runs both searches, rescales the keyword scores to a range of 0 to 100 and shows semantic similarity on the same range. A session that both searches find takes the higher of its two scores plus 20 per cent, which moves it up the list.
If the semantic part fails, for example because the model could not load, PRIMA Memory returns the keyword results and puts a warning at the top saying so.
When the Index Updates
Section titled “When the Index Updates”PRIMA Memory updates the semantic index lazily. Nothing runs in the background while you work, apart from a rebuild you have started.
- You, or a command such as
/resume, run a semantic or combined search. - Before searching, PRIMA Memory looks for conversation files that are new or have changed since it last indexed them.
- It embeds those files, newest first, for up to 20 seconds.
- It runs your search against the index as it stands.
- Files it did not reach wait for the next search or for a rebuild.
PRIMA Memory tracks each file by its last-modified time, so a conversation that grows after indexing gets embedded again in full at the next search. A keyword-only search never touches the index. While a rebuild is running, the update before each search does not happen, because the rebuild already owns the index.
What the Index Stores
Section titled “What the Index Stores”The index is a SQLite database at .prima-memory/index.db in your workspace. For each exchange it stores the text of your message and of Claude’s reply, along with the 384-number vector. It also keeps the session ID, the time, the project folder, the git branch, the path of the source file, the source label and, for shared log entries, the author’s name. It also records which files it has indexed and the state of any rebuild.
Everything in the index comes from files on your disk, so PRIMA Memory can rebuild it at any time from the conversations that still exist.
Session Titles, Tags and File Changes
Section titled “Session Titles, Tags and File Changes”Each Claude Code session gets a title. PRIMA Memory uses the summary line Claude Code writes into the conversation file when there is one. Otherwise it takes the first line or sentence of your first message, removes text that Claude Code adds inside tags and opening phrases such as “can you” or “please”, and keeps up to 80 characters. A session with neither gets the title “Untitled Session”.
PRIMA Memory also tags each session. It adds a language tag, such as python or typescript, for each type of code file the session changed. It adds bugfix, refactor, testing or feature when those words, or related words such as “fix” and “implement”, appear in the conversation.
In Claude Code conversations PRIMA Memory records a file change each time Claude uses the Write or Edit tool. Changes made any other way, such as through a terminal command, do not appear in the file history.
Session Extracts
Section titled “Session Extracts”When PRIMA Memory indexes a substantial Claude Code session, it also writes a markdown extract of that session. A session counts as substantial if it has 50 or more messages, changed 10 or more files, or lasted 30 minutes or longer.
PRIMA Memory saves each extract as .prima-memory/extracts/<project-id>/YYYY-MM-DD-HHMM-session-extract.md. The project ID is the last folder name of the session’s working folder in lower case, with spaces turned into hyphens and other punctuation removed, so a session in Example Consulting files its extracts under example-consulting.
Each extract contains these parts.
- A header with the session ID, date, duration, project folder, branch, message count, number of files changed and tags.
- The session title.
- A table of the files changed, with the explanation Claude gave for each change.
- The last five messages from Claude that run to more than 200 characters, most recent first.
- The last ten exchanges in full.
PRIMA Memory writes at most one extract per project folder per day. If that folder already holds an extract or checkpoint file dated the same day, or a file whose name contains the session’s ID, it writes no new extract. It never updates an extract after writing it, and a rebuild leaves extracts in place. You can search extracts with a deep search.