HarnessCommunity★ 2k

claude-mem

Updated Jul 7, 2026

A Claude Code plugin that captures tool-call observations during sessions, compresses them into a SQLite + Chroma vector database, and injects relevant context automatically at the start of each new session. Three MCP search tools expose a token-efficient 3-layer retrieval workflow: search index first, timeline for context, then full details by ID. Requires Node.js 20+ and Bun.

View on GitHub

What it does

npx claude-mem install
Install the claude-mem plugin, register its lifecycle hooks, and start the local worker service.
search
MCP tool: full-text search over the memory index with type/date/project filters; returns a compact ID-keyed index (~50-100 tokens per result).
timeline
MCP tool: retrieve chronological context around a specific observation or query to understand what was happening nearby.
get_observations
MCP tool: fetch full observation details by a list of IDs — always batch multiple IDs to avoid repeated round trips.

Files (1)

OVERVIEW.mdprimary · markdown · 2.0 KB

## What it does

claude-mem is a persistent memory compression system for Claude Code. It hooks into 5 lifecycle events (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) to capture tool-call observations during a session, store them in a local SQLite database, and index them in a Chroma vector database for semantic search. At the start of each new session, the plugin injects relevant prior context automatically.

A local worker service (managed by Bun) runs as an HTTP API alongside Claude Code, providing a web viewer UI for browsing stored memories and a search API the MCP tools query.

The system uses a token-efficient 3-layer retrieval pattern:
1. search — get a compact index of matching observations (50-100 tokens per result)
2. timeline — get chronological context around interesting results
3. get_observations — fetch full details only for the IDs you filtered to (~500-1000 tokens per result)

This approach achieves roughly 10x token savings compared to fetching full observations upfront.

The plugin also supports a <private> tag in Claude's output to exclude sensitive content from being stored.

## Install

npx claude-mem install

Or from inside Claude Code:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Restart Claude Code after installation. Requires Node.js 20+ and Bun (auto-installed if missing).

Note: npm install -g claude-mem installs the SDK library only — always use npx claude-mem install to register the plugin hooks.

## MCP tools

search — full-text search over the memory index with optional type/date/project filters; returns compact results with IDs

timeline — chronological context around a specific observation or query

get_observations — fetch full observation details by a list of IDs (batch multiple IDs for efficiency)

## When to use

Install claude-mem on any long-running project where sessions pick up where prior sessions left off — active codebases, recurring research tasks, or any project where re-explaining context at the start of each session is a significant friction point.