English | 中文

Lightweight persistent memory system for Claude Code. Automatically captures coding observations, decisions, and bug fixes during sessions, then provides full-text search to recall them later.

Built as an MCP server + Claude Code hooks. Zero external services, single SQLite database, minimal overhead.

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

For a typical 50-tool-call session:

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.

• 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)
• Dual LLM mode -- Auto-detects ANTHROPIC_API_KEY for direct API calls; falls back to claude -p CLI when no key is available
• 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
• 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
• 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 + observation_files + observation_vectors 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

• Node.js >= 18
• Claude Code CLI installed and configured (claude command available)
• SQLite3 support (provided by better-sqlite3, compiled on install)
• Platform: Linux or macOS (see Platform Support)

/plugin marketplace add sdsrss/claude-mem-lite
/plugin install claude-mem-lite

Plugin mode manages its own hooks/runtime. On session start it only checks and reports new claude-mem-lite versions; it does not self-overwrite plugin files in place. Update plugin-mode installs through Claude's plugin workflow.

npx github:sdsrss/claude-mem-lite

Source files are automatically copied to ~/.claude-mem-lite/ for persistence.

git clone https://github.com/sdsrss/claude-mem-lite.git
cd claude-mem-lite
node install.mjs install

Source files stay in the cloned repo. Update via git pull && node install.mjs install.

1. Install dependencies -- npm install --omit=dev (compiles native better-sqlite3)
2. Register MCP server -- mem server with 16 tools (search, recent, recall, timeline, get, save, update, stats, delete, compress, maintain, export, fts_check, browse, registry, use)
3. Configure hooks -- PostToolUse, SessionStart, Stop, UserPromptSubmit lifecycle hooks
4. Create data directory -- ~/.claude-mem-lite/ (hidden) for database, runtime, and managed resource files
5. Auto-migrate -- If ~/.claude-mem/ (original claude-mem) or ~/claude-mem-lite/ (pre-v0.5 unhidden) exists, migrates database and runtime files to ~/.claude-mem-lite/, preserving the original untouched
6. Initialize database -- SQLite with WAL mode, FTS5 indexes created on first server start

Restart Claude Code after installation to activate.

All installation methods auto-detect and migrate from previous versions:

From claude-mem (original ~/.claude-mem/):

• Copy claude-mem.db → ~/.claude-mem-lite/claude-mem-lite.db (renamed)
• Copy the runtime/ directory
• Original ~/.claude-mem/ is preserved (no deletion, no overwrite)

From pre-v0.5 unhidden directory (~/claude-mem-lite/):

• Entire directory is moved to ~/.claude-mem-lite/ (hidden)

In-place rename:

• Existing claude-mem.db in ~/.claude-mem-lite/ is automatically renamed to claude-mem-lite.db

Remove old directories manually after confirming:

rm -rf ~/.claude-mem/       # original claude-mem
rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)

~/.claude-mem-lite/
  claude-mem-lite.db       # SQLite database — memory (WAL mode)
  resource-registry.db     # SQLite database — skill/agent registry
  runtime/
    session-<project>    # Active session state
    ep-<project>.json    # Episode buffer
    ep-flush-*.json      # Flushed episodes awaiting processing
    reads-<project>.txt  # Read file paths (collected on flush)
  managed/
    skills/              # Standalone skills: {name}/SKILL.md
    agents/              # Agent plugins: {group}/agents/{name}.md + skills/*/SKILL.md
    repos/               # Shallow-cloned source repos

/mem search <query>        # Full-text search across all memories
/mem recent [n]            # Show recent N observations (default 10)
/mem recall <file>         # Show past observations for a file
/mem save <text>           # Save a manual memory/note
/mem stats                 # Show memory statistics
/mem timeline <query>      # Browse timeline around a match
/mem browse                # Tier-grouped memory dashboard
/mem <query>               # Shorthand for search

