Martian-Engineering/lossless-claw
GitHub: Martian-Engineering/lossless-claw
为OpenClaw提供基于DAG的无损上下文管理插件，通过分层摘要机制在保持活跃上下文符合token限制的同时，完整保留所有历史消息并支持追溯检索。
Stars: 666 | Forks: 51
# lossless-claw
[OpenClaw](https://github.com/openclaw/openclaw) 的无损上下文管理插件，基于 [LCM 论文](https://papers.voltropy.com/LCM)。用基于 DAG 的摘要系统取代 OpenClaw 内置的滑动窗口压缩机制，在保持活跃上下文符合模型 token 限制的同时，保留每一条消息。
## 目录
- [功能介绍](#what-it-does)
- [快速开始](#quick-start)
- [配置说明](#configuration)
- [文档](#documentation)
- [开发](#development)
- [许可证](#license)
## 功能介绍
两种了解方式：阅读下文，或者[查看这个超酷的动态可视化演示](https://losslesscontext.ai)。
当对话增长超过模型的上下文窗口时，OpenClaw（就像所有其他 Agent 一样）通常会截断较旧的消息。而 LCM 则会：
1. **持久化每一条消息** 到 SQLite 数据库中，按对话组织
2. **汇总旧消息块**，使用你配置的 LLM 生成摘要
3. **压缩摘要**，随着摘要积累将其压缩成更高层级的节点，形成 DAG（有向无环图）
4. **组装上下文**，每轮对话结合摘要 + 最近的原始消息
5. **提供工具**（`lcm_grep`、`lcm_describe`、`lcm_expand`），让 Agent 可以从已压缩的历史记录中搜索和回忆细节
没有任何信息丢失。原始消息保留在数据库中。摘要链接回其源消息。Agent 可以深入任何摘要以恢复原始细节。
**感觉就像在与一个永远不会忘记的 Agent 对话。因为它确实不会。在正常运行中，你再也不需要考虑压缩问题。**
## 快速开始
### 前置条件
- 支持 plugin context engine 的 OpenClaw
- Node.js 22+
- 在 OpenClaw 中配置的 LLM 提供商（用于摘要生成）
### 安装插件
使用 OpenClaw 的插件安装器（推荐）：
```
openclaw plugins install @martian-engineering/lossless-claw
```
如果你是在本地的 OpenClaw 检出中运行，请使用：
```
pnpm openclaw plugins install @martian-engineering/lossless-claw
```
对于本地插件开发，链接你的工作副本而不是复制文件：
```
openclaw plugins install --link /path/to/lossless-claw
# 或从本地 OpenClaw checkout：
# pnpm openclaw plugins install --link /path/to/lossless-claw
```
安装命令会记录插件，启用它，并应用兼容的插槽选择（包括适用的 `contextEngine`）。
### 配置 OpenClaw
在大多数情况下，`openclaw plugins install` 之后不需要手动编辑 JSON。
如果你需要手动设置，请确保 context engine 插槽指向 lossless-claw：
```
{
"plugins": {
"slots": {
"contextEngine": "lossless-claw"
}
}
}
```
配置更改后重启 OpenClaw。
## 配置说明
LCM 通过插件配置和环境变量的组合进行配置。环境变量优先以保持向后兼容性。
### 插件配置
在你的 OpenClaw 配置中的 `plugins.entries` 下添加一个 `lossless-claw` 条目：
```
{
"plugins": {
"entries": {
"lossless-claw": {
"enabled": true,
"config": {
"freshTailCount": 32,
"contextThreshold": 0.75,
"incrementalMaxDepth": -1
}
}
}
}
}
```
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `LCM_ENABLED` | `true` | 启用/禁用插件 |
| `LCM_DATABASE_PATH` | `~/.openclaw/lcm.db` | SQLite 数据库路径 |
| `LCM_CONTEXT_THRESHOLD` | `0.75` | 触发压缩的上下文窗口比例（0.0–1.0） |
| `LCM_FRESH_TAIL_COUNT` | `32` | 受保护免于压缩的最近消息数量 |
| `LCM_LEAF_MIN_FANOUT` | `8` | 每个叶摘要的最小原始消息数 |
| `LCM_CONDENSED_MIN_FANOUT` | `4` | 每个压缩节点的最小摘要数 |
| `LCM_CONDENSED_MIN_FANOUT_HARD` | `2` | 强制压缩扫描的宽松扇出 |
| `LCM_INCREMENTAL_MAX_DEPTH` | `0` | 增量压缩深度（0 = 仅叶节点，-1 = 无限制） |
| `LCM_LEAF_CHUNK_TOKENS` | `20000` | 每个叶压缩块的最大源 token 数 |
| `LCM_LEAF_TARGET_TOKENS` | `1200` | 叶摘要的目标 token 数 |
| `LCM_CONDENSED_TARGET_TOKENS` | `2000` | 压缩摘要的目标 token 数 |
| `LCM_MAX_EXPAND_TOKENS` | `4000` | 子 Agent 扩展查询的 token 上限 |
| `LCM_LARGE_FILE_TOKEN_THRESHOLD` | `25000` | 超过此大小的文件块会被拦截并单独存储 |
| `LCM_LARGE_FILE_SUMMARY_PROVIDER` | `""` | 大文件摘要的提供商覆盖 |
| `LCM_LARGE_FILE_SUMMARY_MODEL` | `""` | 大文件摘要的模型覆盖 |
| `LCM_SUMMARY_MODEL` | *(来自 OpenClaw)* | 摘要生成的模型（例如 `anthropic/claude-sonnet-4-20250514`） |
| `LCM_SUMMARY_PROVIDER` | *(来自 OpenClaw)* | 摘要生成的提供商覆盖 |
| `LCM_AUTOCOMPACT_DISABLED` | `false` | 禁用轮次后的自动压缩 |
| `LCM_PRUNE_HEARTBEAT_OK` | `false` | 从 LCM 存储中回溯删除 `HEARTBEAT_OK` 轮次循环 |
### 推荐起始配置
```
LCM_FRESH_TAIL_COUNT=32
LCM_INCREMENTAL_MAX_DEPTH=-1
LCM_CONTEXT_THRESHOLD=0.75
```
- **freshTailCount=32** 保护最近 32 条消息免于压缩，为模型提供足够的近期上下文以保持连贯性。
- **incrementalMaxDepth=-1** 在每次压缩通过后启用无限自动压缩 —— DAG 会根据需要级联到任意深度。设置为 `0`（默认）仅限叶节点，或设置为正整数以限制特定深度。
- **contextThreshold=0.75** 当上下文达到模型窗口的 75% 时触发压缩，为模型的响应留出余量。
### OpenClaw 会话重置设置
LCM 通过压缩保留历史记录，但**不**改变 OpenClaw 的核心会话重置策略。如果会话重置比你预期的要快，请增加 OpenClaw 的 `session.reset.idleMinutes` 或使用特定频道/类型的覆盖设置。
```
{
"session": {
"reset": {
"mode": "idle",
"idleMinutes": 10080
}
}
}
```
- `session.reset.mode: "idle"` 保持会话活跃直到空闲窗口过期。
- `session.reset.idleMinutes` 是以分钟为单位的实际重置间隔。
- OpenClaw 目前**不**强制执行最大 `idleMinutes`；在源代码中它仅被验证为正整数。
- 如果你也使用每日重置模式，`idleMinutes` 充当次要保护，当达到每日边界或空闲窗口两者中的**任意一个**时，会话就会重置。
- 旧版 `session.idleMinutes` 仍然有效，但 OpenClaw 优先使用 `session.reset.idleMinutes`。
常用值：
- `1440` = 1 天
- `10080` = 7 天
- `43200` = 30 天
- `525600` = 365 天
对于大多数长期运行的 LCM 设置，一个好的起点是：
```
{
"session": {
"reset": {
"mode": "idle",
"idleMinutes": 10080
}
}
}
```
## 文档
- [配置指南](docs/configuration.md)
- [架构](docs/architecture.md)
- [Agent 工具](docs/agent-tools.md)
- [TUI 参考](docs/tui.md)
- [lcm-tui](tui/README.md)
- [可选：启用 FTS5 以进行快速全文搜索](docs/fts5.md)
## 开发
```
# 运行 tests
npx vitest
# Type 检查
npx tsc --noEmit
# 运行特定 test 文件
npx vitest test/engine.test.ts
```
### 项目结构
```
index.ts # Plugin entry point and registration
src/
engine.ts # LcmContextEngine — implements ContextEngine interface
assembler.ts # Context assembly (summaries + messages → model context)
compaction.ts # CompactionEngine — leaf passes, condensation, sweeps
summarize.ts # Depth-aware prompt generation and LLM summarization
retrieval.ts # RetrievalEngine — grep, describe, expand operations
expansion.ts # DAG expansion logic for lcm_expand_query
expansion-auth.ts # Delegation grants for sub-agent expansion
expansion-policy.ts # Depth/token policy for expansion
large-files.ts # File interception, storage, and exploration summaries
integrity.ts # DAG integrity checks and repair utilities
transcript-repair.ts # Tool-use/result pairing sanitization
types.ts # Core type definitions (dependency injection contracts)
openclaw-bridge.ts # Bridge utilities
db/
config.ts # LcmConfig resolution from env vars
connection.ts # SQLite connection management
migration.ts # Schema migrations
store/
conversation-store.ts # Message persistence and retrieval
summary-store.ts # Summary DAG persistence and context item management
fts5-sanitize.ts # FTS5 query sanitization
tools/
lcm-grep-tool.ts # lcm_grep tool implementation
lcm-describe-tool.ts # lcm_describe tool implementation
lcm-expand-tool.ts # lcm_expand tool (sub-agent only)
lcm-expand-query-tool.ts # lcm_expand_query tool (main agent wrapper)
lcm-conversation-scope.ts # Conversation scoping utilities
common.ts # Shared tool utilities
test/ # Vitest test suite
specs/ # Design specifications
openclaw.plugin.json # Plugin manifest with config schema and UI hints
tui/ # Interactive terminal UI (Go)
main.go # Entry point and bubbletea app
data.go # Data loading and SQLite queries
dissolve.go # Summary dissolution
repair.go # Corrupted summary repair
rewrite.go # Summary re-summarization
transplant.go # Cross-conversation DAG copy
prompts/ # Depth-aware prompt templates
.goreleaser.yml # GoReleaser config for TUI binary releases
```
## 许可证
MIT
标签：Agent Memory, Compaction, Context Management, Context Window, Conversation History, DAG, DLL 劫持, GNU通用公共许可证, LLM, Long-term Memory, Lossless Context, MITM代理, NLP, Node.js, OpenClaw, Plugin, RAG, Sliding Window, SQLite, Summarization, Unmanaged PE, Voltropy, 上下文窗口, 上下文管理, 人工智能, 信息检索, 压缩算法, 大语言模型, 威胁情报, 对话历史, 开发者工具, 开源, 插件, 摘要生成, 无损失上下文, 日志审计, 有向无环图, 检索增强生成, 滑动窗口, 火星工程, 用户模式Hook绕过, 自动化攻击, 记忆系统, 长期记忆