🧠 LobsterPress v4.0.93「配置向导」

Cognitive Memory System for AI Agents 基于认知科学的 LLM 永久记忆引擎

中文 | English

最新版本: v4.0.93 · 更新日志

🎯 核心价值

问题：所有 LLM 都受限于上下文窗口。传统方案用滑动窗口截断——旧对话被永久丢弃，AI 陷入"失忆"循环。

解决方案：LobsterPress 基于认知科学实现 DAG 无损压缩 + 遗忘曲线 + 语义记忆，让 AI Agent 拥有类似人类的记忆系统：

• ✅ 无损压缩：100% 原始消息可追溯
• ✅ 智能遗忘：关键决策永久保留，闲聊自动衰减
• ✅ 知识提取：从对话中自动提取结构化知识
• ✅ 矛盾检测：自动发现和更新冲突知识
• ✅ 自动触发：三种策略（定时/紧急/被动）自动压缩

📦 安装教程（面向 OpenClaw 用户）

前置条件

在安装 LobsterPress 之前，请确保您的系统满足以下要求：

| 依赖 | 版本 | 如何检查 | 如何安装 | |------|------|----------|----------| | OpenClaw Gateway | 2026.3.9+ | openclaw gateway version | 安装指南 | | Node.js | 18+ | node --version | 下载地址 | | Python | 3.10+ | python3 --version | 系统自带或 下载 | | npm | 9+ | npm --version | 随 Node.js 安装 |

💡 提示: 如果您已经在使用 OpenClaw，那么 Node.js 和 Python 应该已经安装好了。

安装步骤（推荐方式）

⚠️ 重要: LobsterPress 是 OpenClaw 插件，必须安装到 ~/.openclaw/extensions/lobster-press/ 目录才能工作。不要使用 npm install -g（全局安装不会让 OpenClaw 加载插件）。

步骤 1: 创建插件目录

# 创建 OpenClaw 插件目录
mkdir -p ~/.openclaw/extensions/lobster-press

步骤 2: 安装 LobsterPress

方式 A: 从 npm 下载并安装（推荐）

# 进入插件目录
cd ~/.openclaw/extensions/lobster-press

# 下载最新版本 tarball
npm pack @sonicbotman/lobster-press@latest

# 解压到当前目录
tar -xzf *.tgz --strip-components=1

# 清理 tarball 文件
rm *.tgz

方式 B: 从 GitHub Release 下载（离线安装）

1. 访问 GitHub Releases
2. 下载最新版本的 lobster-press-X.X.X.tgz
3. 解压到插件目录：

cd ~/.openclaw/extensions/lobster-press
tar -xzf /path/to/lobster-press-X.X.X.tgz --strip-components=1

步骤 3: 验证安装

# 检查插件文件是否存在
ls ~/.openclaw/extensions/lobster-press/

# 预期输出: dist/  mcp_server/  openclaw.plugin.json  package.json  README.md  src/

步骤 4: 配置 LobsterPress

方式 1: 使用 AI 助手引导配置（推荐）

在与 AI 对话时，直接说：

帮我配置 LobsterPress 记忆系统

AI 会自动调用 lobster_configure 工具，引导您完成配置。

方式 2: 手动配置（高级用户）

编辑 ~/.openclaw/openclaw.json，添加插件配置：

{
  "plugins": {
    "allow": ["lobster-press"],
    "entries": {
      "lobster-press": {
        "enabled": true
      }
    },
    "slots": {
      "contextEngine": "lobster-press"
    }
  }
}

⚠️ 重要: 推荐使用方式 1（AI 引导配置），避免配置错误。

步骤 5: 重启 OpenClaw Gateway

# 方式 1: 使用 openclaw 命令（如果可用）
openclaw gateway restart

# 方式 2: 使用 systemctl
systemctl --user restart openclaw-gateway

# 方式 3: 发送重启信号
kill -HUP $(pgrep openclaw-gateway)

步骤 6: 验证 LobsterPress 是否工作

在与 AI 对话时，说：

我喜欢吃苹果

然后过几轮对话后，问：

我刚才说我喜欢吃什么？

如果 AI 能回答"苹果"，说明 LobsterPress 记忆系统已经正常工作！

