​
How It Works

claude-mem creates a persistent memory layer for Claude Code sessions, capturing and recalling context automatically.

​
Architecture Overview

​
Key Components

​
1. Hook System

claude-mem uses three hooks:

​
2. Memory Compression

During compression:
1

Extract Transcript - Captures the conversation from Claude Code
2

Analyze Content - Identifies key insights, solutions, and decisions
3

Generate Summaries - Creates searchable memory documents
4

Save Memories - Writes to the local JSONL index and instructs Claude to sync with Chroma via MCP tools

​
3. Context Loading

When you start a new session:
  1. Project Detection - Identifies current working directory
  2. Memory Lookup - Reads recent entries from the local JSONL index
  3. Ranking - Orders by recency and session grouping
  4. Display - Shows formatted context in session start
The hook reads ~/.claude-mem/claude-mem-index.jsonl for recent summaries without Chroma queries.

​
Memory Storage

claude-mem writes summaries to local JSONL and persists in Chroma via MCP: 
{
  // Document content
  content: "Implemented authentication using JWT tokens with refresh...",

  // Metadata for search and filtering
  metadata: {
    session_id: "abc123",
    timestamp: "2025-09-15T10:30:00Z",
    keywords: ["authentication", "jwt", "security"],
    project: "my-app",
    type: "feature"
  }
}

​
Storage Locations

​
Compression Algorithm

Transcript compression process: 
// Parses Claude Code transcript
const messages = parseTranscript(transcript);

// Filters relevant content
const filtered = messages.filter(m =>
  m.role === 'assistant' &&
  m.content.length > 100
);
Vector search process:
  1. Query Embedding - Converts search query to vector
  2. Similarity Search - Finds closest matches in Chroma
  3. Metadata Filtering - Applies project/time filters
  4. Result Ranking - Orders by relevance score
// Example search
const results = await chroma.query({
  queryTexts: ["authentication bug fix"],
  nResults: 5,
  where: { project: "current-project" }
});

​
MCP Integration

MCP integration with Chroma:
MCP provides a standardized way for Claude Code to interact with external tools like Chroma DB.

​
MCP Server Configuration

{
  "mcpServers": {
    "chromadb-claude-mem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-chromadb"]
    }
  }
}

​
Available MCP Tools

  • chroma_add_documents - Store new memories
  • chroma_query_documents - Search memories
  • chroma_get_documents - Retrieve specific memories
  • chroma_delete_documents - Remove memories

​
Performance Optimization

Performance features:

​
Data Flow Example

Complete claude-mem lifecycle:

​
Next Steps