OpenClawBrain v12.2.1

面向AI智能体的学习型检索图。节点为文档块，边为可变加权指针。该图通过策略梯度更新（REINFORCE）从结果中学习，并通过稳态衰减、突触缩放和层级滞后来实现自我调节。

安装

bash
pip install openclawbrain # 核心（纯Python，零依赖）
pip install openclawbrain[openai] # 含OpenAI嵌入

快速开始

bash

从工作区文件构建大脑

openclawbrain init --workspace ./my-workspace --output ./brain --embedder openai

查询

openclawbrain query 如何部署 --state ./brain/state.json --json

从结果中学习（+1 好，-1 差）

openclawbrain learn --state ./brain/state.json --outcome 1.0 --fired-ids node1,node2

自我学习（智能体主动发起，无需人工）

openclawbrain self-learn --state ./brain/state.json \ --content 在终止实例前始终下载工件 \ --fired-ids node1,node2 --outcome -1.0 --type CORRECTION

健康检查

openclawbrain doctor --state ./brain/state.json

核心概念

学习规则：策略梯度（默认）

默认使用applyoutcomepg（REINFORCE）。在每个节点处，更新操作将概率质量重新分配到所有出边（总和≈0）。被选中的边权重上升，所有其他边下降。无膨胀。

apply_outcome（启发式）作为备用方案——仅更新被遍历的边，存在膨胀。

自我学习

智能体从自身观察到的结果中学习，无需人工反馈（self-correct可作为CLI/API别名使用）：

python
from openclawbrain.socket_client import OCBClient

with OCBClient(~/.openclawbrain/main/daemon.sock) as client:
# 智能体检测到失败
client.self_learn(
content=在终止前始终下载工件,
fired_ids=[node1, node2],
outcome=-1.0,
node_type=CORRECTION, # 惩罚+抑制性边
)

# 智能体观察到成功
client.self_learn(
content=先下载后终止的方式可靠有效,
fired_ids=[node1, node2],
outcome=1.0,
node_type=TEACHING, # 强化+正面知识
)

情况	outcome	type	效果
错误	-1.0	CORRECTION	惩罚路径+抑制性边
学到事实

0.0 | TEACHING | 仅注入知识 | | 成功 | +1.0 | TEACHING | 强化路径+注入知识 |

自我调节（自动，无需调参）

• - 稳态衰减：半衰期自动调整以维持5-15%的反射边比例。范围限制在60-300个周期。
• 突触缩放：每个节点的软权重预算（5.0）防止枢纽节点主导。
• 层级滞后：习惯性区间0.15-0.6防止阈值震荡。
• 突触缩放（维护细节）：每个节点的软权重预算（5.0），采用四次方根缩放。

边的层级

层级	权重	行为
反射	≥ 0.6	自动跟随
习惯性

0.15 – 0.6 | 按权重跟随 |

| 休眠 | < 0.15 | 跳过 | | 抑制性 | < -0.01 | 主动抑制目标 |

维护流水线

通过守护进程每30分钟运行一次：health → decay → scale → split → merge → prune → connect

• - 衰减：边权重的指数衰减（自适应半衰期）
• 缩放：对枢纽节点进行突触缩放
• 拆分：运行时节点拆分（合并的逆操作），用于处理臃肿的多主题节点
• 合并：合并共同激活的节点（双向权重≥0.8）
• 修剪：移除死亡边（|w| < 0.01）和孤立节点

维护

• - splitnode：将臃肿节点拆分为聚焦的子节点，并基于嵌入进行边的重新连接
• suggestsplits：通过内容长度、枢纽度、合并来源、边方差检测候选节点

文本分块

splitworkspace按类型对文件进行分块（.py→函数，.md→标题，.json→键），然后rechunk_oversized确保每个块不超过12K字符。大文本按空行→换行→硬切割的顺序进行拆分。不会跳过或截断任何内容。

守护进程（生产环境使用）

守护进程将状态热保持在Unix套接字后的内存中（查询约500ms，而磁盘查询需5-8秒）。

bash

启动守护进程（通常通过launchd）

openclawbrain daemon --state ./brain/state.json --embed-model text-embedding-3-small

守护进程方法（通过Unix套接字的NDJSON格式）

方法	用途
query	遍历图，返回激活节点+上下文
learn

对激活节点应用结果 |

| self_learn | 智能体主动学习（CORRECTION或TEACHING） | | selfcorrect | selflearn的别名（self-correct可作为CLI/API别名使用） | | correction | 人工发起的修正（使用chat_id回溯） | | inject | 添加TEACHING/CORRECTION/DIRECTIVE节点 | | maintain | 执行维护任务 | | health | 图健康指标 | | info | 守护进程信息 | | save | 强制写入状态 | | reload | 从磁盘重新加载状态 | | shutdown | 安全关闭 |

套接字客户端

python from openclawbrain.socket_client import OCBClient

with OCBClient(/path/to/daemon.sock) as c:
result = c.query(如何部署, chat_id=session-123)
c.learn(fired_nodes=[node1, node2], outcome=1.0)
c.selflearn(content=经验教训, outcome=-1.0, nodetype=CORRECTION)
c.health()
c.maintain(tasks=[decay, prune])

CLI参考

bash
openclawbrain init --workspace W --output O [--embedder openai] [--llm openai]
openclawbrain query TEXT --state S [--top N] [--json] [--chat-id CID]
openclawbrain learn --state S --outcome N --fired-ids a,b,c [--json]
openclawbrain self-learn --state S --content TEXT [--fired-ids a,b] [--outcome -1] [--type CORRECTION|TEACHING]
openclawbrain inject --state S --id ID --content TEXT [--type CORRECTION|TEACHING|DIRECTIVE]
openclawbrain health --state S
openclawbrain doctor --state S
openclawbrain info --state S
openclawbrain maintain --state S [--tasks decay,scale,split,merge,prune,connect]
openclawbrain status --state S [--json]
openclawbrain replay --state S --sessions S
openclawbrain merge --state S [--llm openai]
openclawbrain connect --state S
openclawbrain compact --state S
openclawbrain sync --workspace W --state S [--embedder openai]
openclawbrain daemon --state S [--embed-model text-embedding-3-small]

遍历默认值

参数	默认值
beamwidth	8
maxhops

30 | | fire_threshold | 0.01 | | reflex_threshold | 0.6 | | habitual_range | (0.15, 0.6) | | inhibitory_threshold | -0.01 | | maxcontextchars | 20000（在query_brain.py中） |

状态持久化

• - 原子写入：临时文件→fsync→重命名。保留.bak备份。崩溃安全。
• 状态格式：state.json（图+索引+元数据）
• 嵌入器身份存储在元数据中；维度不匹配将报错。

与OpenClaw智能体的集成

添加到智能体的AGENTS.md文件中：

markdown

OpenClaw