快速验证命令

安装完成后，可以使用以下命令快速验证：

# 1. 检查插件文件
ls ~/.openclaw/extensions/lobster-press/

# 2. 检查 OpenClaw 配置
cat ~/.openclaw/openclaw.json | grep -A 5 "lobster-press"

# 3. 检查 Gateway 日志（确认插件加载）
journalctl --user -u openclaw-gateway -f | grep lobster

配置向导使用指南

LobsterPress v4.0.93 提供了 5 步交互式配置向导：

| 步骤 | 说明 | 您需要做的 | |------|------|-----------| | 1. 欢迎 | 介绍配置流程 | 阅读说明 | | 2. LLM 选择 | 选择使用 LLM 还是 TF-IDF | 选择是否使用 LLM | | 3. Provider | 选择 LLM 提供商 | 选择 OpenAI/智谱/DeepSeek 等 | | 4. API Key | 输入 API Key | 输入您的 API Key | | 5. 完成 | 确认配置 | 查看配置示例 |

配置示例对话：

您: 帮我配置 LobsterPress

AI: 欢迎使用 LobsterPress 配置向导！🦞
    LobsterPress 是一个基于认知科学的 LLM 永久记忆引擎。
    
    **第一步：选择记忆模式**
    
    LobsterPress 支持两种记忆模式：
    1. **LLM 模式**（推荐）：使用大语言模型智能提取记忆
    2. **TF-IDF 模式**：基于词频统计的传统模式
    
    请选择您想使用的模式（LLM/TF-IDF）：

您: LLM

AI: ✅ 已选择 LLM 模式
    
    **第二步：选择 LLM Provider**
    
    请选择您的 LLM 提供商：
    1. OpenAI
    2. Anthropic
    3. 智谱 AI（GLM）
    4. DeepSeek
    5. 自定义
    
    请输入选项（1-5）：

您: 3

AI: ✅ 已选择智谱 AI
    
    **第三步：输入 API Key**
    
    请输入您的智谱 AI API Key：
    （格式：xxxxxxxx.xxxxxxxxxxxxxxxx）
    
    ⚠️ 安全提示：API Key 会被加密存储，不会上传到云端。

您: [您的 API Key]

AI: ✅ 配置完成！
    
    LobsterPress 已经配置好了，您的 AI 助手现在拥有了长期记忆能力！
    
    **配置摘要**：
    - 记忆模式: LLM
    - Provider: 智谱 AI
    - API Key: 已配置 ✅
    
    **下一步**：重启 OpenClaw Gateway 使配置生效。

常见问题（FAQ）

Q1: 安装后 AI 还是记不住之前说的话？

可能原因：

1. OpenClaw Gateway 没有重启
2. 配置文件中没有启用 lobster-press
3. slots.contextEngine 没有设置

解决方法：

# 1. 检查配置
cat ~/.openclaw/openclaw.json | grep -A 5 "lobster-press"

# 2. 重启 Gateway
systemctl --user restart openclaw-gateway

# 3. 查看日志
journalctl --user -u openclaw-gateway -f | grep lobster

Q2: 提示 "lobster-press command not found"？

可能原因：npm 全局安装路径不在 PATH 中。

解决方法：

# 检查 npm 全局路径
npm config get prefix

# 添加到 PATH（以 bash 为例）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Q3: 配置后 Gateway 启动失败？

可能原因：配置文件 JSON 格式错误。

解决方法：

# 验证 JSON 格式
python3 -m json.tool ~/.openclaw/openclaw.json

# 如果报错，检查 JSON 语法（逗号、引号等）
# 或者恢复备份
cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json

Q4: 如何查看 LobsterPress 是否在运行？

方法 1: 查看日志

journalctl --user -u openclaw-gateway -f | grep -i lobster

方法 2: 检查数据库

# 查看是否有记忆被保存
sqlite3 ~/.openclaw/lobster.db "SELECT COUNT(*) FROM messages;"

Q5: 如何卸载 LobsterPress？

# 1. 移除配置
# 编辑 ~/.openclaw/openclaw.json，删除 "lobster-press" 相关配置

# 2. 卸载 npm 包
npm uninstall -g @sonicbotman/lobster-press

