{"id":51417680,"url":"https://github.com/offendingcommit/lossless-claude","last_synced_at":"2026-07-04T21:30:21.931Z","repository":{"id":362559130,"uuid":"1203956852","full_name":"offendingcommit/lossless-claude","owner":"offendingcommit","description":"Cross-runtime memory bridge between Claude Code and OpenClaw via the lossless-claw LCM SQLite database. MCP recall tools, PreCompact capture hook, SessionStart bootstrap, lcm-recall skill.","archived":false,"fork":false,"pushed_at":"2026-04-07T14:51:22.000Z","size":41,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T21:48:19.597Z","etag":null,"topics":["anthropic","claude-code","context-management","lcm","lossless-claw","mcp-server","memory","model-context-protocol","openclaw","sqlite","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/offendingcommit/lossless-claude","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/offendingcommit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T14:51:19.000Z","updated_at":"2026-04-17T06:37:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/offendingcommit/lossless-claude","commit_stats":null,"previous_names":["offendingcommit/lossless-claude"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/offendingcommit/lossless-claude","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Flossless-claude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Flossless-claude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Flossless-claude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Flossless-claude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/offendingcommit","download_url":"https://codeload.github.com/offendingcommit/lossless-claude/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Flossless-claude/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35136712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude-code","context-management","lcm","lossless-claw","mcp-server","memory","model-context-protocol","openclaw","sqlite","typescript"],"created_at":"2026-07-04T21:30:21.490Z","updated_at":"2026-07-04T21:30:21.926Z","avatar_url":"https://github.com/offendingcommit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lossless-claude\n\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)](CHANGELOG.md)\n[![Node](https://img.shields.io/badge/node-22%2B-brightgreen.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6.svg)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-1.x-purple.svg)](https://modelcontextprotocol.io/)\n[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#roadmap)\n\nBridges [lossless-claw](https://github.com/offendingcommit/lossless-claw) (LCM) into Claude Code as a **cross-runtime memory layer**. Sits beside Claude Code's harness and shares the OpenClaw lossless-claw SQLite database, so Claude Code sessions can read from and contribute to the same hierarchical memory store that Daphne and other OpenClaw agents use.\n\n## What this is and is not\n\n**This is:** a read-mostly memory bridge that exposes LCM recall tools to Claude Code via MCP, captures Claude Code sessions on PreCompact, and bootstraps relevant context on SessionStart.\n\n**This is not:** a replacement for Claude Code's built-in context management. Claude Code's harness still owns the active context window and decides when to compact. lossless-claude lives outside that loop, providing recall and persistence around it.\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                  Claude Code Session                    │\n│                                                         │\n│  [SessionStart hook] ──── reads ──→  ┌────────────┐    │\n│                                       │            │    │\n│  [Active context]                     │  LCM       │    │\n│  (managed by harness — opaque)        │  SQLite    │    │\n│                                       │            │    │\n│  [PreCompact hook]  ──── writes ──→   │  ~/.opencl │    │\n│                                       │  aw/lcm.db │    │\n│  [MCP tools] ───── queries ─────→     │            │    │\n│   lcm_grep, lcm_describe, lcm_stats   └────────────┘    │\n└─────────────────────────────────────────────────────────┘\n        ↑                                    ↑\n        │                                    │\n   shared with the OpenClaw runtime (Daphne, JelleeBean, etc.)\n```\n\n## Components\n\n| Component | Type | Purpose |\n|-----------|------|---------|\n| `lcm_grep` | MCP tool | FTS5/LIKE search across messages and summaries |\n| `lcm_describe` | MCP tool | Look up message or summary by ID with DAG lineage |\n| `lcm_stats` | MCP tool | Database health snapshot, prefix breakdown |\n| `lcm_expand_query` | MCP tool (stub) | v2 — full LLM-driven recursive expansion |\n| `pre-compact.sh` | Hook (PreCompact) | Captures session messages into LCM before compaction |\n| `session-start.sh` | Hook (SessionStart) | Injects recent CC + Daphne activity as bootstrap context |\n| `lcm-recall` | Skill | Teaches Claude when and how to use the recall tools |\n\n## Prerequisites\n\n- **Node 22+** — required for the MCP server (uses `better-sqlite3`)\n- **Python 3** — required for the hook scripts (uses `sqlite3` from stdlib)\n- **`~/.openclaw/lcm.db`** — must exist. Run lossless-claw at least once via OpenClaw to create it. Override with `LCM_DB_PATH` env var if you want a separate database for Claude Code.\n\n## Install\n\n```bash\n# 1. Clone\ngit clone https://github.com/offendingcommit/lossless-claude ~/lossless-claude\ncd ~/lossless-claude\n\n# 2. Build the MCP server\ncd mcp-server\npnpm install   # or npm install\npnpm build     # or npm run build\ncd ..\n\n# 3. Add to Claude Code as a plugin\n# (User-level — applies to all Claude Code sessions)\nmkdir -p ~/.claude/plugins\nln -s ~/lossless-claude ~/.claude/plugins/lossless-claude\n```\n\nAfter symlinking, restart Claude Code. The MCP server, hooks, and skill load automatically.\n\n### Verify the install\n\nIn Claude Code:\n\n```\n/mcp                    # should list \"lossless-claude\" as connected\n```\n\nThen test the tools:\n\n```\nUse lcm_stats to show me the database snapshot.\n```\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---------|---------|---------|\n| `LCM_DB_PATH` | `~/.openclaw/lcm.db` | Path to the lossless-claw SQLite database |\n| `LOSSLESS_CLAUDE_LOG` | `~/.openclaw/logs/lossless-claude.log` | PreCompact hook log file |\n| `LOSSLESS_CLAUDE_WATERMARK_FILE` | `~/.openclaw/lossless-claude-watermarks.json` | PreCompact hook watermark store. Tracks per-session-key insert counts so overlapping PreCompact firings never insert the same message twice. |\n| `LOSSLESS_CLAUDE_BOOTSTRAP_TURNS` | `12` | Max turns to inject in SessionStart bootstrap |\n| `LOSSLESS_CLAUDE_BOOTSTRAP_INCLUDE_AGENTS` | `0` | When set to `1`, include cross-runtime activity from OpenClaw agents (`agent:main:*` session keys) in the SessionStart bootstrap. OFF by default because that data can include Discord DMs and other sensitive material that should not silently leak into a new session's system prompt. |\n\n## Session keying\n\nClaude Code sessions are written to LCM with `session_key = cc:\u003cbasename(cwd)\u003e:\u003cgit-branch\u003e`. This namespaces them under `cc:` so they're easy to filter via `lcm_grep(session_key_prefix: \"cc:\")` and they don't collide with the `agent:*` keys that OpenClaw uses.\n\nExample session keys you'll see in the database:\n\n| Session key | Source |\n|-------------|--------|\n| `cc:lossless-claude:main` | This repo, working on the `main` branch in Claude Code |\n| `cc:offendingcommit-site:feature/auth` | Some other repo on a feature branch |\n| `agent:main:discord:dm:123` | Daphne in OpenClaw, in a Discord DM |\n| `agent:jellybean:discord:dm:456` | JelleeBean in OpenClaw |\n\n## Why this design\n\n- **Claude Code's harness owns the context window.** Replacing its compaction is not a supported extension point. lossless-claude works *beside* the harness, not inside it.\n- **Direct SQL instead of importing lossless-claw internals.** The lossless-claw schema is migration-versioned and stable. Importing `LcmContextEngine` would couple us to OpenClaw runtime symbols. Talking to SQLite directly via `better-sqlite3` keeps the bridge thin and decouples upgrade cycles.\n- **Read-mostly.** The MCP server is strictly read-only (`PRAGMA query_only = ON`). Only the PreCompact hook writes, and only to its own `cc:` namespace, so we never trample OpenClaw's data.\n- **Cross-runtime recall is the killer feature.** Daphne writes to LCM via OpenClaw at 7 AM; you open Claude Code at 2 PM and it can recall what was discussed — no copy/paste, no manual export.\n\n## Roadmap\n\n- v0.1 (current) — `lcm_grep`, `lcm_describe`, `lcm_stats`, PreCompact + SessionStart hooks, `lcm-recall` skill\n- v0.2 — `lcm_expand_query` with LLM-driven recursive DAG walk\n- v0.3 — periodic compaction job that runs lossless-claw's summarizer over `cc:*` conversations\n- v0.4 — `/lossless-claude` slash command for ad-hoc DB inspection from inside Claude Code\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffendingcommit%2Flossless-claude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foffendingcommit%2Flossless-claude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffendingcommit%2Flossless-claude/lists"}