Skip to main content
Harness Kit logoHarness Kit
DocsGitHub
Back to docs
workflowclaude-mem
Install
Source: packages/harness-kit/src/registry/bundles/workflow/claude-mem/README.md

Claude Mem

Experimental — heavy dependencies (Bun, ChromaDB via uv/Python). Powerful but complex setup.

Persistent session memory for Claude Code — auto-captures tool use, compresses via Claude Agent SDK, retrieves with hybrid semantic + keyword search.

Artifacts

TypeDetail
pluginRuns npx claude-mem install

Requirements

  • Bun >= 1.0.0 (auto-installed if missing)
  • Node.js >= 18
  • Chrome/Chromium
  • uv + ChromaDB (auto-installed if missing)

What it does

Plugin that gives Claude Code persistent memory across sessions:

  • 6 hooks auto-capture every tool use, compress observations, inject context on session start
  • 3 MCP tools for 3-layer retrieval: search → timeline → get_observations (~10x token savings)
  • 7 skills including mem-search, smart-explore (tree-sitter AST, 24 languages), knowledge-agent
  • Web UI at localhost:37777 for browsing memory stream
  • Worker daemon (Bun) runs in background, manages DB writes, embedding, summarization

Hooks

HookTriggerWhat it does
SessionStartstartup/clear/compactStart worker, inject relevant past context
UserPromptSubmitevery promptInitialize session tracking
PostToolUseevery tool resultCapture and compress observation
PreToolUse (Read)file readInject file-specific memory
Stopsession endCompress session summary

MCP tools

ToolDescription
searchFull-text + semantic search over memory index
timelineChronological context around a specific observation
get_observationsBatch-fetch full observation details by ID

Storage

  • SQLite (FTS5) — keyword search, primary storage (bundled)
  • ChromaDB — vector embeddings for semantic search

Setup

  1. Run harness-kit add claude-mem or select it during harness-kit init
  2. harness-kit runs npx claude-mem install
  3. Restart Claude Code
  4. Everything else is automatic — hooks, MCP, worker startup

License

AGPL-3.0 (core). ragtime/ subdirectory is PolyForm Noncommercial 1.0.0.

Notes

  • npm install -g claude-mem is NOT enough — the required installer is npx claude-mem install
  • If the install command fails during init/add, harness-kit reports it in bundle install notes and you can rerun npx claude-mem install manually
  • Worker daemon starts automatically on SessionStart, health-checks on port 37777
  • Settings stored in ~/.claude-mem/settings.json