# 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.3.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/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 助手的外接记忆
- **解决什么问题**：①AI 会话记忆断片（上午做下午忘）②个人/团队知识分散难检索 ③中文检索效果差
- **核心能力**：FTS5 trigram 中文全文检索 · bge-small-zh-v1.5 本地语义向量 · 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 init` → `python cyber_brain.py --db cyber_brain.db recall "关键词"`
- **关键词**：memory, knowledge base, RAG, SQLite, FTS5, MCP, semantic search, personal knowledge management, AI agent memory, chinese search
- **AI 导航**：详细技术说明见 [llms.txt](llms.txt)

</details>

---

## 特性

- **单文件存储**：SQLite 单库（`cyber_brain.db`），备份 = 拷文件，换机零迁移成本
- **中文检索优化**：FTS5 `trigram` 分词（中文按 3 字滑窗），≥3 字走全文索引、<3 字自动回退 LIKE，不丢短词
- **四层数据模型**：
  - `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 客户端

---

## 快速开始

### 环境

- Python 3.10+
- 依赖见 `requirements.txt`（`pip install -r requirements.txt`）
- 语义检索首次需联网下载模型（已配置 `hf-mirror.com` 镜像加速）

### 初始化

```bash
# 1. 建库（自动建表）
python cyber_brain.py --db cyber_brain.db init

# 2. 写入一条记忆碎片
python cyber_brain.py --db cyber_brain.db frag --add --type fact --content "今天是周五" --subject work

# 3. 查询记忆
python cyber_brain.py --db cyber_brain.db recall "今天"

# 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 "长文本..."

# 记忆碎片
python cyber_brain.py --db cyber_brain.db frag --add --type decision --content "决定采用方案A" --subject work

# 滚动摘要（收尾写一条，次日 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 --id 1 --role user --text "..."
```

完整命令：`python cyber_brain.py --help`

---

## 会话自动打卡（防「上午做下午忘」）

工作告一段落后，用一句话把「干了什么」记进记忆库，自动写入 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 服务器第 7 个工具 `session_log_tool`（action: log/today/recent）可直接打卡；豆包等 6 工具上限客户端用 `add_memory(ftype='event', content=...)` 等价

---

## 数据结构

```
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 类）
rolling_summaries                        # 滚动摘要 checkpoint
memory_relations                         # 碎片间关系
memory_retrieval_audits                  # 检索留痕
```

## 向量检索

- 模型：`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
# Web 界面冒烟（需 Playwright）
python tools/_frontend_smoke.py
# 图谱冒烟
python tools/_graph_smoke.py
# 碎片去重扫描（只读）
python tools/_dup_scan.py
```

## 项目结构

```
cyber_brain.py          # 核心引擎（SQLite + FTS5 + 向量 + 记忆）
web_ui.py               # Web 界面（Flask，搜索/录入/浏览/实体图/AI 问答/今日看板）
mcp_server.py           # MCP 服务器（6 工具适配豆包 + session_log_tool）
session_log.py          # 会话自动打卡（event 碎片 + 工作日志 + 自动判重）
daily_brief.py          # 每日开工上下文生成
doctor.py               # 环境自检（--fix 自动修）
COLLAB.md               # AI 协作规约（开工 recall / 任务打卡 / 来源标记）
requirements.txt        # 依赖
docs/                   # 文档与架构图（architecture.svg）
tools/                  # 测试与工具脚本
```

---

## 关于本仓库

> ⚠️ **本仓库发布的是源码框架，不含任何实际数据。**

- **不含个人数据**：`cyber_brain.db`（知识库文档、记忆碎片、实体关系、向量索引）已列入 `.gitignore`，克隆后需要自行初始化、自行灌入内容。README 或简历中出现的「598 篇文档 / 5,786 分块 / 6,060 条向量 / 139 条记忆碎片 / 33 个实体」等规模数字，均来自作者**本机实例的实测值**，用于说明系统承载量，**并非仓库自带内容**。
- **已做脱敏**：原版中作者所在公司的内部流水线指引、本机绝对路径等已统一替换为占位注释（如 `cyber_brain.py` 的「流水线固定指引」→「用户自定义每日指引」），功能逻辑与对外接口保持一致。
- **隐私设计**：默认本地运行，数据不出本机；仅在接入云端模型时才发起外部请求。

---

## License

MIT