claude-mem-lite

Lightweight persistent memory for Claude Code — no daemon, no child processes, zero zombie risk.

Every Claude Code session is short-lived and independent. Your memory persists across sessions in SQLite, and is injected automatically when a new session starts.

Why "lite"?

The original claude-mem uses a background Worker daemon (Express on port 37777), ChromaDB via MCP stdio, and the Claude Agent SDK for AI compression. On Windows, any shutdown path that doesn't complete cleanly leaves zombie processes.

claude-mem-lite eliminates all of that:

| | claude-mem | claude-mem-lite | |---|---|---| | Daemon process | Express worker on 37777 | None | | Child processes | ChromaDB MCP, Agent SDK | None | | Zombie risk | Multiple layers | Zero | | AI compression | Claude Agent SDK (spawn) | Direct HTTP API call | | Semantic search | ChromaDB (Python/MCP) | Transformers.js (in-process ONNX) | | Dependencies | ~80 | 4 |

How it works

Each hook invocation is a short-lived Node.js process that opens SQLite, does its work, and exits. No process stays alive between hooks.

SessionStart       → open SQLite → FTS5 search + vector search → inject context via stderr → exit (< 1s)
UserPromptSubmit   → open SQLite → INSERT prompt → exit (< 0.1s)
PostToolUse        → open SQLite → INSERT observation → compute embedding → exit (< 0.5s)
SessionEnd         → open SQLite → AI compress observations → generate summary → exit (< 15s)

Architecture

claude-mem-lite/
├── src/
│   ├── hooks/            # 4 lifecycle hooks
│   │   ├── session-start.ts    # Context injection
│   │   ├── post-tool-use.ts    # Observation capture
│   │   ├── user-prompt.ts      # Prompt capture
│   │   └── session-end.ts      # AI compression + summary
│   ├── db/               # SQLite operations
│   │   ├── schema.ts           # Tables, migrations
│   │   ├── observations.ts     # CRUD
│   │   ├── sessions.ts         # CRUD
│   │   ├── search.ts           # FTS5 keyword search
│   │   ├── vectors.ts          # Embedding + JS cosine similarity
│   │   └── ...
│   ├── ai/               # AI processing (direct HTTP, no spawn)
│   │   ├── compress.ts         # Observation compression
│   │   └── summarize.ts        # Session summarization
│   └── cli/              # Query CLI commands
├── plugin/               # Installed plugin files
│   ├── hooks/hooks.json
│   ├── scripts/hook-runner.cjs   # Built bundle
│   └── skills/mem-search/
└── package.json

Installation

cd claude-mem-lite
npm install
npm run build-and-sync

This builds the plugin and syncs it to ~/.claude/plugins/claude-mem-lite/.

Configuration

Settings are in ~/.claude-mem/settings.json (shared with original claude-mem):

{
  "CLAUDE_MEM_PROJECT": "my-project",
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "50",
  "compress_key": "your-api-key",
  "compress_url": "https://api.openai.com/v1",
  "compress_model": "gpt-4o-mini"
}

• compress_key / compress_url / compress_model — API credentials for AI compression and summarization. Any OpenAI-compatible API works.
• If no API key is set, heuristic compression is used as fallback (extracts file paths, tool names, key values).

Hook chain

1. SessionStart — Context injection

When a new Claude Code session starts, this hook:

1. Creates a new session record in SQLite
2. Cleans up stale sessions (> 24h old, still marked "active")
3. Gathers context from the database:
   • Recent session summaries (highest priority)
   • Semantic search results — uses Transformers.js to compute query embedding, then cosine similarity against stored vectors
   • Keyword search results — FTS5 BM25 ranking
   • Recent observations (lowest priority)
4. Assembles context within a ~2000 token budget, truncating lower-priority sections first
5. Outputs the context block via stderr (Claude Code feeds stderr to the model)

2. UserPromptSubmit — Prompt capture

Records the user's prompt text for session context.

3. PostToolUse — Observation capture

After each tool use, this hook:

1. Parses tool name, input, and output from stdin
2. Classifies the observation type (action / change / discovery / decision)
3. Generates a descriptive title (e.g. Edit: schema.ts, Run: npm test, Grep: "zombie" in src/)
4. Stores the observation in SQLite
5. Computes an embedding vector asynchronously and stores it for future semantic search

4. SessionEnd — AI compression + summary

When the session ends, this hook:

1. Compresses raw observations — batches of 10 observations are sent to the AI API, which extracts structured facts (JSON array) and narrative (concise summary). This replaces raw Input: {...} Output: {...} with searchable, dense information.
2. Generates a session summary — all compressed observations are summarized into a structured markdown document covering the request, key decisions, changes made, and issues.
3. Falls back to heuristic compression if no API key is configured.

CLI commands

# Search past observations
mem-search --query "zombie worker" --limit 10 --mode keyword
mem-search --query "database schema" --limit 5 --mode semantic

# Browse observations
mem-observations --limit 20
mem-observations --project my-project --offset 10

# View sessions
mem-sessions --limit 10

# View summaries
mem-summaries --limit 5

# View prompts
mem-prompts --limit 10 --project my-project

# Statistics
mem-stats

# Project list
mem-projects

Backfill commands

If you have existing observations from the original claude-mem, you can backfill AI compression and vector embeddings:

# Backfill AI compression for lite observations missing facts
mem-backfill --limit 200

# Backfill vector embeddings for all observations missing them
node plugin/scripts/hook-runner.cjs vector-backfill --limit 500 --batch-size 50

# Dry run (just count)
mem-backfill --dry-run
node plugin/scripts/hook-runner.cjs vector-backfill --dry-run

Database

SQLite at ~/.claude-mem/claude-mem.db, shared with the original claude-mem. Lite is fully compatible — it reads and writes the same observations, sdk_sessions, session_summaries, and user_prompts tables.

Key tables:

• observations — tool use records with facts, narrative, concepts columns (AI-compressed)
• observations_fts — FTS5 virtual table for keyword search
• observation_embeddings — BLOB column for vector search (384-dim, all-MiniLM-L6-v2)
• sdk_sessions — session records
• session_summaries — AI-generated session summaries

Semantic search

Uses Transformers.js with the all-MiniLM-L6-v2 model (~28MB ONNX, downloaded on first use to ~/.claude-mem/models/). Embeddings are computed entirely within the Node.js process — no Python, no MCP, no child processes.

Search pipeline:

1. Compute query embedding (~50ms)
2. Load all observation embeddings for the project from SQLite
3. Compute cosine similarity in JavaScript
4. Return top-k results

For personal databases (< 10k observations), this is fast enough and completely eliminates the ChromaDB dependency chain.

Privacy

Wrap any content in <private>...</private> tags to prevent it from being stored. The hook layer strips these tags before data reaches the database.

Development

npm run build          # Build to plugin/scripts/hook-runner.cjs
npm run build-and-sync # Build + sync to installed plugin dir
npm run sync           # Sync plugin/ to ~/.claude/plugins/claude-mem-lite/
npm run dev            # Build with sourcemaps + sync

License

MIT