@lossless-claude/lcm 0.2.0

package/.claude-plugin/commands/lcm-compact.md

@@ -0,0 +1,31 @@
+---
+name: lcm-compact
+description: Compact conversation messages into DAG summary nodes.
+user_invocable: true
+---
+
+# /lcm-compact
+
+Compact unprocessed conversation messages into summarized DAG nodes.
+
+## Instructions
+
+Run the following command via Bash:
+
+```bash
+lcm compact --all
+```
+
+### Options
+
+If the user specifies options, append them to the command:
+- `--verbose` — Show per-conversation details
+- `--dry-run` — Preview without writing
+
+For example:
+- `/lcm-compact --verbose` → `lcm compact --all --verbose`
+- `/lcm-compact --dry-run` → `lcm compact --all --dry-run`
+
+Display the output verbatim.
+
+**Note:** `lcm compact` without `--all` falls through to hook dispatch (PreCompact). This command always uses the batch path with `--all`.

package/.claude-plugin/commands/lcm-curate.md

@@ -0,0 +1,31 @@
+---
+name: lcm-curate
+description: "Run the full memory curation pipeline: import, compact, and promote."
+user_invocable: true
+---
+
+# /lcm-curate
+
+Run the full memory curation pipeline: import, compact, and promote.
+
+## Instructions
+
+Run the following commands sequentially via Bash:
+
+```bash
+lcm import --all && lcm compact --all && lcm promote
+```
+
+### Options
+
+If the user specifies options, append them to all three commands:
+- `--verbose` — Show per-step details
+- `--dry-run` — Preview without writing
+
+For example:
+- `/lcm-curate --verbose` → `lcm import --all --verbose && lcm compact --all --verbose && lcm promote --verbose`
+- `/lcm-curate --dry-run` → `lcm import --all --dry-run && lcm compact --all --dry-run && lcm promote --dry-run`
+
+The pipeline stops on the first failure and reports the result.
+
+Display the output verbatim.

package/.claude-plugin/commands/lcm-diagnose.md

@@ -0,0 +1,29 @@
+---
+name: lcm-diagnose
+description: Scan recent Claude Code session transcripts for hook failures, MCP disconnects, and stale lcm hook setup.
+user_invocable: true
+---
+
+# /lcm-diagnose
+
+Inspect recent Claude Code transcripts for historical lcm issues.
+
+## Instructions
+
+Run `lcm diagnose` via Bash and display the output verbatim.
+
+If the user asks for a wider scan, use:
+- `lcm diagnose --all`
+- `lcm diagnose --all --days 30`
+- `lcm diagnose --verbose`
+- `lcm diagnose --json`
+
+After showing the results, suggest the next troubleshooting step:
+- `lcm doctor` for current install health
+- `lcm import` if sessions were missed and need recovery
+
+## When to use
+
+- After seeing hook errors in a Claude Code session
+- When investigating missing sessions or gaps in ingestion
+- During troubleshooting: `lcm doctor` for current state, `lcm diagnose` for history, `lcm import` for recovery

package/.claude-plugin/commands/lcm-doctor.md

@@ -0,0 +1,23 @@
+---
+name: lcm-doctor
+description: Run lossless-claude diagnostics — checks daemon, hooks, MCP server, and summarizer health.
+user_invocable: true
+---
+
+# /lcm-doctor
+
+Run diagnostics on the lossless-claude installation.
+
+## Instructions
+
+When invoked, call the `lcm_doctor` MCP tool (no arguments).
+
+The tool returns pre-formatted markdown with status tables per section. Display the output verbatim — it is already formatted correctly.
+
+If any check shows a failure icon, add a **Fix** section listing specific remediation steps for each failure.
+
+End with one of:
+- *All checks passed — lossless-claude is healthy.*
+- *N check(s) need attention — see Fix section above.*
+
+If `lcm_doctor` is unavailable, run `lcm doctor` via Bash and display the output verbatim.

package/.claude-plugin/commands/lcm-dogfood.md

