claude-mem-lite MCP工具

Requirements

• Node.js >= 22
• Claude Code CLI installed and configured (claude command available)
• SQLite3 support (provided by better-sqlite3 13, which ships prebuilt binaries for 8 platforms — no compiler needed on any of them; a platform it has no prebuild for falls back to building from source)
• Platform: Linux or macOS; Windows installs and runs but is not CI-covered and needs Git Bash or WSL for three hooks (see Platform Support)

Installation

What happens during installation

1. Install dependencies -- npm install --omit=dev (compiles native better-sqlite3)
2. Register MCP server -- mem-lite server with 18 tools (9 core exposed via tools/list + 9 hidden-but-callable; see the Usage section for the full table). The pre-v2.78 generic server name mem is renamed to mem-lite for namespace hygiene; the tool names themselves (mem_search, mem_recall, ...) are unchanged.
3. Configure hooks -- all seven lifecycle events: SessionStart, PreCompact, PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit
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.

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.
  To upgrade an installed plugin to the latest published version, run **inside Claude Code**:
  

  (The first command refreshes the local marketplace clone; the second reinstalls from it. Without the first command, `/plugin install` reuses the stale local clone and you stay on whichever version you originally pulled.)
- 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`.

#### Trust model per install path

The three install paths do **not** carry the same supply-chain guarantees — pick the one that matches your threat model:

| Path | Update mechanism | Ed25519 release-signature verification |
|------|------------------|----------------------------------------|
| npm / npx / git-clone direct install | auto-update from GitHub Releases | **Yes** — every runtime file (140 entries incl. hook scripts, MCP launcher, plugin declaration files) is hash-pinned in a signed manifest; verification is fail-closed |
| `/plugin install` (marketplace) | manual `/plugin marketplace update` + reinstall | **No** — Claude Code installs from a git clone of the marketplace repo; the plugin's own signature chain is not consulted on this path. You are trusting GitHub + the repo's branch protection, not the release signing key |

**Rollback recipe (plugin path).** If an update misbehaves, pin the marketplace clone to the previous release tag and reinstall from it:

3. Reinstall from the pinned clone — inside Claude Code:

/plugin install claude-mem-lite@sdsrss

Recovery (stuck install / hook errors)

If you see ERR_MODULE_NOT_FOUND on PreToolUse:Read/Edit hooks, or claude-mem-lite commands crash with import errors, you're likely hit by a partial auto-update — the updater copied new scripts but missed a sibling lib/* file, breaking the hook chain (and the next auto-update that would have healed it).

v2.84.0+ ships a repair subcommand that re-syncs from the latest GitHub release:

claude-mem-lite repair

If repair itself fails (the bin is older than v2.84.0, or the bin is also broken), run this one-liner — it pulls a fresh tarball into a temp dir and runs that tarball's install.mjs, bypassing every file on your disk:

T=$(mktemp -d) && U=$(curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/releases/latest | grep -o '"tarball_url"[^,]*' | cut -d'"' -f4) && curl -sL "$U" | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install

It resolves the latest release tag first. A shell one-liner cannot verify the release signature the way repair does, so running it is a trust decision you are making explicitly — that is why it is the last resort and not the first suggestion.

After it finishes, ~/.claude-mem-lite/ is back in sync with the latest release and claude-mem-lite repair is available for next time.

Uninstall

```bash

Mixed-install residue (read this if you've used multiple install methods)

/plugin uninstall only removes the plugin manifest — it does not touch ~/.claude/settings.json. If you've ever run claude-mem-lite install (npx or git-clone path), hook entries pointing at ~/.claude-mem-lite/hook.mjs were written into your user-global settings, and they keep firing after /plugin uninstall. If ~/.claude-mem-lite/hook.mjs still exists they double-fire alongside the plugin; if you also ran rm -rf ~/.claude-mem-lite/ they error every session.

The safe sequence is: run claude-mem-lite uninstall first (which cleans the settings.json hooks plus the global MCP registration), then /plugin uninstall claude-mem-lite, then optionally rm -rf ~/.claude-mem-lite/.

If you already uninstalled in the wrong order, claude-mem-lite doctor flags orphan hooks under Orphan hooks: with the exact cleanup command.

Usage

Environment Variables

Every environment variable the shipped code reads is listed below, grouped by what it controls. Booleans accept 1 unless noted. Anything not listed here is not read by claude-mem-lite.

Method 1: Plugin Marketplace (recommended)

/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.

The plugin install is complete on its own — hooks, MCP tools, and the bundled slash commands (/mem, /lesson, /bug, /adopt) all run from the plugin with no second step. The slash commands invoke the bundled CLI by an absolute path resolved from the plugin directory (${CLAUDE_PLUGIN_ROOT}/cli.mjs <cmd>), so they work without anything on your PATH. A global claude-mem-lite shell command (for running queries yourself in a terminal) is optional — npm i -g claude-mem-lite — and is a separate npm install: the plugin's auto-update does not refresh it, so re-run npm i -g claude-mem-lite@latest if you want that shell command kept in sync. You do not need it for the plugin to be fully functional.

Auto-adopt writes into your project, on every SessionStart (v3.13+). The plugin adds a slug-scoped managed block to your project's own <cwd>/CLAUDE.md — a file that is normally committed to git — plus a <cwd>/.claude/plugin_claude_mem_lite.md detail file. The block is a system-authority pointer that boosts Claude's proactive use of mem_recall / mem_save. Everything outside the block is preserved verbatim, and it coexists with other plugins' blocks in the same file (details). This happens on every SessionStart, not just the first: the sync is idempotent and re-applies the block if it is edited away, and refreshes it when the shipped template changes. It applies regardless of install path (npm, npx, /plugin, manual), so no manual /adopt is needed. Opt out per project with claude-mem-lite adopt --disable (--enable to re-arm), globally with export MEM_NO_AUTO_ADOPT=1, or freeze an already-adopted block against template refreshes with CLAUDE_MEM_NO_TEMPLATE_REFRESH=1. claude-mem-lite unadopt removes the block and the detail file. Manual /adopt remains available for re-applying after edits and for the --all batch path.

Efficient Search Workflow

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

Hook Pipeline

SessionStart
  -> Read the host's `source` (startup | clear | compact | resume) from stdin
  -> On clear/compact: read the outgoing session from the session file, save its
     'clear' handoff, emit the Working State block  (R10-P1-1, fixed v5.4.0)
  -> Generate session ID (overwrites the session file)
  -> 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
  -> [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 (type 'exit')
  -> Mark session completed
  -> Spawn LLM summary worker (poll-based wait)
  -> Keep the session file  <- Stop fires per TURN; deleting it here re-minted a mem
     session every turn and left the SessionStart /clear branch unreachable (v5.4.0)

Plugin:

/plugin uninstall claude-mem-lite

Architecture comparison

Quality comparison

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.