# 3. 删除数据库（可选）
rm ~/.openclaw/lobster.db

# 4. 重启 Gateway
systemctl --user restart openclaw-gateway

获取帮助

如果您遇到问题，可以通过以下方式获取帮助：

1. 查看文档: docs.openclaw.ai
2. GitHub Issues: 提交问题
3. Discord 社区: 加入讨论

高级配置（可选）

如果您是高级用户，可以手动配置以下选项：

{
  "plugins": {
    "entries": {
      "lobster-press": {
        "enabled": true,
        "config": {
          "llmProvider": "deepseek",
          "llmModel": "deepseek-chat",
          "llmApiKey": "${LOBSTER_LLM_API_KEY}",
          "contextThreshold": 0.8,
          "freshTailCount": 32,
          "namespace": "default"
        }
      }
    },
    "slots": {
      "contextEngine": "lobster-press"
    }
  }
}

| 配置项 | 说明 | 默认值 | |--------|------|--------| | llmProvider | LLM 提供商（openai/anthropic/zhipu/deepseek） | - | | llmModel | LLM 模型名称 | - | | llmApiKey | API Key（建议用环境变量） | - | | contextThreshold | 上下文使用率阈值（触发压缩） | 0.8 | | freshTailCount | 保留最近 N 条消息不压缩 | 32 | | namespace | 命名空间（多租户隔离） | default |

💡 安全提示: API Key 建议使用环境变量，不要直接写在配置文件中：

export LOBSTER_LLM_API_KEY="your-api-key"

🏗️ 架构概述

五大模块（v4.0「深海」）

┌─────────────────────────────────────────────────────────────┐
│                    LobsterPress v4.0                        │
├─────────────────────────────────────────────────────────────┤
│  模块一: CMV 三遍无损压缩                                    │
│  ├── Pass 1: 剥离 base64/长 JSON 冗余                       │
│  ├── Pass 2: 去重工具结果                                   │
│  └── Pass 3: 折叠系统样板代码                               │
├─────────────────────────────────────────────────────────────┤
│  模块二: C-HLR+ 自适应遗忘曲线（✅ 自动应用）              │
│  └── h = base_h × (1 + α × complexity) × spaced_bonus       │
│  └── v4.0.90: agent_end hook 自动调用 lobster_sweep         │
├─────────────────────────────────────────────────────────────┤
│  模块三: Focus 主动压缩触发                                  │
│  ├── 定时触发: 每 12 轮                                     │
│  ├── 紧急触发: 上下文 > 85%                                 │
│  └── 被动触发: 上下文 > 80%                                 │
├─────────────────────────────────────────────────────────────┤
│  模块四: R³Mem 可逆三层压缩                                  │
│  ├── Layer 1: Document-Level (返回子摘要)                   │
│  ├── Layer 2: Paragraph-Level (返回原始消息)                │
│  └── Layer 3: Entity-Level (按实体过滤)                     │
├─────────────────────────────────────────────────────────────┤
│  模块五: WMR 工具框架                                        │
│  ├── Write: compact, correct                                │
│  ├── Manage: sweep, assemble, prune                         │
│  └── Read: grep, describe, expand, status                   │
└─────────────────────────────────────────────────────────────┘

Lifecycle Hooks 集成

LobsterPress 通过 OpenClaw lifecycle hooks 实现自动记忆管理：

| Hook | 触发时机 | 功能 | 状态 | |------|----------|------|------| | before_agent_start | 每轮对话开始前 | 自动注入历史记忆（按 semantic > episodic > working 优先级） | ✅ 启用 | | agent_end | 每轮对话结束后 | 自动保存用户输入和 Agent 回复 | ✅ 启用 |

手动工具（可选）： | 工具 | 触发时机 | 功能 | 状态 | |------|----------|------|------| | lobster_compress | 手动调用 | 强制执行 DAG 压缩 | ✅ 可用 | | lobster_assemble | 手动调用 | 按三层记忆模型拼装最优上下文 | ✅ 可用 |

🛠️ MCP 工具列表

Read 层（读取记忆）