@@ -0,0 +1,101 @@
+---
+name: lcm-dogfood
+description: Run the lcm self-test suite — validates all CLI commands, hooks, MCP tools, and resilience across 39 checks in 10 phases.
+user_invocable: true
+---
+
+# lcm Dogfood — Live Self-Test Suite
+
+Comprehensive self-test for the lcm system in a live Claude Code session. Covers all 9 CLI commands, 4 hooks, 8 MCP tools, and resilience scenarios across 39 checks in 10 phases.
+
+**Arguments:** `all` (default), `health`, `import`, `compact`, `promote`, `sensitive`, `pipeline`, `hooks`, `mcp`, `resilience`, `debug`
+
+## Procedure
+
+Execute each phase in order (or just the requested phase). For each check:
+
+1. Run the command or verify the condition
+2. Record: ✅ PASS, ❌ FAIL, or ⚠️ SKIP (with reason)
+3. On FAIL: capture error, check daemon logs (`~/.lossless-claude/daemon.log`), continue
+4. Produce the **Scorecard** at the end
+5. Write failures to `.xgh/reviews/dogfood-YYYY-MM-DD.md`
+
+**Routing:** Use `ctx_execute` (context-mode sandbox) for commands producing large output. Use Bash for short-output commands. Use MCP tools directly for Phase 8.
+
+Consult `references/checks.md` for detailed pass/fail criteria for each check.
+
+## Phase Overview
+
+| # | Phase | Checks | What it tests |
+|---|-------|--------|---------------|
+| 1 | Health | 3 | Daemon status, doctor, version |
+| 2 | Import | 3 | Transcript ingestion + idempotency |
+| 3 | Compact | 3 | Summarization + idempotency |
+| 4 | Promote | 2 | Insight extraction + stats consistency |
+| 5 | Sensitive | 5 | Pattern list/test/add/remove cycle |
+| 6 | Pipeline | 2 | Full curate + diagnose |
+| 7 | Hooks | 6 | Wiring verification + live tests |
+| 8 | MCP | 8 | All 7 MCP tools + store-retrieve roundtrip |
+| 9 | Resilience | 3 | Kill/restart/graceful degradation |
+| 10 | Debug | 4 | Logs, PWD, DB existence, integrity |
+
+## Key Commands
+
+All CLI checks use `node dist/bin/lcm.js <subcommand>`. If `lcm` is on PATH, use that instead.
+
+### Hook Verification
+
+Hooks are registered in `.claude-plugin/plugin.json`, NOT `~/.claude/settings.json`. Verify all 4:
+- `SessionStart` → `lcm restore`
+- `UserPromptSubmit` → `lcm user-prompt`
+- `PreCompact` → `lcm compact`
+- `SessionEnd` → `lcm session-end`
+
+For live hook testing, pipe JSON to stdin:
+```bash
+echo '{}' | node dist/bin/lcm.js restore
+```
+
+The UserPromptSubmit hook requires `prompt` and `cwd` fields:
+```bash
+node -e 'console.log(JSON.stringify({prompt:"test query",cwd:process.cwd()}))' | node dist/bin/lcm.js user-prompt
+```
+
+### MCP Tool Testing
+
+Call lcm MCP tools directly from the session. All 8 tools to test:
+`lcm_doctor`, `lcm_stats`, `lcm_search`, `lcm_grep`, `lcm_store`, `lcm_expand`, `lcm_describe` + store-retrieve roundtrip.
+
+## Scorecard Template
+
+```
+| Phase       | Checks | ✅ Pass | ❌ Fail | ⚠️ Skip/Known |
+|-------------|--------|---------|---------|---------------|
+| Health      | 3      |         |         |               |
+| Import      | 3      |         |         |               |
+| Compact     | 3      |         |         |               |
+| Promote     | 2      |         |         |               |
+| Sensitive   | 5      |         |         |               |
+| Pipeline    | 2      |         |         |               |
+| Hooks       | 6      |         |         |               |
+| MCP         | 8      |         |         |               |
+| Resilience  | 3      |         |         |               |
+| Debug       | 4      |         |         |               |
+| **TOTAL**   | **39** |         |         |               |
+```
+
+For ❌ FAIL items, include: error message, daemon log excerpt, suggested fix.
+For ⚠️ KNOWN items, reference the bug number from `.claude-plugin/skills/lcm-dogfood/references/known-issues.md`.
+
+## Bundled Resources
+
+### Scripts
+
+Utility scripts for checks that require custom logic:
+- **`.claude-plugin/skills/lcm-dogfood/scripts/prompt-search-test.js`** — Test the daemon `/prompt-search` endpoint directly. Usage: `node .claude-plugin/skills/lcm-dogfood/scripts/prompt-search-test.js "query" [cwd]`
+- **`.claude-plugin/skills/lcm-dogfood/scripts/db-integrity.js`** — Check PRAGMA integrity_check on all project databases. Usage: `node .claude-plugin/skills/lcm-dogfood/scripts/db-integrity.js`
+
+### Reference Files
+
+- **`references/checks.md`** — All 39 checks with detailed pass/fail criteria, organized by phase
+- **`.claude-plugin/skills/lcm-dogfood/references/known-issues.md`** — Known bugs with root causes, affected checks, and fix status