1. mem_search(query="auth bug")     -> compact ID index
2. mem_timeline(anchor=12345)       -> surrounding context
3. mem_get(ids=[12345, 12346])      -> full details

Five core tables with FTS5 virtual tables for search:

observations -- Individual coding observations (decisions, bugfixes, features, etc.)

id, memory_session_id, project, type, title, subtitle,
text, narrative, concepts, facts, files_read, files_modified,
importance, related_ids, created_at, created_at_epoch,
lesson_learned, minhash_sig, access_count, compressed_into, search_aliases,
branch, superseded_at, superseded_by, last_accessed_at

session_summaries -- LLM-generated session summaries

id, memory_session_id, project, request, investigated,
learned, completed, next_steps, files_read, files_edited, notes,
remaining_items, lessons, key_decisions

sdk_sessions -- Session tracking

id, content_session_id, memory_session_id, project,
started_at, completed_at, status, prompt_counter

user_prompts -- User prompts captured via UserPromptSubmit hook

id, content_session_id, prompt_text, prompt_number

session_handoffs -- Cross-session handoff snapshots (UPSERT, max 2 per project)

project, type, session_id, working_on, completed, unfinished,
key_files, key_decisions, match_keywords, created_at_epoch

observation_files -- Normalized file membership for efficient file-based recall

obs_id, filename

observation_vectors -- TF-IDF vector embeddings for hybrid search

observation_id, vector (BLOB Float32Array), vocab_version, created_at_epoch

vocab_state -- Persisted TF-IDF vocabulary for stable vector indexing

term, term_index, idf, version, created_at_epoch

FTS5 indexes: observations_fts (title, subtitle, narrative, text, facts, concepts, lesson_learned), session_summaries_fts, user_prompts_fts

SessionStart
  -> Generate session ID (or save handoff snapshot on /clear)
  -> Mark stale sessions (>24h active) as abandoned
  -> Clean orphaned/stale lock files
  -> Query recent observations (24h)
  -> Inject context into CLAUDE.md + stdout

PostToolUse (every tool execution)
  -> Bash pre-filter skips noise in ~5ms (Read paths tracked to reads file)
  -> Detect Bash significance (errors, tests, builds, git, deploys)
  -> Accumulate into episode buffer
  -> Proactive file history: show past observations for edited files
  -> Flush when: buffer full (10 entries) | 5min gap | context change
  -> Collect Read file paths into episode on flush
  -> Spawn LLM episode worker for significant episodes
  -> Error-triggered recall: search memory for related past fixes

UserPromptSubmit (two parallel paths)
  -> [user-prompt-search.js] Auto-search memory via FTS5 + active file context
  -> [user-prompt-search.js] Inject relevant past observations with recency/importance weighting
  -> [user-prompt-search.js] Write injected IDs to temp file for dedup
  -> [user-prompt-search.js] L1 skill auto-load: match managed skill names in prompt
     -> Load content with portable ~ path + Read() guidance
     -> source="managed-skill|managed-agent", path="~/.claude-mem-lite/managed/..."
  -> [hook.mjs handleUserPrompt] Capture user prompt text to user_prompts table
  -> [hook.mjs handleUserPrompt] Increment session prompt counter
  -> [hook.mjs handleUserPrompt] Handoff: detect continuation intent → inject previous session context
  -> [hook.mjs handleUserPrompt] Semantic memory injection (hook-memory.mjs), deduped via temp file

Stop
  -> Flush final episode buffer
  -> Save handoff snapshot (on /exit)
  -> Mark session completed
  -> Spawn LLM summary worker (poll-based wait)

The resource registry (registry.mjs, registry-retriever.mjs) indexes installed skills and agents into a searchable FTS5 database. Unlike the previous proactive dispatch system, the registry is now on-demand — Claude searches it via the mem_registry MCP tool when it needs to discover relevant skills or agents.

