cyber-brain
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Huiran-cerebro · 赛博大脑
个人/团队记忆中枢与知识库引擎。单文件 SQLite,零服务依赖,融合「知识库 RAG + 记忆碎片 + 实体关系 + AI 检索」四层能力,可作 AI 助手的外接记忆(支持 MCP,已适配豆包等客户端)。
一句话:把 AI 的「记忆」和「知识」沉淀成本地可检索、可对话的私有知识库。
这是什么:个人/团队记忆中枢 + 知识库引擎,单文件 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_chunkRAG 知识库(自动分块、向量列预留)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 客户端
Related MCP server: light-agent-memory-mcp-server
界面预览
以下截图全部取自虚构的演示数据(
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.batMCP 接入(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
# 记忆分区:不传 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「主动提取」:
# 汇总最近 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/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)以支持更大规模
测试
# 核心测试套件(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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Cross-tool persistent memory and context for AI assistants over MCP.
Shared MCP memory for AI agents: knowledge base, skills, todos and agent-to-agent handoffs.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides persistent, inspectable memory storage for AI agents using SQLite. Agents can store, recall, and search memories across sessions via three MCP tools.3MIT
- AlicenseAqualityDmaintenanceProvides persistent, searchable memory for AI agents across any MCP-compatible client, storing project context, user preferences, and session learnings locally in SQLite with tools to save, retrieve, search, and manage them.12MIT
- AlicenseBqualityBmaintenanceLocal long-term memory service for AI agents via MCP, using SQLite with tools for memory CRUD, semantic search, time-based facts, and graph capabilities.2720 npm1MIT
- AlicenseBqualityBmaintenanceEnables MCP-capable AI clients to share one local SQLite-backed memory of preferences, decisions, tasks, and handoffs across sessions and models. It supports saving, searching, recalling, exporting, and restoring context through tools like remember, recall, get_context, and save_handoff.7MIT