package/.claude-plugin/commands/lcm-import.md

@@ -0,0 +1,48 @@
+---
+name: lcm-import
+description: Import Claude Code session transcripts into lcm memory
+user_invocable: true
+---
+
+# /lcm-import
+
+Import Claude Code session transcripts into lcm memory.
+
+## Instructions
+
+Run the following command via Bash:
+
+```bash
+lcm import
+```
+
+### Options
+
+If the user specifies options, append them to the command:
+- `--all` — Import all projects (default when no path given)
+- `--verbose` — Show per-session details
+- `--dry-run` — Preview without writing
+
+For example:
+- `/lcm-import --all` → `lcm import --all`
+- `/lcm-import --all --verbose` → `lcm import --all --verbose`
+- `/lcm-import --dry-run` → `lcm import --dry-run`
+
+Display the output verbatim.
+
+After importing, suggest running `lcm compact --all` to summarize the imported sessions.
+
+## When to use
+
+- After installing lcm for the first time (backfill existing sessions)
+- After a session that failed to ingest (hook error, daemon down)
+- To recover lost conversations
+- After upgrading lcm (ensure all sessions are captured)
+
+## Commands
+
+- `lcm import` — import current project's sessions
+- `lcm import --all` — import all projects
+- `lcm import --verbose` — show per-session details
+- `lcm import --dry-run` — preview without writing
+- `lcm compact --all` — summarize all uncompacted sessions (run after import)

package/.claude-plugin/commands/lcm-promote.md

@@ -0,0 +1,29 @@
+---
+name: lcm-promote
+description: Promote durable insights from summaries into cross-session memory.
+user_invocable: true
+---
+
+# /lcm-promote
+
+Promote durable insights from summaries into cross-session memory.
+
+## Instructions
+
+Run the following command via Bash:
+
+```bash
+lcm promote --all
+```
+
+### Options
+
+If the user specifies options, append them to the command:
+- `--verbose` — Show per-conversation details
+- `--dry-run` — Preview without writing
+
+For example:
+- `/lcm-promote --verbose` → `lcm promote --all --verbose`
+- `/lcm-promote --dry-run` → `lcm promote --all --dry-run`
+
+Display the output verbatim.

package/.claude-plugin/commands/lcm-sensitive.md

