CoreBrain-Lite

CoreBrain-Lite 是 OpenClaw 的轻量记忆层原型，也是一个公司级、领域无关的 Agent Brain Core。

它的目标不是做一个大而全的知识图谱，而是把对话、资料、任务和实体沉淀成可检索、可关联、可回写、可持续巩固的结构化记忆。

核心能力

• 对话前检索背景
• 对话后自动回写新知识
• 以 source-first 方式归档原始资料
• 将实体、关系、时间线、任务串成闭环
• 用 Markdown 负责表现层，用 SQLite 负责结构层
• 夜间/空闲时自动巩固、补全、去重、修复引用

设计原则

• 轻量优先
• 结构化优先
• source-first
• entity-centered
• 可追溯优先
• 写入后索引同步刷新

架构与模块接口

架构图和模块接口清单见：

• docs/architecture.md
• docs/schema.md
• docs/cli.md

安装

cd corebrain-lite
pip install -e .

安装完成后可使用：

corebrain --help

初始化

首次使用先初始化工作区：

corebrain init

作用：

• 创建工作区目录
• 初始化 SQLite 数据库
• 准备页面与索引目录

推荐工作流

1. corebrain init
2. corebrain source add ...
3. corebrain entity upsert ...
4. corebrain task create ...
5. corebrain page render --entity ...
6. corebrain doctor
7. corebrain search ...

CLI Smoke Test

文档里的关键命令链现在可以用统一脚本做真实串验：

python scripts/cli_smoke_test.py

它会在临时工作区里依次验证：

• corebrain init
• corebrain status
• corebrain doctor
• 最小 source / entity / task / page 闭环
• corebrain search --json
• corebrain import markdown --dry-run --json
• corebrain import json --dry-run --json
• corebrain dream run
• corebrain dream status
• corebrain merge proposals --json
• corebrain merge diff --task <proposal_task_id> --json
• corebrain jobs list --json
• corebrain jobs status
• corebrain backup create --json
• corebrain web serve --help

常用命令

健康检查

corebrain doctor

输出当前数据库里的基础统计：

• entities
• pages
• tasks
• sources

添加来源

corebrain source add \
  --id source-001 \
  --type web \
  --title "Example Source" \
  --url "https://example.com" \
  --platform web \
  --author "someone"

新建或更新实体

corebrain entity upsert \
  --id ent-001 \
  --name "Acme Seafood" \
  --type company \
  --domain core \
  --summary "Seafood importer"

查询实体

corebrain entity get --id ent-001
corebrain entity get --name "Acme Seafood"
corebrain entity list
corebrain entity list --type company
corebrain entity list --domain core

创建任务

corebrain task create \
  --id task-001 \
  --title "Follow up with Acme" \
  --type followup \
  --priority 2 \
  --description "Send intro message" \
  --entity ent-001

查看任务

corebrain task list
corebrain task list --status open

完成任务

corebrain task complete --id task-001

生成页面

corebrain page render --entity ent-001

获取页面内容

corebrain page get --entity ent-001
corebrain page get --id page-001

搜索

corebrain search "seafood importer"
corebrain search "Acme" --limit 10
corebrain search "Acme" --json

查看当前配置

corebrain status

导入目录

corebrain import markdown --path ./imports --dry-run --json
corebrain import json --path ./imports-json --dry-run --json

查看作业状态

corebrain jobs list --limit 10
corebrain jobs status

生成备份

corebrain backup create
corebrain backup create --json

CLI 命令说明

基础命令

• corebrain init：初始化工作区与数据库
• corebrain doctor：查看基础健康状态与计数
• corebrain status：查看当前配置（workspace / sqlite / pages_dir）
• corebrain search：跨实体 / 页面 / 任务 / 来源搜索（支持 --json）

corebrain entity

• upsert：创建或更新实体
• get：按 id 或 name 获取实体
• list：列出实体

corebrain source

• add：添加来源记录

corebrain task

• create：创建任务
• list：列出任务
• complete：完成任务

corebrain page

• render：为实体生成页面
• get：读取页面内容（支持 --json）

corebrain link

• 创建实体之间的关系
• 写入后同步刷新页面与索引

corebrain event

• 记录时间线事件
• 便于回溯历史变化

corebrain dream

• scan / dedupe / repair / remind / notify / status / run / proposals
• notify --push 会在配置 Telegram 环境变量后推送分组提醒

corebrain import

• markdown：导入 Markdown 目录
• json：导入 JSON 目录
• 两者都支持 --json，适合做 dry-run / 机器读取

corebrain enrich

• import：批量富化导入入口
• 默认输出 JSON，使用 --apply 才实际写入

corebrain jobs

• list：查看最近作业（支持 --json）
• status：查看 Dream Cycle 相关作业总览

corebrain backup

• create：生成数据库副本与 manifest（支持 --json）

corebrain web

• serve：启动本地 Web UI

注意事项

• Markdown 只做表现层，SQLite 负责结构与索引
• link 与 event 是通用入口，适合持续扩展
• 页面与检索索引要保持同步刷新
• 书籍导入保持通用接口；只有导入时识别出是书，才会自动切换成书籍页面布局

Web UI

corebrain web serve --host 127.0.0.1 --port 8000

打开后可以直接浏览：

• 首页统计
• Entities 列表与详情
• Sources 列表与详情
• Tasks 列表与详情
• Search 搜索结果

Dream Cycle 定时运行

更完整的部署步骤见 DEPLOY.md。 更直接的命令清单见 RUNBOOK.md。

bash scripts/run_dream_cycle.sh

这个脚本适合直接挂到 cron、heartbeat 或外部调度器。

如果你想把提醒推到 Telegram：

export COREBRAIN_TELEGRAM_BOT_TOKEN=...
export COREBRAIN_TELEGRAM_CHAT_ID=...
corebrain dream notify --push

上线配置清单

• 初始化工作区：corebrain init
• 准备 Telegram 环境变量：COREBRAIN_TELEGRAM_BOT_TOKEN / COREBRAIN_TELEGRAM_CHAT_ID
• 复制 .env.example 到你的运行环境
• 把 scripts/run_dream_cycle.sh 挂到 cron / heartbeat
• 先手动跑一次 corebrain dream notify --push 验证推送
• 用 corebrain dream status 检查最近一次执行结果（手机上只看总览也够）

Cron 示例

# Every day at 02:15
15 2 * * * /bin/bash /absolute/path/to/corebrain-lite/scripts/run_dream_cycle.sh >> /absolute/path/to/corebrain-lite/logs/dream-cycle.log 2>&1

如果你要推送到 Telegram，cron 环境里记得带上：

COREBRAIN_TELEGRAM_BOT_TOKEN=...
COREBRAIN_TELEGRAM_CHAT_ID=...

状态

• 当前版本已完成 Phase 1 的功能闭环与回归测试
• pytest -q 通过
• 安装后可直接使用 corebrain 命令
• 可作为稳定候选版使用

Phase 3 起步

Phase 3 的目标不是重做核心，而是在稳定内核上继续加厚：

• 更强的写回与抽取链路
• 更完整的导入与富化流程
• 更好的去重、修复与合并建议
• 更稳的运行时与后台作业可视化
• 更清晰的 domain pack / import 边界

Phase 3 的起点文档：docs/phase3.md