PRIMA Memory v1.0.0

An MCP server that gives Claude Code access to its own conversation history. Search past sessions, recall decisions, and resume work across chat sessions.

Why This Exists

Claude Code conversations have a context window. When it fills, the session ends. Without session memory, Claude starts fresh every time — no knowledge of what was discussed, decided, or changed.

PRIMA Memory solves this. It reads Claude Code's conversation logs (stored as .jsonl files) and provides tools for Claude to search and recall previous sessions. This means:

• Claude can pick up where you left off without you re-explaining everything
• Decisions from previous sessions are retrievable
• File change history is searchable across all sessions

How Session Continuity Works

What happens when a session ends

Every Claude Code conversation is stored as a .jsonl file in ~/.claude/projects/. When a session reaches its context limit or you close the chat, the conversation is saved automatically by Claude Code.

How to resume work in a new session

With PRIMA Memory installed, Claude can search and read previous sessions. To resume:

1. Start a new session
2. Tell Claude what you were working on — e.g. "continue the work on the login page" or "what did we do last session?"
3. Claude uses PRIMA Memory to find the relevant session(s) and reconstructs the context

Without PRIMA Memory, Claude has no access to previous sessions. Your options are:

• Copy Claude's closing summary from the previous session and paste it into the new one
• Describe what you were working on and let Claude figure it out from the codebase

With PRIMA plugin (recommended)

PRIMA Memory works on its own, but works best with the PRIMA plugin. PRIMA adds:

• stoppedAt — a field per project recording where work stopped and what to do next
• .continue-here.md — handoff files written at end of session with full context for resumption
• /day command — morning briefing that reads stoppedAt and handoff files, showing exactly where each project was left
• Session history — structured log of recent sessions in state.json

When both are installed, PRIMA's /resume command upgrades automatically — it uses get_recent_sessions to list past sessions, get_session_details to recover full conversation transcripts at three detail levels (summary/standard/full), and search_history for keyword and semantic search across all sessions. Without PRIMA Memory, /resume falls back to the sessionHistory array in state.json (date, summary, projects worked). /day does not use PRIMA Memory — it reads stoppedAt from state.json directly.

The /save and /resume workflow

AI Business OS includes a /save command that writes a session checkpoint and returns a timestamp (e.g., 15:40). In the next session, the user runs /resume 15:40 to pick up where they left off.

• With PRIMA Memory: /resume matches the timestamp against get_recent_sessions results and can load full conversation detail
• Without PRIMA Memory: /resume matches by JSONL file modification time and falls back to sessionHistory in state.json

This means /save and /resume work on any AI Business OS workspace. PRIMA Memory enhances the detail available but is not required.

With AI Business OS

AI Business OS recommends PRIMA Memory as part of its setup. The /setup wizard guides you through installation. AI Business OS provides the workspace structure; PRIMA Memory provides the session recall; PRIMA (optional) provides project state tracking.

Tools

search_history

Search conversation history with relevance ranking. Supports keyword search, semantic (meaning-based) search, or both.

query: "authentication bug"
mode: "both"          # "keyword", "semantic", or "both" (default)
time_filter: "this week"
project_path: "/path/to/project"  # optional
limit: 5

get_recent_sessions

List recent sessions (excludes empty sessions).

limit: 10
project_path: "/path/to/project"  # optional

get_session_details

Get the full conversation from a specific session. Use the session ID from search_history or get_recent_sessions.

session_id: "abc123-def456"
include_tool_calls: true  # optional, default false

get_file_history

Track changes to a specific file across all sessions.

file_path: "src/auth.ts"
project_path: "/path/to/project"  # optional

summarise_period

Aggregate summary of work over a time period.

period: "this week"  # "today", "yesterday", "this week", "last week", "this month", "last month"
project_path: "/path/to/project"  # optional

rebuild_index

Force a complete rebuild of the semantic search index. Use if search results seem stale.

confirm: true

Installation

Clone into your workspace and build:

cd your-workspace
git clone https://github.com/larrygmaguire-hash/prima-memory.git .claude/mcp-servers/prima-memory
cd .claude/mcp-servers/prima-memory
npm install
npm run build

Then create a .mcp.json file in your workspace root:

{
  "mcpServers": {
    "prima-memory": {
      "type": "stdio",
      "command": "node",
      "args": [".claude/mcp-servers/prima-memory/dist/index.js"]
    }
  }
}

Add .prima-memory/ to your workspace .gitignore — this is where the database and extracts are stored.

Restart Claude Code after installation.

Updating

To get the latest version:

cd your-workspace/.claude/mcp-servers/prima-memory
git pull
npm install
npm run build

Restart Claude Code after updating for changes to take effect.

How It Works

PRIMA Memory reads Claude Code's conversation logs from ~/.claude/projects/, scoped to the current workspace only. These are .jsonl files that Claude Code creates automatically for every session.

Keyword search parses these files directly, scoring results by title match, file changes, message content, and recency.

Semantic search builds a vector index using a local embedding model (all-MiniLM-L6-v2, ~90MB, downloaded on first use). This enables meaning-based search — finding sessions about "authentication" even if the word "auth" was used instead.

The vector index is stored inside the workspace at .prima-memory/index.db and syncs lazily (only re-indexes changed files).

Combined search (default) runs both and merges results, with a bonus for sessions that match both keyword and semantic criteria.

Workspace Isolation

Each PRIMA Memory instance is fully independent. The server detects its workspace at startup and:

• Reads only session files belonging to that workspace
• Stores its database inside the workspace at .prima-memory/index.db
• Writes session extracts to .prima-memory/extracts/

Multiple workspaces on the same machine never share data. There is no global database or shared state.

Retrieval Best Practices

PRIMA Memory is most effective when used with retrieval discipline. Full session transcripts consume significant context window space — the same resource PRIMA Memory is designed to protect.

Recommended retrieval pattern:

1. Search first — use search_history to find matching sessions. The results include session IDs, timestamps, and summaries. This is often enough to identify the right session without loading the full conversation.
2. Confirm before loading — present the search results to the user and let them confirm which session is relevant. Do not preemptively load multiple full sessions.
3. Retrieve targeted details — when calling get_session_details, extract only what is needed (last action, key decisions, files modified, next step). Do not hold the full transcript in context.
4. One session at a time — if cross-referencing multiple sessions, pull one, extract key points, then pull the next. Never load 2-3 full sessions simultaneously.

Anti-patterns to avoid:

• Calling get_session_details on every search result "to be thorough"
• Loading full session transcripts when the search summary already answers the question
• Pulling multiple sessions into context preemptively before the user has confirmed what they need

This discipline should be codified in your workspace CLAUDE.md (or equivalent agent instructions) so it persists across sessions.

Data and Privacy

• All data stays on your machine, inside your workspace
• PRIMA Memory reads .jsonl files that Claude Code already creates
• The database and index are stored locally in .prima-memory/ within your workspace
• The embedding model runs locally — no data is sent to external services
• No API keys or accounts required

Requirements

• Node.js 18 or later
• Claude Code (which creates the .jsonl session files)

Credits

Based on claude-mems by Joe Tustin.

Licence

Copyright Larry G. Maguire / Human Performance. All rights reserved.

This software is provided under a proprietary licence. Unauthorised copying, distribution, or modification is not permitted without a valid licence. Contact [email protected] for licensing enquiries.

Portions of this software are based on claude-mems by Joe Tustin, used under the MIT licence.