@@ -0,0 +1,55 @@
+---
+name: lcm-sensitive
+description: Manage sensitive patterns for lossless-claude secret redaction — list, add, remove, test, or purge patterns.
+user_invocable: true
+---
+
+# /lcm-sensitive
+
+Manage the sensitive patterns used by lossless-claude to redact secrets before storing conversation messages.
+
+## Usage
+
+```
+/lcm-sensitive list
+/lcm-sensitive add <pattern>
+/lcm-sensitive add --global <pattern>
+/lcm-sensitive remove <pattern>
+/lcm-sensitive test <text>
+/lcm-sensitive purge [--all] --yes
+```
+
+## Instructions
+
+Run the appropriate `lcm sensitive` subcommand via Bash based on the user's intent:
+
+```bash
+lcm sensitive list
+lcm sensitive add "MY_SECRET_TOKEN"
+lcm sensitive add --global "SHARED_API_KEY"
+lcm sensitive remove "OLD_PATTERN"
+lcm sensitive test "some text containing MY_SECRET_TOKEN"
+lcm sensitive purge --yes
+lcm sensitive purge --all --yes
+```
+
+### Subcommands
+
+- **list** — Show all active patterns: built-in, global, and project-specific
+- **add `<pattern>`** — Add a regex pattern to the current project's sensitive patterns file
+- **add --global `<pattern>`** — Add a pattern to the global config (applies to all projects)
+- **remove `<pattern>`** — Remove a pattern from the project's sensitive patterns file
+- **test `<text>`** — Test what gets redacted from the given text (shows `[REDACTED]` substitutions)
+- **purge** — Delete the current project's data directory (`~/.lossless-claude/projects/{hash}/`) (requires `--yes`)
+- **purge --all** — Delete all project data directories under `~/.lossless-claude/projects/` (requires `--yes`)
+
+All `purge` variants require `--yes` to confirm the destructive action.
+
+### Pattern Guidelines
+
+- Patterns are JavaScript-compatible regular expressions
+- Prefer specific token patterns (e.g., `MY_APP_SECRET_[A-Z0-9]+`) over broad ones (e.g., `MY_APP.*`)
+- Patterns containing spaces or `\s` are applied to full message text; others are applied per token
+- Built-in patterns already cover common secrets: OpenAI keys, Anthropic keys, GitHub tokens, AWS keys, PEM keys, Bearer tokens, password assignments
+
+Display the command output verbatim. If the command fails, show the error and suggest running `lcm doctor` to check installation health.

package/.claude-plugin/commands/lcm-stats.md

@@ -0,0 +1,19 @@
+---
+name: lcm-stats
+description: Show lossless-claude memory inventory, compression ratios, and DAG statistics.
+user_invocable: true
+---
+
+# /lcm-stats
+
+Show memory and compression statistics from lossless-claude.
+
+## Instructions
+
+When invoked, call the `lcm_stats` MCP tool with `{"verbose": true}`.
+
+The tool returns pre-formatted markdown with Memory and Compression tables. Display the output verbatim — it is already formatted correctly.
+
+If `lcm_stats` is unavailable, run `lcm stats -v` via Bash and display the output verbatim.
+
+Do not add commentary — just the stats output.

package/.claude-plugin/commands/lcm-status.md

@@ -0,0 +1,27 @@
+---
+name: lcm-status
+description: Show daemon state and project memory statistics.
+user_invocable: true
+---
+
+# /lcm-status
+
+Show daemon state and project memory statistics.
+
+## Instructions
+
+Run the following command via Bash:
+
+```bash
+lcm status
+```
+
+### Options
+
+If the user specifies options, append them to the command:
+- `--json` — Return output in JSON format
+
+For example:
+- `/lcm-status --json` → `lcm status --json`
+
+Display the output verbatim.

package/.claude-plugin/hooks/README.md