Registry pipeline:
  -> registry-scanner.mjs discovers skills/agents on filesystem
  -> resource-discovery.mjs handles flat dirs, plugin nesting, loose .md files
  -> registry-indexer.mjs indexes content into FTS5 with metadata
  -> registry-retriever.mjs provides BM25-ranked search with synonym expansion
  -> mem_registry MCP tool exposes search/list/stats/import/remove/reindex actions

Smart invocation (three layers):
  L1 auto-load: UserPromptSubmit matches managed skill name in prompt
     -> Loads content with path="~/.claude-mem-lite/managed/.../SKILL.md"
     -> Guides: Read("path") or mem_use(name="..."), never Skill()
  L2 bridge: PreToolUse hook intercepts Skill("name") for managed resources
     -> Outputs content, prevents native handler failure
  L3 explicit: mem_use(name="...") loads full content with reload path
  Search: managed resources → Read(path), native plugins → Skill("full:name")

Composite scoring for search results: BM25 relevance (40%) + repo stars (15%) + success rate (15%) + adoption rate (10%) + freshness (10%) + exploration bonus (10%). Domain filtering ensures platform-specific resources (iOS, Go, Rust) only surface for matching projects.

Episodes are batched related operations (edits to the same file group) that get processed by a background LLM worker:

Episode buffer -> Flush to JSON -> claude -p --model haiku -> Structured observation -> SQLite

Each observation includes type, title, narrative, concepts, facts, importance (1-3), and is automatically deduplicated via two tiers: Jaccard similarity (>70% within 5 minutes) and MinHash signatures (>80% within 7 days across sessions). If the LLM call fails, a degraded observation is saved with inferred metadata (zero data loss). Related observations are linked via related_ids based on FTS5 title similarity and file overlap.

# Plugin install:
/plugin install claude-mem-lite       # Install / update
/plugin uninstall claude-mem-lite     # Uninstall

# git clone install:
node install.mjs install              # Install and configure
node install.mjs uninstall            # Remove (keep data)
node install.mjs uninstall --purge    # Remove and delete all data
node install.mjs status               # Show current status
node install.mjs doctor               # Diagnose issues
node install.mjs cleanup-hooks        # Remove only stale claude-mem-lite hooks from settings.json
node install.mjs update               # Force-check for updates and install them (direct install / npx mode)

# npx install:
npx claude-mem-lite                   # Install / reinstall
npx claude-mem-lite uninstall         # Remove (keep data)
npx claude-mem-lite doctor            # Diagnose issues

Notes:

• Plugin mode only reports available updates; it does not self-update plugin files.
• Direct install / npx mode keeps auto-update enabled and uses staged replacement with rollback on install failure.
• If you disabled the plugin but still have old mem hooks in ~/.claude/settings.json, run node install.mjs cleanup-hooks.

Checks Node.js version, dependencies, server/hook files, database integrity, FTS5 indexes, and stale processes.

Shows MCP registration, hook configuration, plugin disabled state, and database stats (observation/session counts).

# Plugin:
/plugin uninstall claude-mem-lite

# git clone:
cd claude-mem-lite
node install.mjs uninstall            # Keeps ~/.claude-mem-lite/ data
node install.mjs uninstall --purge    # Deletes ~/.claude-mem-lite/ and all data

# npx:
npx claude-mem-lite uninstall
npx claude-mem-lite uninstall --purge

Data in ~/.claude-mem-lite/ is preserved by default. Delete manually if needed:

rm -rf ~/.claude-mem-lite/

