llms.txt git:20260525.d1058bdA

Immutable. This exact content is served forever at /api/v1/blob/5a215d2bf63b869f.

# claude-mem-lite

> Persistent long-term memory for Claude Code (Anthropic's CLI coding agent) via the Model Context Protocol (MCP). Captures coding decisions, bugfixes, and context across sessions; recalls them via hybrid FTS5 + TF-IDF search. Single local SQLite database, no external services. Alternative to claude-mem with ~600× lower LLM cost.

claude-mem-lite is a Claude Code plugin (also installable via npm/npx) that runs as an MCP server plus a set of Claude Code lifecycle hooks (`SessionStart`, `PostToolUse`, `Stop`, `UserPromptSubmit`, `PreToolUse:Edit`, `PreToolUse:Read`). It automatically captures coding observations during sessions — file edits, bug fixes, decisions, refactors — then surfaces relevant past observations when you edit a related file or hit a familiar error. Search is hybrid: FTS5 BM25 + TF-IDF cosine similarity merged via Reciprocal Rank Fusion (RRF), with 100+ synonym pairs including CJK↔EN cross-language mappings. Benchmarked at 0.88 Recall@10 / 0.96 Precision@10 / 0.95 nDCG@10 across 200 observations / 30 queries.

## Core docs

- [README](https://github.com/sdsrss/claude-mem-lite/blob/main/README.md): full usage, architecture, comparison vs claude-mem / mem0 / MCP reference memory, FAQ
- [中文 README](https://github.com/sdsrss/claude-mem-lite/blob/main/README.zh-CN.md): Chinese documentation
- [CHANGELOG](https://github.com/sdsrss/claude-mem-lite/blob/main/CHANGELOG.md): version history (currently v2.84.2)
- [CLAUDE.md](https://github.com/sdsrss/claude-mem-lite/blob/main/CLAUDE.md): architecture map and module roles
- [Architecture comparison](https://github.com/sdsrss/claude-mem-lite#architecture-comparison): vs claude-mem original (the project this was redesigned from)
- [Comparison vs mem0 / MCP memory](https://github.com/sdsrss/claude-mem-lite#comparison-memory-systems-for-ai-coding-agents): differentiation from general LLM memory frameworks
- [FAQ](https://github.com/sdsrss/claude-mem-lite#faq): "what is memory for Claude Code", "vs mem0", privacy, cross-machine

## Key concepts

- **MCP server**: registers 20 tools total; 9 core exposed to Claude Code (`mem_search`, `mem_recent`, `mem_recall`, `mem_timeline`, `mem_get`, `mem_save`, `mem_defer`, `mem_defer_list`, `mem_defer_drop`); 11 admin/maintenance tools hidden from `tools/list` but reachable via the `claude-mem-lite` CLI
- **Hooks**: `SessionStart` (context injection + handoff resume), `PostToolUse` (episode capture + error-triggered recall), `Stop` (episode flush + handoff snapshot), `UserPromptSubmit` (semantic memory injection + L1 skill auto-load), `PreToolUse:Edit/Read` (file lesson recall)
- **Episode batching**: groups related tool calls (5–10 ops) before sending to LLM (Haiku) for structured observation extraction. ~600× lower cost than per-tool-call LLM invocation (claude-mem original's model).
- **Hybrid retrieval**: FTS5 BM25 keyword search + TF-IDF cosine (512-dim vectors) semantic search, fused via Reciprocal Rank Fusion. Synonym expansion handles abbreviations (`K8s`, `DB`, `auth`) and CJK↔EN cross-language (数据库↔database)
- **Cross-session handoff**: captures session state on `/clear` or `/exit`, re-injects on next session via FTS5 term overlap or `git SHA` continuation anchor
- **Invited memory pattern (v2.82+)**: installs an MCP-trigger sentinel into the project's `MEMORY.md` so Claude Code loads the tool-use contract as user-memory authority (higher rank than MCP server instructions). Auto-fires on first SessionStart per project; per-project and global opt-outs available.

## Installation

- `/plugin marketplace add sdsrss/claude-mem-lite && /plugin install claude-mem-lite` (Claude Code plugin marketplace, recommended)
- `npx github:sdsrss/claude-mem-lite` (one-liner; installs to `~/.claude-mem-lite/`)
- `git clone https://github.com/sdsrss/claude-mem-lite.git && node install.mjs install` (for development)

Requires Node.js ≥ 18, Claude Code CLI. Linux/macOS only (uses POSIX shell scripts).

## Related projects

- [claude-mem](https://github.com/thedotmack/claude-mem) — the original; claude-mem-lite is its ground-up redesign
- [mem0](https://github.com/mem0ai/mem0) — general-purpose LLM memory framework (any LLM app, manual SDK)
- [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — MCP reference `memory` server (knowledge-graph data model, manual tool calls)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — the parent product (Anthropic's CLI coding agent)
- [Model Context Protocol](https://modelcontextprotocol.io/) — the protocol claude-mem-lite implements