clawbrain

核心用法

ClawBrain 是一款专为 OpenClaw/ClawDBot 生态设计的个人 AI 记忆系统，通过 pip install clawbrain[all]] 安装后执行 clawbrain setup 即可完成初始化。系统默认采用 SQLite 零配置运行，同时可选 PostgreSQL/Redis 生产级部署。核心 API 围绕 Brain 类展开，提供 get_full_context()() 统一上下文获取、、remember()()/()/recall()() 记忆存取、、learn_user_preference()() 用户偏好学习等能力。安装时会自动注入两个事件钩子：：gateway:startup 用于服务启动时刷新记忆，，command:new` 用于会话切换时保存状态。

显著优点

隐私优先架构：默认本地 SQLite 存储，无遥测、无外部 API 调用，所有数据留存用户设备。Fernet 对称加密专门保护 API 密钥等敏感数据，密钥文件权限严格控制在 600。

零摩擦体验：无需环境变量即可运行，自动检测平台（OpenClaw/ClawdBot），自动生成加密密钥，自动安装钩子，大幅降低部署门槛。

情感智能：内置 6 维人格特质（幽默、共情、好奇、创造、助人、诚实）动态演化，支持实时情绪检测、意图识别和个性化响应建议生成。

完全可审计：约 50 行 JavaScript 钩子代码全部开源，GitHub 仓库透明公开，支持从源码安装以彻底审查。

潜在缺点与局限性

密钥管理责任：加密密钥由用户本地保管，丢失即永久丢失加密数据，虽提供 backup-key 多方式备份，但仍依赖用户安全意识。

功能边界模糊：情绪检测、意图识别等 NLP 能力内置于记忆系统，但未说明是否依赖外部模型或纯规则实现，复杂场景准确性存疑。

生态锁定：专为 OpenClaw/ClawDBot 设计，钩子机制与特定事件体系深度耦合，迁移至其他 Agent 框架需重构集成层。

扩展性约束：SQLite 单文件模式在超高并发或多实例部署时存在瓶颈，虽支持 PostgreSQL 但增加运维复杂度。

适合的目标群体

• OpenClaw/ClawDBot 用户：希望为聊天机器人赋予长期记忆和个性化能力的开发者
• 隐私敏感型开发者：拒绝云端记忆服务、坚持数据本地化的 AI 应用构建者
• 快速原型团队：需要零配置启动、渐进式扩展至生产数据库的初创项目
• 教育研究场景：可审计开源代码满足学术透明度要求，适合人机交互研究

使用风险

性能风险：情绪检测和意图识别若涉及本地模型推理，可能在低配置设备上产生延迟；SQLite 在万级记忆量以上查询效率下降。

依赖风险：[all]] 安装模式可能引入 psycopg2-binary、redis 等重型依赖，生产环境建议按需精简。

密钥泄露风险：clawbrain show-key --full 命令可直接输出完整密钥，屏幕共享或日志记录场景存在意外暴露可能。

钩子冲突风险：自定义 hooks 目录若被其他技能污染，可能导致启动事件处理顺序异常。

版本兼容性：0.1.x 版本迭代较快，数据库 schema 升级路径未在文档中明确说明，跨版本迁移需谨慎备份。

核心用法

ClawBrain 是专为 OpenClaw/ClawDBot 设计的个人 AI 记忆系统，提供六大核心能力：

• Soul/Personality：6 维动态人格特质（幽默、共情、好奇心、创造力、乐于助人、诚实）
• User Profile：持续学习用户偏好、兴趣与沟通风格
• Conversation State：实时情绪检测与对话上下文追踪
• Learning Insights：从交互和修正中持续学习
• get_full_context()：一键获取个性化响应所需的全部上下文
• Encrypted Secrets：Fernet 加密存储 API 密钥等敏感凭证

典型调用流程：

from clawbrain import Brain
brain = Brain()
context = brain.get_full_context(
    session_key="telegram_12345",
    user_id="username",
    agent_id="assistant",
    message="Hey, how's it going?"
)
# context 包含用户画像、当前情绪、意图、相关记忆、人格指导、建议回复

显著优点

1. 零配置开箱即用：默认 SQLite + 自动生成加密密钥，无需任何配置即可运行
2. 存储后端灵活：自动检测 PostgreSQL/Redis，无可用时优雅降级至 SQLite
3. 安全设计完善：敏感数据本地加密，无遥测，无强制外部调用
4. Hook 机制透明：约 50 行 JavaScript 启动 Hook 完全开源可审计
5. CLI 工具齐全：setup、密钥管理、健康检查等命令一站式覆盖

潜在缺点与局限性

1. 密钥管理责任：加密密钥丢失将导致加密数据永久不可恢复，用户需自行承担备份责任
2. Hook 安装依赖：自动启动功能依赖写入用户目录的 Hook 文件，若被篡改存在潜在风险
3. PostgreSQL/Redis 需手动配置：生产环境扩展需要额外运维投入
4. 情绪检测准确性：基于规则/轻量模型，复杂情绪场景可能不够精准

适合人群

• 需要长期记忆能力的 AI 助手开发者
• 注重数据隐私、希望敏感信息本地加密的用户
• 使用 OpenClaw/ClawDBot 平台的机器人运营者
• 希望 AI 具备"人格一致性"和"用户熟悉感"的场景

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 启动 Hook 篡改 | 中 | Hook 代码简单透明，但建议安装前审查源码 |

| 文件系统读写 | 中 | 操作限于用户主目录，建议以专用用户运行 |

| 密钥泄露 | 低 | `show-key --full` 可能在不安全环境暴露密钥，建议用 `--file` 备份 |

| 加密数据丢失 | 低 | 密钥未备份时丢失将导致加密数据不可恢复 |

生产环境建议：启用 PostgreSQL + TLS、定期审计文件完整性、密钥离线备份。