脑珊瑚
August 31, 2026 · View on GitHub
给工程推理机当记忆骨头：任务链主导、记忆分域隔离、踩过的坑精炼回填，检索只捞该捞的。 不占上下文窗口，跨会话不丢失；从"聊天记忆"升级为纯工程推理推进机的记忆层。
你只管跟 AI 推进工程，重复交代的事交给它。
EN: A memory kernel for engineering-feedback agents — task-chain-first injection, domain-isolated stores, pitfalls distilled back into a shared expert-knowledge base, heat-aware eviction, reasoning threads for cross-chat coordination, zero-dependency MCP stdio bridge.
适用版本：本插件已适配 DeepSeek Harness
0.1.2-alpha.1（较旧版本有一个破坏性变更：@deepseek-ai/dsh-client-runtime已被移除，珊瑚客户端插件改为从@deepseek-ai/cordis取Context，并随新 harness 的dsh.client/invariant 契约适配）。安装前请确认你的 Harness 为 0.1.2-alpha.1。
⚠️ 版本与安装（v0.1.2-alpha.1，重要）：本插件已适配 Harness 0.1.2-alpha.1——
@deepseek-ai/dsh-client-runtime已被移除，珊瑚客户端插件改为从@deepseek-ai/cordis取Context，并随新 harness 的dsh.client/invariant契约适配（源码随 Harness 编译进packages/client）。三个独立部分：
- coral-memory（本包）：记忆层本体 + 设置面板。注册为 profile 的
dsh.profile.bundles（link:到本仓库webui），并暴露mcp__coral__*工具。- coral-board / ui-balance：任务板 / 余额胶囊，DSH 客户端插件。0.1.2-alpha.1 中放 Harness 源码
packages/client/，经 profile 的cordis.patch.yml用insert注册成dsh.client行（不能放进dsh.profile.bundles）；ui-balance含./invariant伴侣、coral-board为 typert-host。- mcp-coral：MCP 桥（
coral_mcp_server.py，仓库根），经cordis.patch.yml注册@deepseek-ai/dsh-mcp-clientstdio 行。安装顺序：Harness 工作区
pnpm install && pnpm run build:lib:host（构建珊瑚客户端插件 lib）→ 建/改 profile（cordis.patch.ymlinsert +package.json挂coral-memorybundle）→ 启动node apps/cli/lib/bin.js --profile <name>。详见plugins/。
它做了什么
脑珊瑚解决一个问题：LLM 每次新会话都失忆，工程推进到一半就断片。
它不只是"记住你说过的话"，而是给工程推理机当推进骨架：
- 任务链主导：每个工程任务一条推理线索链路——进度、决策、分工、到哪了，全部写死在链路上。任何聊天进来
thread_status就知道全局，接着推进。 - 记忆分域隔离：按域组织记忆池，检索只捞该捞的——绘图的记忆不会串到代码里，踩过的坑不会淹没在闲聊里。
- 踩坑精炼回填：失败的教训、修复方案作为高热度记忆回填，下次检索自动浮现——同一个坑不踩第二次。
- 自动新陈代谢：底层三级存储 + 热度淘汰 + LLM 蒸馏，常记常新，旧记忆自动钙化沉底。
记忆只是底座：三级存储 / 融合检索 / 热度淘汰负责"记得牢、捞得准"；真正的主轴是推理线索链路（跨聊天推进）与领域隔离（不串戏）。它不是聊天记录备份，是工程推进的记忆骨架。
为什么叫脑珊瑚：记忆像珊瑚礁一样，常被触碰的部分越活越旺（热度高、难淘汰），没人理的部分慢慢钙化沉底（自动降级）。它在自己长，你不用管。
GUI 一览（DSH Harness 插件）
| 任务栏 | 统计窗口 | 设置窗口 |
|---|---|---|
 |  |  |
