Imported from DevEstacion/light-mem (AGENTS.md). Install upstream with npx skills add DevEstacion/light-mem. Copyright stays with the author.

light-mem

Lightweight persistent memory system for Claude Code, Grok, Codex, and OpenCode. It captures tool-usage observations via lifecycle hooks (Claude Code, Grok, Codex) or an OpenCode plugin, compresses them into searchable summaries with the Claude Agent SDK (default) or a direct Messages API call, embeds them in-process (potion-base-8M + BM25 hybrid search), and injects relevant context into future sessions. TypeScript, Node ≥24, esbuild-bundled worker, SQLite via the built-in node:sqlite.

Commands

npm run build              # sync-plugin-manifests + build-hooks (esbuild bundle + Rule A verify)
npm run build-and-sync     # build, sync to marketplace, restart worker
npm run typecheck          # tsc --noEmit (root + viewer)
npm test                   # vitest run  — MUST run under Node 24 (see AI Instructions)
npm run lint:hook-io       # hook IO-discipline guard
npm run lint:spawn-env     # spawn-env discipline guard
npm run smoke:clean-room   # fresh-install dependency-closure smoke test

Detailed command docs: file:docs/commands.md:BUILD, file:docs/commands.md:TEST, file:docs/commands.md:LOCAL_DEV.

See file:docs/migrating-from-claude-mem.md for moving an existing claude-mem SQLite database to light-mem.

Architecture

Hooks (plugin/hooks/hooks.json) launch a Node worker (worker-service.cjs) that owns a SQLite DB and an MCP search server. Source lives in src/; plugin/ is build output.

See file:docs/architecture.md:OVERVIEW for the system design. See file:docs/architecture.md:DIAGRAM_OVERVIEW for the architecture diagram. See file:docs/architecture.md:COMPONENTS for component responsibilities. See file:docs/claude-providers.md for the SDK vs API provider choice. See file:docs/opencode.md for the OpenCode plugin install flow (covers ocx-managed profiles). See file:docs/architecture.md:SERVER_RUNTIME for the optional multi-tenant server runtime (beta).

Conventions

See file:docs/conventions.md:STYLE for code conventions. See file:docs/conventions.md:TESTING for test patterns (Vitest, Node 24).

Workflows

See file:docs/workflows.md:CONTRIBUTING for the change workflow. See file:docs/workflows.md:RELEASE for the version-bump + release process. See file:docs/workflows.md:DAILY_MAINTENANCE for the dependency-upgrade routine.

AI Instructions

• Tests and the worker require Node ≥24 (built-in node:sqlite). Under an older Node (e.g. nvm default 20) tests crash at DatabaseSync import. Run nvm use 24 first.
• Do NOT hand-edit plugin/ — it is esbuild/build output. Edit src/ and run npm run build. The bundled plugin/scripts/*.cjs are generated.
• Do NOT hand-edit plugin/hooks/hooks.json or plugin/.mcp.json — the build verifies them byte-exact against the canonical template in scripts/build-hooks.js (shellTemplateManifest). Change the generator, then rebuild. This is "Rule A".
• plugin/scripts/node-runner.js is the hook launcher (an ES module). It must NOT use bare require() (throws a swallowed ReferenceError in ESM) and must NOT use ?./?? (it parses on pre-ES2020 Node). See src/build/hook-shell-template.ts.
• Model ids must be provider-valid. On Bedrock, Direct-API ids (e.g. claude-haiku-4-5-20251001) 400; use portable aliases (haiku/sonnet/opus) or global.anthropic.* ids. See src/npx-cli/install/bedrock-models.ts:1.
• Do NOT edit the changelog — it is generated automatically.
• Version is single-source from package.json. Never hand-edit a version in another manifest or the .cjs. Bump via npm run version:bump[:minor|:major] (runs sync-plugin-manifests.js), then npm run build. The pre-commit hook blocks commits where the version has drifted across manifests or the built .cjs. See file:docs/workflows.md:RELEASE.
• New worker model wiring goes through src/services/worker/ClaudeProvider.ts:500 (getModelId → resolveTierAlias). If you add a new provider, follow the same pattern in src/services/worker/ClaudeApiProvider.ts:58 (startSession signature must match ClaudeProvider.startSession(session, worker?) — see docs/claude-providers.md).
• The Setup hook almost never fires — only claude --init-only / -p --init, NOT on normal launch, install, update, or /reload-plugins. Per-launch work (e.g. the tree-sitter CLI binary backfill in plugin/scripts/version-check.js) must run on SessionStart, backgrounded via nohup … >/dev/null 2>&1 & so it never blocks the 60s hook timeout. Setup is retained only for the fresh-install path. The background flag is generated by buildShellCommand in src/build/hook-shell-template.ts:1 (Rule A). Use nohup, never setsid — it is absent on macOS.
• Hook matchers are now Rule-A-verified. plugin/hooks/hooks.json still hand-authors matcher/timeout/statusMessage, but the matchers map in shellTemplateManifest (scripts/build-hooks.js) is asserted against the file by verifyShellTemplateCanonical, so changing a matcher means editing both. PreToolUse is scoped to Read|read_file (Claude Code Read, Grok read_file) so the file-context hook stops spawning a worker subprocess on every tool call. Pipe-separated exact-match matchers work on all Claude Code versions; only comma/hyphen matcher syntax needs Claude Code ≥ 2.1.195 (there is no minAppVersion field in the plugin manifest schema to enforce a floor).
• Observation capture diverges by host (PostToolBatch). Claude Code's hooks.json uses PostToolBatch (subcommand observation-batch, src/cli/handlers/observation-batch.ts) — one hook per resolved batch of tool calls instead of one PostToolUse per tool, cutting worker spawns to ~one per model turn. Requires a Claude Code new enough to emit PostToolBatch (no changelog pins the exact version and there is no manifest floor to enforce it; on an older build the event simply never fires and capture silently stops — advisory only). Grok reads this same hooks.json but has no PostToolBatch event and silently skips unknown event keys (verified in xai-org/grok-build crates/codegen/xai-grok-hooks/src/config.rs), so Grok gets its per-tool PostToolUse observation hook from ~/.grok/hooks/light-mem.json, installed by GrokInstaller from the generated plugin/hooks/grok-hooks.json. Codex keeps PostToolUse in codex-hooks.json. Editing the observation hook means touching the generator for all three (shellTemplateManifest, writeGrokHooksJson, writeCodexHooksJson in scripts/build-hooks.js).

Research

• API-provider resilience design: file:docs/superpowers/specs/2026-06-17-claude-api-provider-resilience-design.md