| 工具 | 说明 | 必需参数 | |------|------|----------| | lobster_grep | 全文搜索（FTS5 + TF-IDF） | query | | lobster_describe | 查看 DAG 摘要结构 | conversation_id 或 summary_id | | lobster_expand | 展开摘要到原始消息 | summary_id | | lobster_status | 系统健康报告 | - |

Write 层（写入记忆）

| 工具 | 说明 | 必需参数 | |------|------|----------| | lobster_compress | 触发 DAG 压缩 | conversation_id | | lobster_correct | 纠错记忆内容 | target_type, target_id, correction_type |

Manage 层（管理记忆）

| 工具 | 说明 | 必需参数 | |------|------|----------| | lobster_sweep | 标记衰减消息 | conversation_id | | lobster_assemble | 拼装三层上下文 | conversation_id | | lobster_prune | 删除 decayed 消息 | conversation_id |

调试工具

| 工具 | 说明 | |------|------| | lobster_check_context | 手动检查上下文（降级方案） |

🚀 快速上手

Python API

from src.database import LobsterDatabase
from src.dag_compressor import DAGCompressor
from src.incremental_compressor import IncrementalCompressor

# 初始化
db = LobsterDatabase("~/.openclaw/lobster.db")
compressor = DAGCompressor(db)
manager = IncrementalCompressor(
    db,
    max_context_tokens=200_000,
    context_threshold=0.8,
    fresh_tail_count=32
)

# 新消息触发压缩检查
result = manager.on_new_message("conv_123", {
    "id": "msg_001",
    "role": "user",
    "content": "我们决定用 PostgreSQL 作为主数据库",
    "timestamp": "2026-03-21T10:00:00Z"
})

print(result["compression_strategy"])  # "none" | "light" | "aggressive"

Agent 工具调用

from src.agent_tools import lobster_grep, lobster_describe, lobster_expand

# 搜索历史
results = lobster_grep(db, "PostgreSQL", conversation_id="conv_123", limit=5)

# 查看摘要结构
structure = lobster_describe(db, conversation_id="conv_123")
# → {"total_summaries": 12, "max_depth": 3, "by_depth": {...}}

# 展开摘要
messages = lobster_expand(db, "sum_abc123", max_depth=2)
# → {"total_messages": 47, "messages": [...]}

📚 学术基础

| 论文/理论 | 应用 | |-----------|------| | EM-LLM (ICLR 2025) | 事件分割、语义边界检测 | | HiMem | DAG 压缩、三级摘要结构 | | Ebbinghaus Forgetting Curve | 动态遗忘：R(t) = base × e^(-t/stability) | | Memory Reconsolidation (Nader, 2000) | 矛盾检测、知识重巩固 | | CMV | 三遍无损压缩 | | C-HLR+ (arXiv:2004.11327) | 复杂度驱动半衰期 | | Focus (arXiv:2502.15957) | 主动压缩触发 | | R³Mem (arXiv:2502.15957) | 可逆三层压缩 |

⚙️ 配置参数

| 参数 | 默认值 | 说明 | |------|--------|------| | max_context_tokens | 128,000 | 目标模型上下文窗口 | | context_threshold | 0.8 | 触发压缩的使用率阈值 | | fresh_tail_count | 32 | 受保护的最近消息数 | | leaf_chunk_tokens | 20,000 | 叶子压缩分块大小 | | focus_interval | 12 | Focus 定时触发间隔（轮） | | urgent_threshold | 0.85 | Focus 紧急触发阈值 |

🤖 LLM 提供商

支持 8 个主流提供商，用于高质量摘要生成：

国际：OpenAI, Anthropic, Google, Mistral

国内：DeepSeek ⭐, 智谱 GLM ⭐, 百度文心, 阿里通义

# 环境变量配置
export LOBSTER_LLM_PROVIDER=deepseek
export LOBSTER_LLM_API_KEY=sk-xxx
export LOBSTER_LLM_MODEL=deepseek-chat

📊 压缩策略

上下文使用率        策略              LLM 成本
─────────────────────────────────────────────────
< 60%              无操作            $0
60% – 80%          语义去重          $0
> 80%              DAG 摘要压缩      $

无损原则：user/assistant 消息永不修改，仅 trim 工具输出。

🗂️ 项目结构

