Tools Reference

PRIMA Memory gives Claude Code seven tools. You do not call them yourself, because Claude chooses a tool and its settings from what you ask. This page lists every setting each tool accepts, so you can ask for a particular behaviour and understand the replies. No setting is required unless its table says so.

search_history

Searches your history and ranks the sessions by relevance. It can match by keyword, by meaning or both, and it can also search the session extracts.

Setting	Type	Default	Description
query	text	empty	Natural language, file names or keywords
mode	keyword, semantic or both	both	Exact matching, meaning-based matching, or both merged
time_filter	text	none	today, yesterday, this week, last week, this month, last month, N days ago or N weeks ago. Keeps the sessions that started since that point. An unrecognised value applies no filter
project_path	text	none	Narrows the results, with each source treating the value differently (see Narrowing by Project)
limit	number	5	The most sessions to return
deep	true or false	false	Also searches the session extracts in .prima-memory/extracts/

{
  "query": "venue shortlist",
  "mode": "both",
  "time_filter": "this week",
  "limit": 5
}

Each result shows the session title, a relevance score, a source label ([transcript], [shared log · author], [VS Code] or [Codex]), the session ID, time, project, branch, tags, the names of changed files and up to two matching passages. A deep search adds an Agent Outputs section listing matching extract files.

A warning line at the top of the results tells you when part of the history is not yet in the semantic index or a rebuild is running. Warnings also report text that failed to embed and a semantic search that failed, leaving keyword-only results. A semantic or combined search first updates the index for up to 20 seconds. Searching Your History explains time windows, scoring, deep search and the warnings in full.

get_recent_sessions

Lists recent sessions, newest first. It reads only the Claude Code conversations for the current workspace and leaves out empty sessions. Shared log, VS Code and Codex sessions do not appear in this list.

Setting	Type	Default	Description
limit	number	5	How many sessions to return
project_path	text	none	Keeps the workspace’s sessions when the value is the workspace’s full path, its folder name, or another value that ends in the same words as the workspace path. Returns none for any other value

Each entry shows the session title, session ID, start time and length in minutes, project folder, branch, tags, message count and number of files changed.

Recent sessions:

## Spring Workshop venue shortlist [transcript]
  Session: 5b1e7c2a-0d4f-4e8b-9a61-2c7f3e9d1a40
  Time: 07/10/2026, 14:05:12 (48 min)
  Project: /Users/you/Example Consulting
  Branch: main
  Tags: feature
  Messages: 64
  Files changed: 3

The extracts folder may hold a file named YYYY-MM-DD-session-checkpoint.md for the session’s project and start date. In that case the entry also shows the file’s path and a preview of its latest summary. PRIMA Memory does not write these checkpoint files itself. The line appears only when another tool has saved one there.

get_session_details

Opens one session and shows its conversation, using the session ID from search_history or get_recent_sessions. It opens Claude Code conversations from the current workspace and entries from the shared project log. It cannot open VS Code Copilot Chat or Codex sessions, even when search_history finds them.

Setting	Type	Default	Description
session_id	text	none	Required. The session to open
project_path	text	none	Limits where the tool looks for the session
include_tool_calls	true or false	false	Lists the names of the tools Claude used in each message
detail_level	summary, standard or full	standard	The most characters shown for each message, which is 2,000 for summary, 5,000 for standard and unlimited for full

{
  "session_id": "5b1e7c2a-0d4f-4e8b-9a61-2c7f3e9d1a40",
  "detail_level": "summary"
}

The reply opens with the session title, ID, time and length, project folder, branch, message count and tags, followed by a list of the files changed. The conversation follows, one message at a time with its time. A message longer than the limit ends with a note giving the limit and suggesting detail_level: "full". If no session has that ID, the tool replies that it cannot find the session.

Note

A full reply can be very long and fills Claude’s context window quickly. Resuming a Previous Session describes how to keep what Claude loads small.

get_file_history

Shows the recorded changes to a file across all sessions, most recent first. The match ignores capital letters and accepts part of a path, so agenda finds Projects/P012/agenda.md.

Setting	Type	Default	Description
file_path	text	none	Required. The file path, or part of it
project_path	text	none	Narrows the sessions searched, in the same way as search_history

File history for "agenda.md" (2 changes):

- 07/10/2026, 14:31:09 [edit]
  /Users/you/Example Consulting/Projects/P012/agenda.md
  Session: 5b1e7c2a-0d4f-4e8b-9a61-2c7f3e9d1a40
  "I've moved the breakout sessions to the afternoon so they follow the keynote..."

Each change shows the time, the kind of change (write or edit), the full path, the session ID and the explanation Claude gave just before making the change. In Claude Code conversations PRIMA Memory records a change only when Claude used its Write or Edit tool. Changes made through terminal commands do not appear.

summarise_period

Totals the work done over a period, with the number of sessions and messages, the files changed, the projects worked on, the common topics and a list of session titles.

Setting	Type	Default	Description
period	text	none	Required. today, yesterday, this week, last week, this month or last month. Any other value covers the last seven days
project_path	text	none	Narrows the sessions counted, in the same way as search_history

# Summary: last week

**Period:** 04/10/2026 - 11/10/2026
**Total Sessions:** 9
**Total Messages:** 412
**Files Changed:** 14 files (agenda.md, budget.xlsx, venue-shortlist.md, invite.md, notes.md...)

## Projects Worked On
  - /Users/you/Example Consulting

## Key Topics
workshop, venue, budget, agenda, spring

## Session Highlights
  - Spring Workshop venue shortlist
  - P012 budget revision

The key topics are the ten words longer than three letters that appear most often in the session titles, leaving out common words. The highlights list up to ten session titles and skip untitled sessions. Weeks start on Sunday, as they do for the search_history time filter.

rebuild_index

Clears the semantic index and embeds every session file again as a background job. Use it when search results seem stale, or when search_history or get_index_status reports files that are not yet embedded.

Setting	Type	Default	Description
confirm	true or false	none	Required. Must be true. Any other value cancels the rebuild

The call returns at once with the number of files queued. The job embeds the newest sessions first and pauses while Claude waits on another tool call. If the server restarts, the job resumes where it stopped. Until it finishes, semantic results cover only the files embedded so far, and keyword search is unaffected throughout. Calling rebuild_index while a job is running reports the job’s progress and does not start a second job. Rebuilding the Index walks through a rebuild.

get_index_status

Reports how much of your history the semantic index covers and whether a rebuild is running. It takes no settings.

The report gives the number of session files on disk, how many are embedded and how many are not. It counts the exchanges indexed and embedded for each source, with totals. It then gives the state of any rebuild job and a one-line verdict on whether semantic search covers your full history. Rebuilding the Index shows an example report with each line explained.