AI导哈

LLM工作内存管理器

一个管理LLM工作内存的服务器，用于在令牌预算内存储、检索和压缩上下文，确保对话不超出限制而不丢失有价值信息。

  • by lukaszraczylo
  • Go
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 lukaszraczylo/compaction-mcp

使用说明

压实机

在令牌预算内管理LLM工作内存的MCP服务器。存储、检索和压缩上下文，使对话保持在限制范围内，而不会丢失有价值的信息。

旨在通过处理短期会话上下文来补充长期记忆工具（如克劳德助记符）。

安装

二进制

下载自 发布 或从源代码构建：

go build -o compactor .

单一二进制，无外部依赖。约6 MiB。

码头工人

docker pull ghcr.io/lukaszraczylo/compaction-mcp:latest

基于无发行版构建的多平台镜像（linux/amd64、linux/arm64）。

用法

# Ephemeral (in-memory, default)
compactor

# With persistent state
compactor --state-dir ~/.local/share/compactor

# Explicit token budget
compactor --budget 80000

码头工人

容器将压缩器二进制文件作为其入口点运行。由于MCP服务器通过stdio进行通信，请使用 -i （交互式）：

# Ephemeral
docker run -i ghcr.io/lukaszraczylo/compaction-mcp:latest

# With persistent state
docker run -i -v compactor-data:/data ghcr.io/lukaszraczylo/compaction-mcp:latest --state-dir /data

# With explicit budget
docker run -i ghcr.io/lukaszraczylo/compaction-mcp:latest --budget 80000

克劳德代码

.claude/settings.json （二进制）：

{
  "mcpServers": {
    "compactor": {
      "command": "/path/to/compactor",
      "args": ["--state-dir", "/tmp/compactor-state"]
    }
  }
}

.claude/settings.json （Docker）：

{
  "mcpServers": {
    "compactor": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "compactor-data:/data", "ghcr.io/lukaszraczylo/compaction-mcp:latest", "--state-dir", "/data"]
    }
  }
}

游标/其他MCP客户端

同样的模式。服务器自动检测客户端并设置合理的预算：

  • 克劳德 客户端：8万个令牌（20万个上下文的40%）
  • 光标：6万个代币
  • 覆盖 --budget 旗帜

工具

工具 说明
recall 每次会议先打电话。 恢复以前的上下文--返回预算状态+按相关性列出的顶级项目
store 使用可选摘要、标签和重要性存储内容（1-10）
query BM25按文本和/或标签过滤进行排名搜索
status 检查预算使用情况、项目计数、自动压缩设置
compact 触发压缩到目标使用率
update 添加/更新项目摘要（压缩后工作流）
pin / unpin 保护物品免遭驱逐
forget 删除特定项目
list 分页项目列表（最新优先）
bulk_store 在一次调用中存储多个项目（JSON数组）
export 导出所有项目，可选择作为摘要导出
configure 调整预算、自动压缩切换和阈值

压实工作原理

三相管道，在90%预算时自动触发或通过手动触发 compact:

  1. 总结推广 -用摘要替换内容（得分最低的项目优先）
  2. 去重 -合并单词重叠率>70%的项目（Jaccard相似性），保留得分较高的项目
  3. 驱逐 -删除得分最低的项目，直到达到目标使用率

压缩后，没有摘要的项目会被标记。然后，LLM可以通过以下方式生成摘要 update 用于未来的压实循环。

评分

每个项目都会得到一个结合四个信号的保留分数：

score = 0.4 * importance + 0.3 * recency + 0.2 * access - 0.1 * size_penalty

内容类型意识 自动调整评分：

类型 检测 分数乘数 衰变半衰期
错误 error:, panic:，堆叠痕迹 1.5x 30分钟
决定 “已决定”、“继续”、“方法：” 1.3x 6小时
代码 func, class，倒退围栏 1.2倍 6小时
散文 默认值 1.0x 2小时
刀具输出 $ 前缀，表字符 0.7x 15分钟

被钉住的物品永远不会被驱逐。

搜索

全文搜索使用BM25排名（k1=1.2，b=0.75），其中：

  • camelCase和snake_case令牌拆分
  • 标签匹配得分提高5倍
  • BM25相关性+项目保留率综合得分

自动标记

当没有提供标签时，项目会根据内容自动标记：

  • 内容类型（错误、代码、决策、工具输出）
  • 文件扩展名（.go、.ts、.py等）
  • 基础设施关键字（kubernetes、docker、cilium、postgres等）
  • URL存在（标记为“引用”）

坚持

随着 --state-dir，状态每30秒（脏时）和优雅关机时保存为原子JSON。没有它，每个会话的存储都是短暂的。

CLI标志

标志 默认值 描述
--budget 100000 令牌预算（覆盖自动检测）
--state-dir "" 持久状态目录（空=临时）

使其无缝衔接

压缩器是LLM必须积极使用的工具——它不会自动拦截上下文。为了使使用习惯化，请将此添加到您的 CLAUDE.md:

## Working Memory (compactor MCP)
- At session start, ALWAYS call `recall` to restore previous context
- After making decisions, reading key files, or encountering errors: call `store` with a summary
- Before re-reading a file: call `query` to check if it's already stored
- When `status` shows >80% usage: call `compact`, then `update` items it flags
- Pin architecture decisions and user preferences with `pin`

服务器还通过MCP握手发送指导LLM的指令，但CLAUDE.md规则更强，因为它们被视为硬要求。

三层如何协同工作

  1. MCP服务器说明 --在连接时注入，告诉LLM工作流程
  2. CLAUDE.md规则 --跨会话持久化，覆盖默认行为
  3. recall 工具 --为LLM提供了一个恢复上下文的单一操作，将12个工具的摩擦减少到1个入口点

坚持不懈(--state-dir)，上下文在会话中存在。LLM电话 recall → 取回其存储的决策、错误、代码片段→ 继续它停止的地方。

建筑

main.go       - Entry point, CLI flags, MCP server setup, persistence wiring
store.go      - Core store: items, scoring, compaction, BM25 integration
tools.go      - MCP tool definitions and handlers
index.go      - BM25 inverted index with tag boosting
content.go    - Content type detection and auto-tagging
persist.go    - Atomic JSON persistence with background save
tokens.go     - Token count estimation (~4 chars/token)

许可证

私人。

相关 MCP