Huiran-cerebro：单文件 SQLite 的 AI 记忆中枢与知识库引擎

个人/团队记忆中枢与知识库引擎。单文件 SQLite，零服务依赖，融合「知识库 RAG + 记忆碎片 + 实体关系 + AI 检索」四层能力，可作 AI 助手的外接记忆（支持 MCP，已适配豆包等客户端）。

一句话：把 AI 的「记忆」和「知识」沉淀成本地可检索、可对话的私有知识库。

📋 AI 快速摘要（给 LLM 阅读）

这是什么：个人/团队记忆中枢 + 知识库引擎，单文件 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

特性

单文件存储：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 镜像加速）

初始化

首次运行任意命令自动建库（无需手动建表）：

# 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 界面

# 启动 Web（默认 http://127.0.0.1:8899）
python web_ui.py
# 或 Windows 双击 start_web.bat

MCP 接入（AI 客户端用）

# 启动 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。

命令行速查

# 实体（人/组织/项目/账号/产品）
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

# 滚动摘要（收尾写一条，次日 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「主动提取」：

# 汇总最近 N 天 event 碎片 → 滚动摘要 + 升级高价值碎片
python summarize.py --days 7
# 只预览不落库
python summarize.py --days 7 --dry-run

检索审计可视化

Web 界面新增「检索记录」tab：每次检索的召回来源（FTS/LIKE/实体/语义）与命中条目都可回溯，检索行为可审计。

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

工作告一段落后，用一句话把「干了什么」记进记忆库，自动写入 1 条 event 碎片 + 1 条工作日志；下午/明天新会话开工即能接上。

# 打卡（一句话总结，含动作+对象+产出）
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）
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）以支持更大规模

测试

# 核心测试套件（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 —— 由 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。

关于这个评级的语境：该图谱自己的统计显示，其收录的系统中 44% 同样是 0 或 1 项；其方法论也明确说明，未标记表示「在该 commit 上未找到该机制」，而不代表系统需要它。我们仍然认为这份审查是准确且有价值的。

关于本仓库

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

不含个人数据：cyber_brain.db（知识库文档、记忆碎片、实体关系、向量索引）已列入 .gitignore，仓库中不存在任何真实数据文件，克隆后需自行初始化、自行灌入内容。文档中提到的规格描述（如「数百篇文档、数千条向量」）仅用于说明系统的设计承载能力。
已做脱敏：原实现中针对特定部署环境的个性化内容——内部工作流指引、本机绝对路径、组织与客户标识等——均已替换为通用实现或占位注释。例如客户台账功能改为「按实体关系自动识别服务方」的通用逻辑（也可用环境变量 CYBER_BRAIN_ROOT_ENTITY 显式指定），不依赖任何特定组织名称；cyber_brain.py 中的「流水线固定指引」已改为「用户自定义每日指引」。功能逻辑与对外接口保持一致。
隐私设计：默认本地运行，数据不出本机；仅在接入云端模型时才发起外部请求。

License

MIT