@@ -0,0 +1,47 @@
+# lossless-claude — Hooks
+
+**Usage**: Lossless context management — every conversation is captured, compressed, and restored across sessions.
+
+## Hooks
+
+All hooks auto-heal: each validates that all 4 hooks are registered in `settings.json` before executing. If any are missing, they're silently repaired.
+
+| Hook | Command | What it does |
+|------|---------|-------------|
+| PreCompact | `lcm compact` | Intercepts compaction, runs LLM summarization into a DAG, returns the summary (exit 2 = replace native) |
+| SessionStart | `lcm restore` | Restores project context + recent summaries + promoted memories from prior sessions |
+| SessionEnd | `lcm session-end` | Ingests the session transcript into the database for future recall |
+| UserPromptSubmit | `lcm user-prompt` | Searches promoted memory for relevant context, surfaces it as `<memory-context>` hints |
+
+## Lifecycle
+
+```
+SessionStart ──→ conversation ──→ UserPromptSubmit (each turn)
+                                         │
+                               PreCompact (if context fills)
+                                         │
+                              SessionEnd (conversation exits)
+```
+
+1. **SessionStart**: daemon wakes, orientation + episodic + promoted context injected
+2. **UserPromptSubmit**: each user message triggers a background memory search — relevant context appears as hints
+3. **PreCompact**: when Claude's context window fills, lossless-claude intercepts and produces a DAG-based summary (nothing lost)
+4. **SessionEnd**: full transcript ingested into SQLite for future sessions
+
+## MCP Tools
+
+Available alongside hooks for direct memory access:
+
+```
+lcm_search    # Search across episodic + promoted memory
+lcm_grep      # Regex/full-text search across messages + summaries
+lcm_expand    # Drill into a summary node for full detail
+lcm_describe  # Summary metadata (depth, tokens, parent/child)
+lcm_store     # Write to promoted knowledge store
+lcm_stats     # Compression ratios and usage statistics
+lcm_doctor    # Diagnostics — daemon, hooks, MCP, summarizer
+```
+
+## Why
+
+Without lossless-claude, conversation history is lost when Claude compacts or when a session ends. With it, every message is preserved in a SQLite DAG, summaries are hierarchical (leaf → condensed → session → durable), and relevant context from past sessions surfaces automatically on each prompt.

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "lossless-claude",
+  "owner": {
+    "name": "lossless-claude",
+    "url": "https://github.com/lossless-claude"
+  },
+  "plugins": [
+    {
+      "name": "lossless-claude",
+      "source": {
+        "source": "github",
+        "repo": "lossless-claude/lcm"
+      },
+      "description": "Lossless context management — DAG-based summarization that preserves every message",
+      "version": "0.1.0",
+      "strict": true
+    }
+  ]
+}

package/.claude-plugin/mcp.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// MCP entrypoint for plugin system — delegates to the built lcm MCP server.
+// Uses import.meta.url to resolve paths relative to this file, so it works
+// regardless of how the plugin cache resolves ${CLAUDE_PLUGIN_ROOT}.
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverModule = join(__dirname, "dist", "src", "mcp", "server.js");
+
+const { startMcpServer } = await import(serverModule);
+await startMcpServer();

package/.claude-plugin/plugin.json

@@ -0,0 +1,46 @@
+{
+  "name": "lossless-claude",
+  "version": "0.2.0",
+  "description": "Lossless context management — DAG-based summarization that preserves every message",
+  "author": {
+    "name": "Pedro Almeida",
+    "url": "https://github.com/ipedro"
+  },
+  "homepage": "https://lossless-claude.com",
+  "repository": "https://github.com/lossless-claude/lcm",
+  "license": "MIT",
+  "keywords": ["context", "memory", "compaction", "summarization", "lcm"],
+  "commands": "./.claude-plugin/commands/",
+  "mcpServers": {
+    "lcm": {
+      "command": "lcm",
+      "args": ["mcp"]
+    }
+  },
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "lcm compact" }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "lcm restore" }]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "lcm session-end" }]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "lcm user-prompt" }]
+      }
+    ]
+  }
+}

