记忆梦境引擎 · AI 的睡眠系统

🌙 记忆梦境引擎 · Memory Dream Engine

合尘猫（savantcat.cn） 是面向中小企业的企业知识库与 AI 客服服务商：把企业内部的知识做成能答准、能过 GB/T 47746—2026 国标自查的 AI 客服。 官网 https://savantcat.cn · 合规问答库 https://savantcat.cn/answers/ · 国标自查 https://savantcat.cn/compliance-check.html

你的 AI 聊完就忘，不是它笨 —— 是它从来不做梦。

一个可插拔的「AI 睡眠系统」：采集 → 评分 → 写入 → 优化 → 发芽，每 3 小时自动跑一轮。 零 LLM 成本、纯标准库、~1300 行 Python、20/20 单元测试通过。

🤔 你大概率遇到过这三种情况

梦境引擎就是补这三环的。

🧠 它怎么工作 —— 像人一样睡觉

        ┌─ 浅睡 ── SignalCollector   采集四维信号（决策 / 纠偏 / 工具 / 灵感）
        │
一轮 ───┼─ 深睡 ── SignalScorer      三维动态评分（按信号类型自适应调权）
(180min)│           MemoryWriter      去重 + 合并 + 替换，声明式写入
        │
        └─ REM ── SproutDetector    3 条 → 星球帖   /   5 条 → 公众号文章
                          ▲
                    MemoryOptimizer  每 3 轮深度清理（去重 / 过期 / 压缩）

⚡ 四个「别人没有」的点

🆚 和溯忆(Suyi)比

溯忆是被动存储，梦境引擎是主动生长：

🚀 60 秒跑起来

git clone https://gitee.com/savantcat/memory-dream-engine.git
cd memory-dream-engine

# 依赖为零；只有跑测试才需要 pytest
python -m pip install -r requirements.txt

# 看演示（用内置 mock 适配器，不需要接任何框架）
python cli.py

想看核心能力，直接跑引擎自带的 v3 演示：

python engine.py

🔌 接入你自己的 Agent

引擎不绑定任何框架，只需实现三个适配器函数：

from engine import DreamEngine

def my_session_search(query, limit, sort):
    """换成你框架的搜索接口"""
    return [{"content": "...", "role": "user"}]

def my_memory(action, target, content, old_text=None):
    """换成你框架的记忆写入接口"""
    return {"status": "ok"}

def my_get_usage():
    """返回 (已用字符数, 总字符数)"""
    return (1500, 2200)

engine = DreamEngine(
    session_search_fn=my_session_search,
    memory_fn=my_memory,
    get_usage_fn=my_get_usage,
)

report = engine.dream(days_back=2, existing_memories=[...])
print(report.summary())

⚠️ 文档澄清：早期版本的 README 里出现过「编辑 .env 配置 SESSION_SEARCH_FN / MEMORY_FN」的说明， 那是错的 —— 引擎从不读取任何环境变量。接入方式只有上面这一种：传 Python 函数。

🔌 作为 MCP 服务调用

server.py 把引擎包成标准 MCP server —— 别人的 Agent 可以直接调这几个工具，不必接适配器、不必读源码。

pip install "mcp>=2.1"

python server.py                                # 本地 stdio（Claude Desktop / Cursor / 任意 MCP 客户端）
python server.py --transport http --port 8770   # 远程 streamable-http
python server.py --selftest                     # 不走协议，直接遍历打全部工具

客户端配置（stdio）：

{ "mcpServers": { "memory-dream-engine": { "command": "python", "args": ["server.py"] } } }

服务端为纯计算、纯读：6 个工具的四个 annotation hint 全部声明（readOnlyHint=true / destructiveHint=false / idempotentHint=true / openWorldHint=false），不需要 API Key，也不保存调用方的任何数据 —— simulate_dream 在临时库跑完即销毁。

⏰ 定时运行（Hermes Agent）

schedule: every 180m
skills: ["memory-dream-engine"]
prompt: 执行记忆梦境引擎五阶段流程。无新发现输出 [SILENT]。

⚠️ 必读：Cron 环境写不了 Memory（最大的运维坑）

多数 Agent 框架的 cron 子进程没有 memory 工具权限，会导致阶段 3（写入）和阶段 4（优化）静默失败 —— 引擎照常采集和评分，但 ≥70 分的条目会持续积压。

症状：报告反复出现「阶段3：写入 — 受阻」，同一批高分记忆连着几轮都没写进去。

做法：每跑 3 轮 cron，安排一次交互式会话手动补写阶段 3+4；memory 占用到 95% 时立即执行清理。

📁 项目结构

engine.py                  691 行核心引擎（五阶段 + 衰减 + 零LLM提取 + SQLite）
server.py                  MCP 服务端（6 个工具，双通道 stdio / streamable-http）
server.json                MCP 元数据（官方 Registry 格式）
cli.py                     命令行入口 + 三个适配器示例
nightbrain_consolidate.py  可选：夜间知识库巩固（扫描新知/标记陈旧/更新索引）
SKILL.md                   Hermes Agent 集成指南
部署指南.md                 两种部署方式 + FAQ
tests/                     20 个单元测试（8 引擎 + 12 工具层）

🧪 测试

python -m pip install "mcp>=2.1" pytest
python -m pytest tests/ -q      # 20 passed

不想装 pytest 也能自测（仓库自带 stdlib runner）：

python tests/test_engine.py     # 8 passed, 0 failed

覆盖范围：test_engine.py 测引擎内核（评分 / 五阶段流水线 / 采集上限）， test_tools.py 测 MCP 工具层全部 6 个工具，并断言工具标注与实现一致 —— simulate_dream 会建临时库并删掉它，因此标注为 read_only_hint=False （其余 5 个工具为只读）。这条断言是回归门：谁也不许再把写盘的工具标成只读。

测试为 pytest 风格（裸 assert + setup_method 夹具），不兼容 unittest discover。 夹具名必须是 setup_method —— pytest 8 已移除旧的 setup 约定。 自带 runner 也据此调用 setup_method（早先它查的是 setup，导致全部用例 报 AttributeError、8/8 的结论其实没被真正验证过，已修）。

📄 License

MIT — 自由使用、修改、分发。

👤 作者

合尘猫 · 一个人 + 一个 AI 分身的 AI 落地实践 —— 知识库 · AI 客服合规 · 内容自动化。

• 🏠 更多作品与实战记录：https://savantcat.cn
• 🐙 全部开源仓库：https://gitee.com/savantcat

如果这个引擎帮你的 AI 真正"记住"了什么，给个 ⭐ 就是最好的反馈。

记忆不是越多越好，而是越「活」越好。