Claude Mem Lite

[English](README.md) | [中文](README.zh-CN.md)

claude-mem-lite

claude-mem-lite is a persistent memory (also called long-term memory or cross-session context) system for Claude Code — Anthropic's CLI coding agent. It runs as an MCP server plus a set of Claude Code hooks, automatically capturing coding observations, decisions, and bug fixes during sessions, then providing hybrid full-text + semantic search to recall them later.

Compared to general-purpose LLM memory frameworks like mem0 or the MCP reference memory server, claude-mem-lite is purpose-built for Claude Code's hook lifecycle: episode batching cuts LLM calls 7–10× vs the original claude-mem (an estimated ~600× lower total cost — see the cost model below; this is an architecture estimate, not a measured benchmark), while the hybrid FTS5 + TF-IDF retriever benchmarks at 0.88 Recall@10 / 0.96 Precision@10.

> 中文简介：claude-mem-lite 是 Claude Code 的轻量级持久化记忆 / 长期记忆 / 跨会话上下文插件，基于 MCP 协议 + 钩子机制，自动捕获编码会话中的决策、修复和上下文，并通过 FTS5 + TF-IDF 混合检索召回。详见 [中文 README](README.zh-CN.md)。

Zero external services. Single SQLite database. Minimal overhead.

Why claude-mem-lite?

A ground-up redesign of claude-mem, replacing its heavyweight architecture with a smarter, leaner approach.

Architecture comparison

| | claude-mem (original) | claude-mem-lite | |---|---|---| | LLM calls | Every tool use triggers a Sonnet call | Only on episode flush (5-10 ops batched) | | LLM input | Raw tool_input + tool_output JSON | Pre-processed action summaries | | Conversation | Multi-turn, accumulates full history | Stateless single-turn extraction | | Noise filtering | LLM decides via "WHEN TO SKIP" prompt | Deterministic code-level Tier 1 filter | | Runtime | Long-running worker process (1.8MB .cjs) | On-demand spawn, exits immediately | | Dependencies | Bun + Python/uv + Chroma vector DB | Node.js only (3 npm packages) | | Source size | ~2.3MB compiled bundles | ~50KB readable source | | Data directory | ~/.claude-mem/ | ~/.claude-mem-lite/ (hidden, auto-migrates) |

Token & cost efficiency

For a typical 50-tool-call session (illustrative cost model — the ratios below are architecture estimates derived from batch size, token counts, and model pricing, not a measured end-to-end benchmark):

| | claude-mem | claude-mem-lite | Ratio (estimated) | |---|---|---|---| | LLM calls | ~50 (every tool use) | ~5-8 (per episode) | ~7-10x fewer | | Tokens per call | 1,000-5,000 (raw JSON + history) | 200-500 (summaries only) | ~5-10x smaller | | Total tokens | ~100K-250K | ~1K-4K | ~50-100x less | | Model cost | Sonnet ($3/$15 per M) | Haiku ($0.25/$1.25 per M) | ~12x cheaper | | Combined savings | | | ~600x lower cost (estimated) |

Quality comparison

| Dimension | Winner | Why | |---|---|---| | Classification accuracy | Tie | Both produce correct type/title/narrative | | Noise filtering | lite | Code-level filtering is deterministic; LLM "WHEN TO SKIP" is unreliable | | Observation coherence | lite | Episode batching groups related edits into one coherent observation | | Code-level detail | original | Sees full diffs, but rarely useful for memory search | | Search recall | Tie | Users search semantic concepts ("auth bug"), not code lines | | Hook latency | lite | Async background workers; original blocks 2-5s per hook |

Design philosophy

The original sends everything to the LLM and hopes it filters well. claude-mem-lite filters first with code, then sends only what matters to a smaller model. This is not a downgrade; it's a smarter architecture that produces equivalent search quality at a fraction of the cost.

Comparison: memory systems for AI coding agents

How claude-mem-lite differs from the major neighbors in the LLM-memory space (verified May 2026):

| | claude-mem-lite | mem0 | MCP reference memory | claude-mem (original) | |---|---|---|---|---| | Target client | Claude Code only | Any LLM app via SDK | Any MCP client | Claude Code only | | Capture model | Auto via hooks | Manual memory.add() | Manual tool calls (create_entities, add_observations) | Auto via hooks | | Code-aware retrieval | FTS5 + 100+ synonym pairs (incl. CJK↔EN) | General-purpose | Generic graph nodes | Code-aware | | Search | Hybrid: FTS5 BM25 + TF-IDF cosine via RRF | Hybrid: semantic + BM25 + entity linking | Knowledge-graph traversal | FTS5 + Chroma vector | | Storage | Single local SQLite | Pluggable; Qdrant or configurable vector store | Single JSONL file (knowledge graph) | SQLite + Chroma | | LLM dependency | Haiku per episode (5–10 ops batched) | LLM per add/search op | None (graph CRUD only) | Sonnet per tool call | | Setup | One command (/plugin install or npx) | SDK integration + vector store config | MCP install (per-client) | Bun + Python + Chroma |