claude-mem-lite/
  .claude-plugin/
    plugin.json      # Plugin manifest
    marketplace.json # Marketplace catalog
  .mcp.json          # MCP server definition (plugin root)
  hooks/
    hooks.json       # Hook definitions (plugin mode)
  commands/
    mem.md           # /mem command definition
  server.mjs           # MCP server: tool definitions, FTS5 search, database init
  server-internals.mjs # Extracted search helpers: re-ranking, PRF, concept expansion
  hook.mjs             # Claude Code hooks: episode capture, error recall, session management
  hook-llm.mjs         # Background LLM workers: episode extraction, session summaries
  hook-shared.mjs      # Shared hook infrastructure: session management, DB access, LLM calls
  hook-handoff.mjs     # Cross-session handoff: state extraction, intent detection, injection
  hook-context.mjs     # CLAUDE.md context injection and token budgeting
  hook-episode.mjs     # Episode buffer management: atomic writes, pending entry merging
  hook-memory.mjs      # Semantic memory injection on user prompt
  hook-semaphore.mjs   # LLM concurrency control: file-based semaphore for background workers
  schema.mjs           # Database schema: single source of truth for tables, migrations, FTS5
  tool-schemas.mjs     # Shared Zod schemas for MCP tool validation
  tfidf.mjs            # TF-IDF vector engine: tokenization, vocabulary building, vector computation, cosine similarity, RRF merge
  tier.mjs             # Temporal tier system: activity-based time window classification
  utils.mjs            # Re-export hub: backward-compatible surface for all utility modules
  nlp.mjs              # FTS5 query building: synonym expansion, CJK bigrams, sanitization
  scoring-sql.mjs      # BM25 weight constants and type-differentiated decay half-lives
  stop-words.mjs       # Shared base stop-word set for all NLP/search modules
  synonyms.mjs         # Unified synonym source: SYNONYM_MAP (bidirectional) + DISPATCH_SYNONYMS
  project-utils.mjs    # Shared project name resolution with in-process cache
  secret-scrub.mjs     # API key, token, PEM, and credential pattern redaction
  format-utils.mjs     # String formatting: truncate, typeIcon, date/time/week formatting
  hash-utils.mjs       # MinHash signatures, Jaccard similarity for dedup
  bash-utils.mjs       # Bash output significance detection: errors, tests, builds, deploys
  # Resource registry
  registry.mjs         # Resource registry DB: schema, CRUD, FTS5, invocation tracking
  registry-retriever.mjs # FTS5 retrieval with synonym expansion and composite scoring
  registry-indexer.mjs # Resource indexing pipeline
  registry-scanner.mjs # Filesystem scanner: reads content + hashes, delegates discovery
  resource-discovery.mjs # Shared discovery layer: flat dirs, plugin nesting, loose .md files
  haiku-client.mjs     # Unified Haiku LLM wrapper: direct API or CLI fallback
  # Install & config
  install.mjs          # CLI installer: setup, uninstall, status, doctor (npx/git clone mode)
  skill.md             # MCP skill definition (npx/git clone mode)
  package.json         # Dependencies and metadata
  scripts/
    setup.sh           # Setup hook: npm install + migration (hidden dir + old dir)
    post-tool-use.sh   # Bash pre-filter: skips noise in ~5ms, tracks Read paths
    user-prompt-search.js # UserPromptSubmit hook: auto-search memory + L1 skill auto-load
    pre-skill-bridge.js  # PreToolUse hook: L2 skill bridge for managed resources
    pre-tool-recall.js   # PreToolUse hook: file lesson recall before Edit/Write
    prompt-search-utils.mjs # Shared logic: skip patterns, intent detection, name matching
    convert-commands.mjs # Converts command .md → SKILL.md in managed plugins
    index-managed.mjs  # Offline indexer for managed resources
  # Test & benchmark (dev only)
  tests/               # Unit, property, integration, contract, E2E, pipeline tests
  benchmark/           # BM25 search quality benchmarks + CI gate

Benchmarked on 200 observations across 30 queries (standard + hard-negative categories):

The benchmark suite runs as a CI gate (npm run benchmark:gate) to prevent search quality regressions.

npm run lint              # ESLint static analysis
npm test                  # Run full test suite (vitest)
npm run test:smoke        # Run 5 core smoke tests
npm run test:coverage     # Run tests with V8 coverage (≥75% lines/functions, ≥65% branches)
npm run benchmark         # Run full search quality benchmark
npm run benchmark:gate    # CI gate: fails if metrics regress beyond 5% tolerance

MIT