package/.claude-plugin/skills/lcm-context/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: lcm-context
+description: "Use when deciding which lcm MCP tool to call — lcm_search, lcm_grep, lcm_expand, lcm_describe, lcm_store, lcm_doctor, or lcm_stats — or when an lcm tool returns an error."
+---
+
+# lcm Memory Tool Guide
+
+Lossless-claude provides 7 MCP tools. This skill helps you pick the right one and recover from errors.
+
+> **Hooks already inject memory at session start.** Do NOT re-query what was already injected. This skill is for active retrieval, storage, and error recovery — not session initialization.
+
+## Tool Decision Tree
+
+### Retrieval Tools (search → grep → expand)
+
+These three tools **chain** from broad to deep:
+
+1. **lcm_search** — Broad concept recall across sessions
+   - Use: "how was auth implemented?", "what decisions were made about compaction?"
+   - Returns: ranked results from FTS5 + semantic layers
+   - Options: `tags` to filter, `layers` to scope (episodic/semantic)
+
+2. **lcm_grep** — Exact keyword/regex in raw transcripts
+   - Use: "JWT", "socket.unref", specific error messages
+   - Returns: matching messages/summaries with context
+   - Options: `scope` (messages/summaries/all), `since` date filter
+
+3. **lcm_expand** — Drill into a compressed summary node
+   - Use: when a search/grep result references a summary nodeId and you need the full content
+   - Returns: decompressed source content from the DAG
+   - Options: `depth` to control traversal levels
+
+**Chaining pattern:** Start with `lcm_search` for broad recall → use `lcm_grep` to find exact references → use `lcm_expand` to decompress interesting nodes.
+
+### Inspection Tool
+
+4. **lcm_describe** — Check a node's metadata without loading content
+   - Use: when a nodeId came from grep and you don't know if it's worth expanding. Saves tokens if the node is stale, shallow, or unrelated.
+   - Returns: depth, token count, parent/child links, promotion status
+
+### Storage Tool
+
+5. **lcm_store** — Persist a decision or finding for future sessions
+   - Use: architectural decisions, bug root causes, user preferences, integration patterns
+   - Options: `tags` for categorization, `metadata` for project/session context
+
+### Operational Tools
+
+6. **lcm_doctor** — Check system health (daemon, hooks, MCP, summarizer)
+7. **lcm_stats** — View compression ratios and token savings
+
+## When to Use / When NOT to Use
+
+### Retrieval
+**Use when:**
+- You need context that wasn't in the hook-injected summary
+- You're looking for a specific past decision or conversation
+- A summary node looks relevant but needs more detail
+
+**Do NOT use when:**
+- The information is already in your current context (hook injected it)
+- You're looking for general knowledge, not project memory
+- You can answer from code/git alone
+
+### Storage
+**Use when:**
+- An architectural decision was made with rationale worth preserving
+- A bug root cause was identified (the "why", not just the fix)
+- User expressed a preference or feedback that affects future work
+- A non-obvious integration pattern was discovered
+
+**Do NOT use when:**
+- The information is already in git (code, commit messages)
+- It's a transient debugging step or ephemeral task detail
+- It's already documented in CLAUDE.md or memory files
+- It's general knowledge, not project-specific
+
+## Error Self-Healing
+
+### Agent-Fixable (handle automatically)
+
+| Error | Recovery |
+|---|---|
+| Daemon not running | Run `lcm start` via Bash, then retry |
+| "No results" from search | Try `lcm_grep` with different keywords, or broaden the query |
+| Node not found on expand | Use `lcm_search` to find the correct nodeId |
+| Store succeeds but daemon restarted before SessionEnd | Call `lcm_doctor` to verify persistence; re-store if the node is missing |
+
+### User Action Required (surface to user)
+
+| Error | What to tell the user |
+|---|---|
+| MCP server disconnected | Restart the session, then run `/lcm-diagnose` to audit for gaps |
+| Hooks not firing | Call `lcm_doctor` to confirm; if hooks are missing, tell user to run `lcm install` |
+| Summarizer failing | Tell user to run `/lcm-doctor` for full diagnostics |
+
+## Quick Reference
+
+```
+lcm_search  → broad concept recall (FTS5 + semantic)
+lcm_grep    → exact keyword/regex match
+lcm_expand  → decompress a summary node
+lcm_describe → inspect node metadata (check before expanding)
+lcm_store   → persist decisions/findings
+lcm_doctor  → health check
+lcm_stats   → compression metrics
+```