- 任务栏：推理线索链路看板——活跃链路标题 / 状态 / 步数 / 最近推进者
- 统计窗口：缓存占用 + 记忆按天分布 + 即将被淘汰的冷记忆 Top5
- 设置窗口：容量 / 检索条数 / 最低分数 / 磁盘配额 / 热区保留时长，热加载即时生效
快速开始
pip install numpy
import asyncio
from three_dog_coral import ThreeDogCoral
async def main():
coral = ThreeDogCoral("coral_config.json")
# 记录一条工程经验（importance 高 → 难淘汰，检索优先浮现）
await coral.insert("迁移 bge 嵌入模型后必须重建向量：python migrate_bge.py", importance=0.9)
# 检索相关经验（踩坑回填后自动浮现）
hits = await coral.search("嵌入模型 换模型 向量", top_k=3)
for h in hits:
print(h.score, h.content, h.scores)
asyncio.run(main())
集成到 DSH / 其他客户端
MCP 方式（推荐）
零依赖，手写 MCP stdio 协议，不依赖 pip mcp 包。
# 1. 编辑 $DSH_HOME/profiles/<profile>/cordis.patch.yml，加一条：
# - insert:
# - id: mcp-coral
# name: '@deepseek-ai/dsh-mcp-client'
# inject: [coralPaths]
# config:
# serverName: coral
# transport: stdio
# command: !!js ctx.coralPaths.pythonCmd
# args: !!js ctx.coralPaths.pythonArgs
# env:
# CORAL_DATA_DIR: !!js ctx.coralPaths.dataDir
# toolCallTimeoutMs: 120000
#
# ⚠️ 不要重复添加同名 entry——会导致 dsh web 启动崩溃
# 2. 保存即生效（DSH 有 HMR）
# 3. 新会话自动获得全套工具
可用工具：memory_search / memory_insert / memory_flush / memory_delete + thread_*（链路协作）+ coral_config_*（配置管理）
持久化提醒：新记忆先进内存热区，重启后丢失。写重要记忆后务必调
memory_flush落盘。
HTTP Sidecar 方式
curl -X POST http://127.0.0.1:8765/rpc \
-H "content-type: application/json" \
-d '{"tool":"memory_insert","args":{"content":"你好珊瑚","importance":0.5}}'
核心功能
三级存储 + 热度淘汰
插入 → 热区（内存，最快） → TTL过期 → 温区（内存+JSON持久化） → 超容 → 冷区（JSONL追加）
- 热区：最新最热的记忆，检索最快
- 温区：写盘持久化，热度统计随写盘保留
- 冷区：尾部流式读，不读全文件
- 常被回忆的记忆热度越高，越难被淘汰——越用越"记得住"
多路融合检索
三路打分，加权融合：
score = 0.6·向量相似度 + 0.2·文本重合 + 0.2·时间新鲜度
- 向量：BLAS 矩阵乘，2000 条 ~2ms
- Jaccard：2048-bit 哈希位图向量化，稳态 12-13x 加速
- 时间衰减：最近说过的优先
推理线索链路（Thread）
永不遗忘的跨聊天协作机制。 普通记忆按热度淘汰，链路不参与任何淘汰——项目进度不会被"忘掉"。
聊天A: thread_create("发布 v2.0", "目标：升级嵌入模型", by="聊天A")
聊天B: thread_status # 进来就看到全局
聊天B: thread_advance(<id>, "migrate_bge.py 跑通", done=True, by="聊天B")
聊天C: thread_advance(<id>, "向量重建完成", by="聊天C")
聊天A: thread_archive(<id>) # 归档，永不遗忘
多进程一致性：锁文件串行化写者 + 文件指纹检测外部变更 + 按 step_id 合并。 压测：3 进程并发各推 30 步，90/90 零丢失。
配置热加载
在聊天里直接改配置，不用重启：
coral_config_set memory.capacity_threshold 2000 # 容量调大
coral_config_get retrieval.weights # 查检索权重
coral_stats() # 看占用
LLM 蒸馏
相似记忆簇交给 LLM 压缩成摘要（配置 llm 段即启用）。未配置时优雅降级为"不蒸馏"，不阻断治理。
磁盘配额
超 80% → 节流告警
超 100% → 按热度淘汰冷库，回落到 85%
向量用投影值计算（防止节流落盘导致低估真实占用）。
嵌入模型
模型不随仓库分发，首次运行自动从 HuggingFace 下载。
| 模型 | 维度 | 中文 | 说明 |
|---|---|---|---|
all-MiniLM-L6-v2（默认） | 384 | 一般 | 小快，纯本地 |
BAAI/bge-small-zh-v1.5（推荐） | 512 | 更准 | ~95MB，缓存在 .cache/huggingface |
换模型后需重建向量：
python migrate_bge.py # 修订+重嵌入+重建+验证，一步到位
DLC · 大工程协同
仓库自带指挥官 agent 预设 dlc/big-project-coordinator/：
开场"Hi，有什么大工程要我解决吗？"→ 自动建链路 → 拆子任务 → 派多个子聊天并行推进 → 写回进度 → 任何会话可接手。
配置参考
配置不入库（可能含 API key）。首次运行缺文件时自动生成默认配置。 模板：
coral_config.example.json
| 段 | 关键项 | 默认 | 说明 |
|---|---|---|---|
memory | capacity_threshold | 1000 | 记忆总数上限 |
hot_ttl_hours / max_hot_entries | 24 / 50 | 热区参数 | |
retrieval | weights | 0.6/0.2/0.2 | 向量/Jaccard/时间 |
top_k / min_score | 3 / 0.35 | 检索参数 | |
heat | weights | 0.4/0.3/0.3 | 频率/最近访问/重要性 |
storage | max_bytes | 0（不限） | 磁盘配额 |
threads | path | memory_data/coral_threads.json | 链路存储（永不遗忘） |
llm | base_url / api_key | 空 | 蒸馏端点（OpenAI 兼容） |
完整配置见 coral_config.example.json。
实测数据
合成语料 + hash 嵌入 + 固定 seed 的确定性基准（8C/16T）。 能力上限演示，不是典型场景预期。 脚本在
benchmarks/、tests/、stress/，可复现。
| 项目 | 结果 |
|---|---|
| 2 万次写入 | 83.7s，检索 12ms/次 |
| 超容治理 | 批量淘汰，90x 加速 |
| 并行（8C/16T） | 嵌入合批 3.9-6.8x，Jaccard 12-13x |
适用边界
诚实地说，这些场景它可能帮不上忙：
- 多领域混用同一池 → 不相关高频记忆挤占 Top-K。按项目拆独立实例解决。
- 无脑注入太多条 → 超过 5-10 条边际收益为负。默认 top_k=3 就够。
- 用 hash 嵌入冒充语义 → 只有词面重合。生产请装 sentence-transformers。
- 容量设太低 → recall 塌方。留够余量。
- 配置路径写错 → 静默回退默认值，部署时请校验。
- 基准数字当承诺 → 真实效果取决于嵌入模型、语料、查询措辞。用自有数据复测。
存储细节
- 单条记忆：文本 ~250B + 向量 ~1.5KB ≈ 1.8KB（10 万条 ≈ 180MB）
item_id = md5(content)[:16]：重复内容共享向量、跨库去重- 向量节流落盘（默认 5s）+
flush()强制；崩溃最多丢一个节流窗口 - 重启语义：热区不落盘（设计如此）；温区随治理写盘；孤儿向量启动清理
API 参考
| 方法 | 说明 |
|---|---|
insert(content, importance) | 插入记忆；重复返回 None 并合并访问统计 |
search(query, top_k) | 检索；返回 SearchHit（含分项得分） |
mark_important(item_id) | 显式标记重要性 |
delete(item_id) | 按 ID 彻底删除 |
flush() | 强制落盘 |
stats() | O(1) 统计 |
reload_config() | 热重载配置 |
disk_usage() | 磁盘明细 |
thread_create / status / advance / interrupt / archive / resume / link | 推理线索链路 |
config_get / config_set | 配置管理 |
MCP 工具前缀：mcp__coral__
License
MIT（见 LICENSE）。
唯一的要求：二次开发或发布衍生版本时，请保留作者署名（@Ne · 751286928@qq.com）与代码中的 __author__、插件水印。