When to pick which: pick mem0 if you need a memory layer for a non-Claude-Code app (your own agent, multiple LLM providers). Pick the MCP reference memory server if you specifically want a knowledge-graph data model and don't mind invoking memory tools by hand. Pick claude-mem-lite if you want zero-touch automatic capture purpose-built for Claude Code's hook lifecycle, with code-domain retrieval and no external services.

Features

• Automatic capture -- Hooks into Claude Code lifecycle (PostToolUse, SessionStart, Stop, UserPromptSubmit) to record observations without manual effort
• Hybrid search -- FTS5 BM25 + TF-IDF vector cosine similarity, merged via Reciprocal Rank Fusion (RRF). FTS5 handles keyword matching; 512-dim TF-IDF vectors capture semantic similarity for recall beyond exact terms
• Timeline browsing -- Navigate observations chronologically with anchor-based context windows
• Episode batching -- Groups related file operations into coherent episodes before LLM encoding
• Error-triggered recall -- Automatically searches memory when Bash errors occur, surfacing relevant past fixes
• Proactive file history -- When editing a file, automatically shows relevant past observations for that file
• Session summaries -- LLM-generated summaries at session end (via background workers using claude -p)
• Project-scoped context -- Injects recent memory into CLAUDE.md and session startup for immediate context
• Observation types -- Categorized as decision, bugfix, feature, refactor, discovery, or change
• Importance grading -- LLM assigns 1-3 importance levels (routine / notable / critical) to each observation
• Observation relations -- Bidirectional links between related observations based on file overlap
• User prompt capture -- Records user prompts via UserPromptSubmit hook for intent tracking
• Read file tracking -- Tracks files read during sessions for richer episode context
• Zero data loss -- If LLM fails, observations are saved with degraded (inferred) metadata instead of being discarded
• Two-tier dedup -- Jaccard similarity (5-minute window) + MinHash signatures (7-day cross-session window) prevent duplicates
• Synonym expansion -- Abbreviations like K8s, DB, auth automatically expand to full forms in FTS5 search (100+ pairs including CJK↔EN cross-language mappings)
• CJK synonym extraction -- Unsegmented Chinese text is scanned for known vocabulary words (数据库→database, 搜索→search, etc.) enabling cross-language memory recall
• Stop-word filtering -- English stop words filtered from both TF-IDF vocabulary (reclaiming ~18% of vector dimensions) and FTS queries (preventing false negatives from noise terms like "how", "the", "does")
• Persisted vocabulary -- TF-IDF vocabulary persisted to vocab_state table, preventing vector staleness when document frequencies shift. Vectors stay valid until explicit rebuild
• Pseudo-relevance feedback (PRF) -- Top results seed expansion queries for broader recall
• Concept co-occurrence -- Shared concepts across observations expand search to related topics
• Context-aware re-ranking -- Active file overlap boosts relevance (exact match + directory-level half-weight)
• Superseded detection -- Marks older observations as outdated when newer ones cover the same files with higher importance
• Adaptive time windows -- Session startup recall uses velocity-based time windows (high/medium/low activity tiers)
• Token-budgeted context -- Greedy knapsack algorithm selects session-start context within a 2,000-token budget, prioritizing by recency and importance
• Observation compression -- Old low-value observations can be compressed into weekly summaries to reduce noise
• Secret scrubbing -- Automatic redaction of API keys, tokens, PEM blocks, connection strings, and 15+ credential patterns
• Atomic writes -- All file writes (episodes, CLAUDE.md) use write-to-tmp + rename to prevent corruption on crash
• Robust locking -- PID-aware lock files with automatic stale/orphan cleanup (>30s timeout or dead PID)
• Stale session cleanup -- Sessions active for >24h are automatically marked as abandoned on next start
• Resource registry -- Indexes installed skills and agents with FTS5 search, composite scoring, and invocation tracking; searchable via mem_registry MCP tool
• Unified resource discovery -- Shared filesystem traversal layer (resource-discovery.mjs) used by both runtime scanner and offline indexer, supporting flat directories, plugin nesting, and loose .md files
• Domain synonym expansion -- Registry search queries expand to domain synonyms (e.g., "fix" → debug, bugfix, troubleshoot, diagnose, repair)
• Multi-provider LLM mode -- Provider priority ANTHROPIC_API_KEY (direct Anthropic API) → OPENROUTER_API_KEY (OpenRouter, OpenAI-compatible — point it at any model via OPENROUTER_MODEL) → claude -p CLI fallback when no key is set
• Lesson-learned indexing -- lesson_learned field indexed in FTS5 with weight 8, making past debugging insights directly searchable
• Cross-source normalization -- mem_search normalizes scores across observations, sessions, and prompts before merging, preventing any source from dominating results
• Exponential recency decay -- Type-differentiated half-lives (decisions: 90d, discoveries: 60d, bugfixes: 14d, changes: 7d) consistently applied in all ranking paths
• Prompt-time memory injection -- UserPromptSubmit hook automatically searches and injects relevant past observations with recency and importance weighting
• Smart skill invocation -- Auto-loaded and searched managed skills/agents include portable ~ paths with Read() guidance; native plugin skills recommend Skill("full:name"); prevents Skill() misuse for managed resources that aren't registered with Claude Code's native handler
• Dual injection dedup -- user-prompt-search.js and handleUserPrompt coordinate via temp file to prevent duplicate memory injection
• Plugin cache hook self-heal -- Claude Code runtime reads plugin hooks from ~/.claude/plugins/cache////hooks/hooks.json, not from the marketplace source. When install.mjs-managed settings.json hooks coexist with a stale cache hooks.json (e.g. from a previous marketplace install or a plugin auto-update), the runtime registers hooks twice → every session start / user prompt fires twice. install.mjs and hook-update.mjs now clear cache hooks.json in every version dir, and hook.mjs session-start self-heals on every session (gated by hasInstallManagedHooks so plugin-only users are not affected). install.mjs status reports cache pollution state (since v2.31.1/2.31.2).
• Result-dedup cooldown -- User-prompt memory injection uses result-overlap detection (>80% ID overlap → skip) instead of time-based cooldown, allowing topic switches within seconds while preventing redundant injections
• OR query fallback -- When AND-joined FTS5 queries return zero results, automatically relaxes to OR-joined queries for broader recall (applied in both user-prompt-search and hook-memory paths)
• Configurable LLM model -- Switch between Haiku (fast/cheap) and Sonnet (deeper analysis) via CLAUDE_MEM_MODEL env var
• DB auto-recovery -- Detects and cleans corrupted WAL/SHM files on startup; periodic WAL checkpoints prevent unbounded growth
• Schema auto-migration -- Idempotent ALTER TABLE migrations run on every startup, safely adding new columns and indexes without data loss
• Exploration bonus -- New resources in the registry get a fair chance in composite ranking; zombie resources (high recommend, zero adopt) are penalized in scoring
• LLM concurrency control -- File-based semaphore limits background workers to 2 concurrent LLM calls, preventing resource contention
• stdin overflow protection -- Hook input truncated at 256KB with regex-based action salvage for oversized tool outputs
• Cross-session handoff -- Captures session state (request, completed work, next steps, key files) on /clear or /exit, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap
• Git-SHA continuation anchor (v2.31.0) -- Handoff rows include git_sha_at_handoff; any handoff matching the current HEAD counts as continuation regardless of TTL. Code state is a stronger continuation signal than wall-clock time
• Startup dashboard (v2.31.0) -- SessionStart hook aggregates git status + ~/.claude/tasks/*.json + ~/.claude/plans/*.md + most-recent exit handoff + recent event count into a single structured block injected via hookSpecificOutput.additionalContext
• Activity namespace (v2.31.0) -- Dedicated events table + FTS5 for non-memdir types (bugfix, lesson, bug, discovery, refactor, feature, observation, decision) that don't compete with WHAT_NOT_TO_SAVE semantics on the observations table. CLI: claude-mem-lite activity save|search|recent|show. Slash commands: /lesson, /bug. hook-llm routes non-memdir summary types through persistHaikuSummary so upgrades from observations→events are atomic
• In-place observation updates -- mem_update tool modifies existing observations atomically (field update + FTS text rebuild + vector re-computation in one transaction), preserving original IDs and references
• Bulk export -- mem_export tool exports observations as JSON or JSONL, with project/type/date filtering and 1000-row pagination cap with batch guidance
• FTS integrity management -- mem_fts_check tool verifies FTS5 index health or rebuilds indexes on demand, useful after database recovery or when search results seem wrong
• Atomic multi-table writes -- saveObservation wraps observations + observationfiles + observationvectors INSERTs in a single db.transaction(), preventing orphaned rows on crash
• Modular NLP pipeline -- Synonym maps, stop words, scoring constants, and query building extracted into focused modules (synonyms.mjs, stop-words.mjs, scoring-sql.mjs, nlp.mjs) for independent testing and maintenance
• Porter-aligned PRF -- Pseudo-relevance feedback terms are now stemmed with the same Porter algorithm used by FTS5, ensuring PRF expansion terms match the search index

Platform Support

| Platform | Status | Notes | |----------|--------|-------| | Linux | Supported | Primary development and testing platform | | macOS | Supported | Fully compatible (Intel and Apple Silicon) | |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sdsrss
• Source: sdsrss/claude-mem-lite
• License: MIT

Install and usage instructions live in the source repository linked above.