mem-lite

English | 中文

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 full-text search with query expansion 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 FTS5 retriever benchmarks at 0.90 Recall@10 / 0.85 Precision@10 (see Search Quality for the reproduction command).

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

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

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):

Quality comparison

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):

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 the Claude Code lifecycle (SessionStart, PreCompact, PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit — the seven events in hooks/hooks.json) to record observations without manual effort
• Lexical search with query expansion -- FTS5 BM25 scoring, an AND->OR rescue pass, pseudo-relevance feedback and concept co-occurrence. A TF-IDF vector arm shipped alongside it until it was measured net-negative and removed; --deep still fuses multiple LLM-rewritten queries with Reciprocal Rank Fusion
• 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 -- written at every Stop (the assistant's final report when it has Done / Not done sections, else — when the final reply has no report section at all — its first 120 characters, else the first prompt and recent observation titles), then upgraded by a background model summary when the session has observations
• 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
• Degraded fallback when the LLM fails -- An episode that fixed an error is saved with inferred metadata (as an activity event) instead of being discarded, when a command that exited 0 printed the error (npm test 2>&1 | tail): a command Claude Code reports as failed does not enter the episode, so a fix that follows one counts as edit-only. An edit-only episode, config and schema changes included, is summarised from raw tool output, which the noise rules drop in most cases (Modified a.js, b.js with no lesson; only a short single-file summary survives) — as they do when the model answers without a lesson — so a failing provider loses those episodes unless CLAUDE_MEM_KEEP_LOW_SIGNAL=1 is set; claude-mem-lite doctor warns when the claude CLI it would call does not resolve
• 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 FTS queries, preventing false negatives from noise terms like "how", "the", "does"
• 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
• Domain synonym expansion -- 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
• Dual injection dedup -- user-prompt-search.js and handleUserPrompt coordinate via temp file to prevent duplicate memory injection