├── index.ts                    # OpenClaw 插件入口（ContextEngine）
├── openclaw.plugin.json        # 插件配置
├── mcp_server/
│   └── lobster_mcp_server.py   # MCP Server（14 个工具）
└── src/
    ├── database.py             # SQLite 存储层
    ├── dag_compressor.py       # DAG 压缩引擎
    ├── incremental_compressor.py  # 三层压缩调度器
    ├── three_pass_trimmer.py   # CMV 三遍无损压缩
    ├── semantic_memory.py      # 语义记忆层
    ├── llm_client.py           # LLM 客户端
    ├── llm_providers.py        # 8 个提供商适配
    ├── prompts.py              # Prompt 模板
    ├── agent_tools.py          # Python API
    └── pipeline/
        ├── tfidf_scorer.py     # TF-IDF 评分
        ├── semantic_dedup.py   # 语义去重
        └── ...

📜 版本历史

| 版本 | 日期 | 说明 | |------|------|------| | v4.0.89 ⭐ | 2026-03-24 | 记忆优先级排序：semantic > episodic > working，长期记忆优先注入 | | v4.0.49 | 2026-03-23 | MCP 工具模式：禁用 lifecycle hooks，添加手动记忆管理指南 | | v4.0.41 | 2026-03-22 | Issue #174 专家反馈修复（6 个优化） | | v4.0.25 | 2026-03-21 | Issue #154 修复（ESM 兼容 + 截断逻辑） | | v4.0.25 | 2026-03-21 | Issue #153 修复（per-session 锁 + 版本动态） | | v4.0.25 | 2026-03-21 | README 重写 + 学术引用 | | v4.0.25 | 2026-03-20 | 安全修复（CodeQL） | | v4.0.25 | 2026-03-19 | 五大模块重构 | | v4.0.25 | 2026-03-19 | Bug 修复（7 个） | | v4.0.25 | 2026-03-19 | MemOS 架构 | | v4.0.25 | 2026-03-19 | ContextEngine 集成 | | v4.0.25 | 2026-03-17 | LLM 多提供商 | | v4.0.25 | 2026-03-17 | 认知科学重构 | | v4.0.25 | 2026-03-13 | 初始发布 |

详见 CHANGELOG.md

🙏 致谢

学术引用

如果 LobsterPress 对你的研究有帮助，请引用以下论文：

@inproceedings{emllm2025,
  title={EM-LLM: Event-Based Memory Management for Large Language Models},
  booktitle={ICLR 2025},
  year={2025}
}

@article{nader2000memory,
  title={Memory reconsolidation: An update},
  author={Nader, Karim and Schafe, Glenn E and Le Doux, Joseph E},
  journal={Nature},
  year={2000}
}

@article{ebbinghaus1885memory,
  title={Memory: A contribution to experimental psychology},
  author={Ebbinghaus, Hermann},
  journal={Teachers College, Columbia University},
  year={1885}
}

@article{chlr2020,
  title={C-HLR: Continual Hebbian Learning with Replay},
  author={Parisi, German I and Tani, Jun and Weber, Cornelius and Wermter, Stefan},
  journal={arXiv preprint arXiv:2004.11327},
  year={2020}
}

@article{focus2025,
  title={Focus: Attention-based Context Compression for LLMs},
  journal={arXiv preprint arXiv:2502.15957},
  year={2025}
}

@article{r3mem2025,
  title={R³Mem: Reversible Residual Recurrent Memory for Long-context LLMs},
  journal={arXiv preprint arXiv:2502.15957},
  year={2025}
}

@article{cmv2024,
  title={Context Maintenance and Retrieval for Efficient LLM Inference},
  journal={arXiv preprint},
  year={2024}
}

@inproceedings{himem2024,
  title={HiMem: Hierarchical Memory Management for Long-context LLMs},
  booktitle={NeurIPS 2024},
  year={2024}
}

开源项目

• lossless-claw — DAG 压缩架构参考
• OpenClaw — 插件平台

如果 LobsterPress 对你的项目有帮助，请给个 ⭐ Star！

Made with 🧠 by SonicBotMan & Xiao Yun

基于认知科学，为 AI Agent 构建人类般的记忆系统