cyber-brain
README.md
# Huiran-cerebro · 赛博大脑
<p align="center">
<img src="docs/architecture.svg" alt="Huiran-cerebro 架构图" width="100%">
</p>
<p align="center">
<img src="https://img.shields.io/badge/版本-v1.8.0-4B8BF5" alt="version">
<img src="https://img.shields.io/badge/语言-Python%203.10%2B-3776AB" alt="python">
<img src="https://img.shields.io/badge/许可证-MIT-green" alt="license">
<img src="https://img.shields.io/badge/数据库-SQLite%20%2B%20FTS5%20trigram-blue" alt="db">
<img src="https://img.shields.io/badge/语义检索-bge--small--zh--v1.5-orange" alt="embedding">
<img src="https://img.shields.io/badge/检索-RRF%20多信号融合-FF6B6B" alt="rrf">
<img src="https://img.shields.io/badge/MCP-%E8%B1%86%E5%8C%85%E5%85%BC%E5%AE%B9-7B3FE4" alt="mcp">
</p>
个人/团队记忆中枢与知识库引擎。单文件 SQLite，零服务依赖，融合「知识库 RAG + 记忆碎片 + 实体关系 + AI 检索」四层能力，可作 AI 助手的外接记忆（支持 MCP，已适配豆包等客户端）。
> **一句话**：把 AI 的「记忆」和「知识」沉淀成本地可检索、可对话的私有知识库。
<!-- AI-README：以下为给 AI 爬虫/LLM 的结构化摘要，便于快速理解项目 -->
<details open>
<summary><b>📋 AI 快速摘要（给 LLM 阅读）</b></summary>
- **这是什么**：个人/团队记忆中枢 + 知识库引擎，单文件 SQLite 零依赖，可作 AI 助手（Agent）的外接记忆层（Memory Layer）
- **解决什么问题**：①AI 会话记忆断片（上午做下午忘）②个人/团队知识分散难检索 ③中文检索效果差 ④记忆随体量膨胀而遗忘（长期记忆 / Long-Term Memory）
- **核心能力**：FTS5 trigram 中文全文检索 · bge-small-zh-v1.5 本地语义向量 · **RRF 多信号混合检索（FTS+LIKE+实体+语义四路融合）** · **时间感知检索（recall --days，时间衰减降权）** · **记忆生命周期管理（importance 自动分级 / 过期降权 / 重复合并）** · **主动提取（summarize.py 滚动摘要 + 碎片升级）** · 检索审计可视化 · 8 类记忆碎片 · 实体关系网 · MCP 接入 AI 客户端
- **技术栈**：Python 3.10+ / SQLite / FTS5 trigram / fastembed+ONNX / Flask / fastmcp
- **快速开始**：`pip install -r requirements.txt` → `python cyber_brain.py --db cyber_brain.db frag --add --type fact --content "今天周五"` → `python cyber_brain.py --db cyber_brain.db recall "关键词"`
- **关键词**：memory, knowledge base, RAG, SQLite, FTS5, MCP, semantic search, personal knowledge management, AI agent memory, memory layer, long-term memory, RRF, hybrid retrieval, chinese search, vector database, LLM memory
- **AI 导航**：详细技术说明见 [llms.txt](llms.txt)
</details>
---
## 特性
- **单文件存储**：SQLite 单库（`cyber_brain.db`），备份 = 拷文件，换机零迁移成本
- **中文检索优化**：FTS5 `trigram` 分词（中文按 3 字滑窗），≥3 字走全文索引、<3 字自动回退 LIKE，不丢短词
- **RRF 多信号混合检索**：FTS(BM25) + LIKE + 实体 + 语义向量 四路融合，短词也能命中，检索精度显著提升
- **时间感知检索**：`recall --days N` 只召回最近 N 天；时间衰减排序（高价值记忆永不衰减，普通记忆按年龄降权）
- **记忆生命周期管理**：`importance` 自动分级（铁律/决策/踩坑=high，事件=low）+ 过期降权 + 重复合并（`lifecycle --audit / --apply / --dedupe`，去重**默认只预演**，加 `--apply` 才落库）
- **可撤销的合并**：合并采用 tombstone 标记而非物理删除，`lifecycle --unmerge <id>` 可随时撤销；被标记的碎片不再出现在检索结果与开工上下文中
- **变更审计**：`memory_mutations` 表记录「谁改了什么」（与只记检索的 `memory_retrieval_audits` 互补），记忆的变更历史可回溯
- **主动提取**：`summarize.py` 自动汇总近期 event 碎片 → 滚动摘要 + 升级高价值碎片，防止「记得的内容被遗忘」
- **检索审计**：Web 界面「检索记录」tab 可视化每次检索的召回来源与命中，检索行为可回溯
- **四层数据模型**：
- `content_item` 内容实体（笔记/文章/任务/决策）
- `kb_document/kb_chunk` RAG 知识库（自动分块、向量列预留）
- `memory_fragments` 记忆碎片（fact/preference/emotion/knowledge/decision/iron_rule/event/pitfall）
- `entity/entity_link` 实体关系网（人/组织/项目/账号/平台/产品）
- **语义检索**：本地 `bge-small-zh-v1.5` 向量（fastembed + ONNX，离线可用）
- **记忆防遗忘**：`recall` 带回「滚动摘要 + 记忆碎片 + 关联实体」，长会话开工即带上文
- **Web 界面**：搜索 / 录入 / 浏览 / 实体关系图 / AI 问答 / 今日看板 / 检索记录
- **MCP 服务器**：把记忆库暴露为标准 MCP 工具，可接入豆包等支持 MCP 的 AI 客户端
---
## 界面预览
> 以下截图全部取自**虚构的演示数据**（`tools/_seed_demo.py` 可一键复现），不含任何真实内容。
| 统一搜索（记忆 / 实体 / 内容 / 知识库 一次命中） | 实体关系查询 |
|---|---|
|  |  |
| 关系图谱可视化 | 检索审计（召回来源可回溯） |
|---|---|
|  |  |
| 今日工作看板 / 开工上下文 | 内容实体浏览 |
|---|---|
|  |  |
| 记忆碎片 / 内容 / 实体录入 | 社交分享预览图 |
|---|---|
|  |  |
---
## 快速开始
### 环境
- Python 3.10+
- 依赖见 `requirements.txt`（`pip install -r requirements.txt`）
- 语义检索首次需联网下载模型（已配置 `hf-mirror.com` 镜像加速）
### 初始化
首次运行任意命令自动建库（无需手动建表）：
```bash
# 1. 写入一条记忆碎片
python cyber_brain.py --db cyber_brain.db frag --add --type fact --content "今天是周五" --subject work
# 2. 查询记忆（默认带时间衰减排序）
python cyber_brain.py --db cyber_brain.db recall "今天"
# 3. 时间感知检索：只召回最近 7 天
python cyber_brain.py --db cyber_brain.db recall --days 7 "今天"
# 4. 统一搜索（一次命中实体+内容+记忆+知识库+关键词组）
python cyber_brain.py --db cyber_brain.db search "关键词"
```
### Web 界面
```bash
# 启动 Web（默认 http://127.0.0.1:8899）
python web_ui.py
# 或 Windows 双击 start_web.bat
```
### MCP 接入（AI 客户端用）
```bash
# 启动 MCP 服务器（默认 http://127.0.0.1:8765/mcp）
python mcp_server.py
# 或 Windows 双击 start_mcp_server.bat
```
豆包等客户端配置：服务器名称 `cyber-brain` / 传输类型 `HTTP` / URL `http://127.0.0.1:8765/mcp`。
详见 `MCP接入豆包指南.md`。
---
## 命令行速查
```bash
# 实体（人/组织/项目/账号/产品）
python cyber_brain.py --db cyber_brain.db entity --add --type client --name "某公司" --org "某集团"
python cyber_brain.py --db cyber_brain.db link --from 1 --to 2 --relation belongs_to
# 内容（笔记/任务/决策）
python cyber_brain.py --db cyber_brain.db content --add --title "标题" --body "正文" --type note --cat 分类
# 知识库文档（自动分块可检索）
python cyber_brain.py --db cyber_brain.db doc --add --title "文档名" --text "长文本..."
# 记忆碎片（importance 自动分级）
python cyber_brain.py --db cyber_brain.db frag --add --type decision --content "决定采用方案A" --subject work
# 记忆分区：不传 namespace 落在 default（检索不传则看全部）
python cyber_brain.py --db cyber_brain.db frag --add --type fact --content "..." --namespace work
python cyber_brain.py --db cyber_brain.db search "关键词" --namespace work
python cyber_brain.py --db cyber_brain.db recall "主题" --namespace work
# 墓碑（软删除）：删掉只打标记，正文保留、可恢复
python cyber_brain.py --db cyber_brain.db frag --delete 12
python cyber_brain.py --db cyber_brain.db frag --deleted # 列出墓碑
python cyber_brain.py --db cyber_brain.db frag --restore 12
# 人工确认：待审碎片不进检索，批准后才激活
python cyber_brain.py --db cyber_brain.db lifecycle --submit-review 12
python cyber_brain.py --db cyber_brain.db lifecycle --review # 列出待审
python cyber_brain.py --db cyber_brain.db lifecycle --approve 12 # 或 --reject 12
# 变更审计（谁改了什么）
python cyber_brain.py --db cyber_brain.db mutations --limit 20
python cyber_brain.py --db cyber_brain.db mutations --action add
# 滚动摘要（收尾写一条，次日 recall 带回）
python cyber_brain.py --db cyber_brain.db summary --add --scope work --summary "今天完成了..."
# AI 会话落库
python cyber_brain.py --db cyber_brain.db conv --add --title "会话名" --session 2026-01-01
python cyber_brain.py --db cyber_brain.db conv --append 1 --role user --text "..."
```
完整命令：`python cyber_brain.py --help`
---
## 检索智能增强（v1.4 新特性）
### 多信号混合检索（RRF 融合）
检索从「纯向量语义」升级为 **FTS(BM25) + LIKE + 实体 + 语义向量 四路 RRF 融合**：
- RRF（Reciprocal Rank Fusion）：每路召回按 rank 打分 `1/(k+rank)`，跨路累加
- 中文短词（<3 字，FTS 不命中）也能靠 LIKE + 语义兜底召回
- 语义命中 + 关键词命中双重命中的条目排序更靠前
### 时间感知检索
- `recall --days N` / `search_memory(days=N)`：只召回最近 N 天
- 时间衰减排序：`importance=high` 的记忆永不衰减，普通记忆按创建年龄降权（防旧记忆淹没新记忆）
### 记忆生命周期管理
- `importance` 自动分级：iron_rule/decision/pitfall → high，event/emotion → low，其余 → normal
- 关键词加权：含「铁律/红线/必须/禁止/踩坑/决定」自动升 high
- `lifecycle` 命令：
- `lifecycle --audit`：只读审计（缺 importance / 过期低优先碎片）
- `lifecycle --apply`：自动修复（补分级 + 30 天以上降权）
- `lifecycle --dedupe`：**只预演**，列出疑似重复对（相似度阈值 0.8）
- `lifecycle --dedupe --apply`：真正落库 —— 把后写者标记为 `merged`（不删原文）
- `lifecycle --unmerge <id>`：撤销合并，把碎片从 `merged` 改回 `active`
> 设计取舍：**合并默认不落库**。重复判定是启发式的，误合并的代价比漏合并高，
> 所以先让人看预演结果再决定。标记而非删除，是为了保留可追溯性与可撤销性。
> 被标记为 `merged` 的碎片不会出现在检索结果与开工上下文里。
### 主动提取（summarize.py）
对标 memU「主动提取」：
```bash
# 汇总最近 N 天 event 碎片 → 滚动摘要 + 升级高价值碎片
python summarize.py --days 7
# 只预览不落库
python summarize.py --days 7 --dry-run
```
### 检索审计可视化
Web 界面新增「检索记录」tab：每次检索的召回来源（FTS/LIKE/实体/语义）与命中条目都可回溯，检索行为可审计。
---
## 会话自动打卡（防「上午做下午忘」）
工作告一段落后，用一句话把「干了什么」记进记忆库，自动写入 1 条 event 碎片 + 1 条工作日志；下午/明天新会话开工即能接上。
```bash
# 打卡（一句话总结，含动作+对象+产出）
python session_log.py "上午完成知识库上传包 v2.1 升级，向量索引重建到 5873 条"
# 看今天
python session_log.py --today
# 看最近 10 条
python session_log.py --list 10
```
- **自动分类**：含「发布/上传/草稿」→发布记录；「修复/解决/踩坑」→踩坑；「完成/落地/交付/升级」→完成事项；默认→工作日志
- **自动判重**：同一天相同/相近内容自动跳过（相似度阈值 85%），不重复打卡
- **Web 看板**：Web 界面「今日」tab 实时展示当日打卡（需 `python web_ui.py` 启动）
- **MCP 调用**：MCP 服务器 `session_log_tool`（action: log/today/recent）可直接打卡
---
## 数据结构
```
entity ──< entity_link >── entity # 工作对象 + 关系网
content_item (+ content_fts) # 笔记/文章/任务/决策 统一实体
kb_document ─< kb_chunk ─< kb_embedding # RAG 知识库（向量列预留）
ai_conversation # AI 会话落库
master_data / keyword_pack # 字典 / 关键词组
ingest_source / ingest_record # 数据接入 + 授权登记
memory_fragments (+ fragment_fts) # 记忆碎片（8 类，含 importance/namespace/deleted_at）
rolling_summaries # 滚动摘要 checkpoint
memory_relations # 碎片间关系
memory_retrieval_audits # 检索留痕（审计可视化数据源）
memory_mutations # 变更留痕（谁改了什么，与检索审计互补）
```
## 向量检索
- 模型：`BAAI/bge-small-zh-v1.5`（512 维，fastembed + ONNX Runtime）
- 重建索引：`python cyber_brain.py --db cyber_brain.db index`
- 语义搜索：`python cyber_brain.py --db cyber_brain.db vecsearch "词"`
- 未来可平滑迁移 pgvector（PostgreSQL）以支持更大规模
---
## 测试
```bash
# 核心测试套件（19 条断言，无需外部依赖，跑在临时库上）
python tools/test_cyber_brain.py
# 版本号一致性（__version__ ↔ README 徽章 ↔ git tag）
python tools/check_version.py --tag
# Web 界面冒烟（需 Playwright + 已启动 python web_ui.py）
python tools/_frontend_smoke.py
# 图谱冒烟
python tools/_graph_smoke.py
# 碎片去重扫描（只读）
python tools/_dup_scan.py
# 生成一份虚构演示数据（用于界面截图 / 本地试玩）
python tools/_seed_demo.py
```
> `test_cyber_brain.py` 的设计取向：**测命令，而不只是测函数** ——
> 核心断言落在「执行之后数据真的变了」这一层。例如
> `lifecycle --dedupe --apply` 之后必须真的有一条碎片变成 `merged`，
> 而不只是函数返回了一个数字。
## 项目结构
```
cyber_brain.py # 核心引擎（SQLite + FTS5 + 向量 + 记忆 + RRF 检索 + 生命周期）
web_ui.py # Web 界面（Flask，搜索/录入/浏览/实体图/AI 问答/今日看板/检索记录）
mcp_server.py # MCP 服务器（适配豆包等客户端）
session_log.py # 会话自动打卡（event 碎片 + 工作日志 + 自动判重）
summarize.py # 主动提取（event 汇总 → 滚动摘要 + 碎片升级）
daily_brief.py # 每日开工上下文生成
doctor.py # 环境自检（--fix 自动修）
COLLAB.md # AI 协作规约（开工 recall / 任务打卡 / 来源标记）
requirements.txt # 依赖
docs/ # 文档与架构图（architecture.svg）
tools/ # 测试与工具脚本
```
---
## 常见问题（FAQ）
**和 Mem0 / Letta(MemGPT) / Zep 这类记忆框架有什么不同？**
定位不同。那些是给 Agent 用的记忆层 SDK / 服务；本项目的重心是「单机、单文件、自己完全掌控」的记忆 + 知识库 ——
把 RAG 知识库、记忆碎片、实体关系、混合检索装进一个 SQLite 文件，零服务依赖、可离线。
不追求做通用框架，也不替代它们。它的场景是：**拷一个文件，就能带走全部记忆。**
**为什么用 SQLite 而不是专门的向量数据库？**
在个人 / 小团队的量级（数千到数十万条）下，SQLite + FTS5 完全够用，换来三个实际好处：
备份 = 拷文件、换机零迁移、无外部服务需要维护。向量用 fastembed + ONNX 本地推理，向量也存库内。
真到更大规模，`kb_embedding` 这一层可以平滑迁到 pgvector。
**中文检索为什么不能直接用默认分词？**
SQLite FTS5 自带的 `unicode61` 按空格切词，而中文没有空格 —— 直接用它几乎检索不出东西。
本项目改用 `trigram`（按 3 字滑窗）建索引，并保留「不足 3 字自动回退 LIKE」的兜底。
**RRF 是什么？为什么需要四路融合？**
Reciprocal Rank Fusion。单一向量检索对短词和专有名词不稳，单一全文检索对语义改写不稳。
四路（FTS-BM25 / LIKE / 实体 / 语义向量）各自召回后按 `1/(k+rank)` 累加重排，互相补位。
**会不会把我的数据传出去？**
默认不会。全文检索、向量计算（本地 ONNX 推理）、存储都在本机完成。
只有你主动配置了云端模型（例如把 AI 问答接到外部 API）时才会出网。
**数据怎么备份 / 换机？**
拷 `cyber_brain.db` 一个文件即可 —— 文档、碎片、实体、向量全在里面。
**记忆会无限膨胀吗？**
有生命周期管理：`importance` 自动分级、30 天以上的低价值事件自动降权、重复碎片可合并（可撤销）。
检索侧还有时间衰减排序，防止旧记忆淹没新记忆。
**能接哪些 AI 客户端？**
任何支持 MCP 的客户端。仓库内附了豆包（Doubao）的接入说明 `MCP接入豆包指南.md`；
其他客户端只需把 MCP 服务器地址填进配置。
**这是生产可用的项目吗？**
诚实地说：它是一个**能实际运行、也确实被长期使用**的个人项目，但不是经过大规模验证的成熟框架。
已有测试套件覆盖核心命令，但仍有许多边界未被覆盖 —— 见下节「第三方审阅」。
---
## 第三方审阅
本项目的代码曾被一个第三方记忆系统调研收录，并做了逐行、带锚点的代码审查：
**[Agent Memory Atlas · huiran-cerebro](https://neoneye.github.io/agent-memory-atlas/systems/huiran-cerebro/)**
—— 由 Simon Strandgaard 维护的 AI 记忆系统图谱（收录 700+ 系统），
以固定的 7 项机制对每个项目打分：tombstone / trust state / bi-temporal / scope enforced /
mutation audit / human review / negative evals。
对 v1.5.0（commit `2f48deb`）的评级是 **0/7**。指出的问题集中在同一类毛病：
**机制已经写出来了，但没有接线**——例如重复检测的函数存在、调用点却永远传预览参数；
合并标记写进了库、检索侧却不过滤 `status`。
**v1.6.0 逐条修复了这些问题**：去重改为两段式（默认预演 / `--apply` 落库）、
检索与开工上下文全面补 `status` 谓词、修掉 `namespace` 缺列导致的查询报错、
新增变更审计表与撤销合并命令、补上首个测试套件。完整记录见 [CHANGELOG](CHANGELOG.md)。
> 关于这个评级的语境：该图谱自己的统计显示，其收录的系统中 **44% 同样是 0 或 1 项**；
> 其方法论也明确说明，未标记表示「**在该 commit 上未找到该机制**」，
> 而不代表系统需要它。我们仍然认为这份审查是准确且有价值的。
---
## 关于本仓库
> ⚠️ **本仓库发布的是源码框架，不含任何实际数据。**
- **不含个人数据**：`cyber_brain.db`（知识库文档、记忆碎片、实体关系、向量索引）已列入 `.gitignore`，**仓库中不存在任何真实数据文件**，克隆后需自行初始化、自行灌入内容。文档中提到的规格描述（如「数百篇文档、数千条向量」）仅用于说明系统的设计承载能力。
- **已做脱敏**：原实现中针对特定部署环境的个性化内容——内部工作流指引、本机绝对路径、组织与客户标识等——均已替换为通用实现或占位注释。例如客户台账功能改为「按实体关系自动识别服务方」的通用逻辑（也可用环境变量 `CYBER_BRAIN_ROOT_ENTITY` 显式指定），不依赖任何特定组织名称；`cyber_brain.py` 中的「流水线固定指引」已改为「用户自定义每日指引」。功能逻辑与对外接口保持一致。
- **隐私设计**：默认本地运行，数据不出本机；仅在接入云端模型时才发起外部请求。
---
## License
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessUnresponsive