真正记得住你、认识你、随你成长的 AI 长效认知记忆引擎
Long-term Cognitive Memory Engine for LLM Agents
"Like Andrew Martin, our mission is to cross the boundary between code and soul through memory and evolution."
像安德鲁·马丁一样，我们的使命是通过记忆与演化，跨越代码与灵魂的边界。
—— 电影《机器管家》
在线体验网站： ebbingflow.net
EbbingFlow 是一套融合 知识图谱、时序事件记忆、多轨检索、智能重排 与 Ebbinghaus 遗忘曲线 的 AI 助手记忆引擎。
它不是又一个聊天机器人，而是让任何 LLM 拥有真正长期记忆的基础设施层：把对话沉淀为可追溯、可审计、可演化的认知记忆。
当前 AI 记忆常依赖单一向量检索，容易出现不可验证、语义漂移、事实冲突和长期维护困难等问题。
EbbingFlow 做到的是：
EbbingFlow 不只保存“模型总结过的事实”，还会保留原始对话消息，并通过 source_msg_id 将 Event、Episode、Saga 与 SQL 原件关联起来。
这意味着：记忆不是黑箱摘要，而是可以追溯到原文的认知索引。
Event → 原子事实：谁在什么时候做了什么
Episode → 剧情片段：一段连续对话的上下文摘要
Saga → 长期主线：跨周、跨月的目标、关系和项目叙事
系统同时使用 Graph、Vector、SQL、BM25、Structured Events、Episode、Saga 和 Plan 检索。HybridScorer 会先判断本轮问题更偏向 fact、summary、long_term 还是 semantic，再动态调整各检索轨道的预算与权重：事实型问题优先 SQL/Graph/Structured Events，叙事型问题才提升 Episode/Saga。这样既能保留长期脉络，又避免摘要覆盖可回溯证据。
EbbingFlow 支持用户与助手的身份锚定、别名归一、Big Five 慢变量与 EFSTB 快变量画像，让 AI 不只记住事实，也能维持长期一致的相处方式。
| 工具 | 版本要求 | 说明 | 安装检查 |
|---|---|---|---|
| Python | 3.10+ | 核心后端运行环境 | python --version |
| Neo4j | 4.4+ / 5.x | 图数据库支持（支持本地部署或 AuraDB 云端） | 访问 7474 或云端连接地址 |
# 创建并安装依赖
python -m venv venv
.\venv\Scripts\python.exe -m pip install -r requirements.txt
# 复制示例配置文件
cp .env.example .env编辑 .env 文件，填入必要的 API 密钥：
# LLM API配置（支持 OpenAI SDK 格式的任意 LLM API）
OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_MODEL=deepseek-v4-flash
# 嵌入模型配置（支持完全本地与 OpenAI SDK 格式 API）
# 默认【方案 A：完全本地 (SentenceTransformers)】
EMBED_TYPE=local
EMBED_MODEL=paraphrase-multilingual-MiniLM-L12-v2
# 推荐【方案 C：OpenAI / 阿里百炼平台 兼容嵌入】
EMBED_TYPE=openai
EMBED_MODEL=text-embedding-3-small
EMBED_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBED_API_KEY=sk-your-key-her
# Neo4j 数据库配置
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j
# 提示：若不配置 POSTGRES_URL，系统将自动使用 SQLite 托底标准启动：
.\venv\Scripts\python.exe api\server.py快捷启动 (Windows)：
run.bat启动后访问：
- Interaction Hub: http://localhost:8000
- Data Monitor: http://localhost:8000/monitor
EbbingFlow 启动后会同时暴露一个本地 OpenAI 兼容接口，可供 Open WebUI、Cherry Studio、小智数字人等前端调用：
Base URL: http://localhost:8000/v1
Model: ebbingflow
API Key: local
如果前端只支持填写完整接口地址，则填写：
http://localhost:8000/v1/chat/completions
model 不传时后端会默认使用 ebbingflow；但很多前端会强制要求填写模型名，此时填 ebbingflow 即可。本地开源版暂不校验 API Key，若前端必填，可填写任意占位字符串。
请求示例：
curl http://localhost:8000/v1/chat/completions `
-H "Content-Type: application/json" `
-d '{
"model": "ebbingflow",
"messages": [
{"role": "system", "content": "请在回复开头输出 <happy>/<thinking> 情绪标签。"},
{"role": "user", "content": "我今天完成了一个重要功能。"}
]
}'外部 system / developer message 会注入 EbbingFlow 主 prompt 的 [EXTERNAL_SYSTEM_PROMPT] 区块。接入其它前端时，请删除其中的身份、角色、记忆控制类内容，只保留情绪标签、输出格式、语音合成、回复长度等适配要求。
更多细节见 OpenAI-compatible Chat API。
QQ 机器人集成示例 (可选)
EbbingFlow 支持通过 QQ 机器人进行跨平台交互，让你可以直接在移动端进行长效记忆沉淀：
- 获取凭据：登录 QQ 开放平台，创建机器人并获取
AppID与AppSecret。 - 配置环境：将获取的凭据填入
.env文件中对应的配置项。 - 启动服务：
.\venv\Scripts\python.exe integrations\qq_bot.py
现在，你就可以直接在 QQ 聊天框中与 EbbingFlow 交流互动。
如果你希望快速预览系统的核心能力，可以导入我们预置的演示数据：《重生成为诸葛亮，系统（Ebbingflow）助我成就霸业》。
- 启动服务并进入 数据审计页面 (Data Monitor)：http://localhost:8000/monitor
- 点击右上角的 导入演示数据。
- 确认警告提示后，系统将自动恢复包含完整身份画像与证据链的认知记忆。
- 注意：Demo 中古代与现代单位计算有误。这是为了展示 EbbingFlow 在面对“脏数据”输入时，依然能保证记忆可追溯、不崩盘的核心优势。
视频演示： Coming soon...
 Interaction Hub（核心交互） |
 Data Monitor（数据审计） |
用户输入
│
▼
[身份识别 / 别名归一]
└── 确定“我是谁/你是谁”，解析代词到绝对实体 ID（Actor）
│
▼
[记忆检索引擎]
├── 图谱原子检索（Event via Neo4j）
├── 图谱叙事检索（Episode + Saga）
├── 向量检索（Chroma Vector）
├── 关键词检索（BM25）
├── 结构化检索（SQL Structured Events / CRM）
└── 计划检索（Plan / Task / Schedule）
│
▼
[智能重排 HybridScorer]
├── 意图路由（fact / summary / long_term / semantic）
├── Ebbinghaus 时间衰减（含置信度护栏）
├── 多维打分（语义 / 图谱跳数 / 时间 / 影响力）
└── RRF 融合 + 意图感知配额控制
fact 优先 SQL/Graph/Structured，summary/long_term 才提升 Episode/Saga
│
▼
[LLM 生成 + 证据注入]
├── 仅注入 HybridScorer 接纳的 in_prompt 候选
├── SQL Evidence Window 回溯注入
├── [MEMORY] 事实区与 [NARRATIVE] 叙事区分离
└── 流式输出（可追溯到 source_msg_id）
──────────────────────────────────────────────
[写入沉淀链路（本轮结束后）]
├── 08 事件/事实抽取（Event / Relation / Observation / Structured Envelope）
├── 09 人格观察与身份演化
├── 10 结构化事件标准化/校验
├── 11 写入图谱、SQL 与 Episode（证据链绑定）
└── 12 Saga 聚类归并与上下文同步（长期主线）
EbbingFlow 并非简单的向量存储，而是一套具有层级感、可审计、可演化的认知引擎。
- 三层递进记忆：构建
Event (原子)→Episode (片段)→Saga (主线)的认知抽象，模拟人类自传体记忆。 - 全链路证据闭环：每一条认知判断均可通过
source_msg_id100% 溯源至原始对话，杜绝“黑箱摘要”。 - 意图感知检索优先级：事实型问题强制优先 SQL/Graph/Structured Evidence；Episode/Saga 作为叙事脉络辅助，不覆盖原文证据。
- 人格连续性：集成 Big Five (慢变量) 与 EFSTB (快变量) 身份画像，让 AI 不只记住事实，更能在长期相处中“认识你”。
| 层级 | 模块 | 存储/索引 | 记录什么 | 认知作用 | 证据溯源 |
|---|---|---|---|---|---|
| 1 | SQL 主存 | SQLite / PostgreSQL | 1:1 原始对话全量 | 权威原件、审计终点 | True Source |
| 2 | Event 事件层 | Neo4j | 原子事实 (5W1H) | 细节索引、实体推理 | 回链 SQL |
| 3 | Episode 剧情层 | Neo4j | 连续对话片段摘要 | 中短期上下文脉络 | 关联事件回链 |
| 4 | Saga 主线层 | Neo4j | 跨月长期目标/项目叙事 | 长期稳定记忆与连续性 | 关联 Episode 回链 |
| 5 | Vector 语义轨 | ChromaDB | 对话/文档向量片段 | 模糊语义召回、语气唤醒 | 辅助索引 |
| 6 | Identity 层 | Neo4j + Session | Big Five / EFSTB 画像 | 身份一致性与策略个性化 | 观测记录可追踪 |
| 7 | HybridScorer | 评分引擎 | 多轨候选集重排 | 意图路由、Ebbinghaus 衰减、RRF 与动态配额控制 | 审计打分路径 |
Tip
每一个 MemoryEvent 都包含了 impact_score、confidence 以及 source_msg_id，确保了记忆的每一根神经末梢都能追溯到最初的感官输入。
STATE_CHANGE → 换工作、搬家、改名、状态变化
INTERACTION → 开会、聚餐、争吵、沟通互动
CONSUMPTION → 购物、看电影、消费支付
PLAN → 计划辞职、打算旅行、待办安排
OPINION → 认为某事不对、观点表达、态度判断
ACHIEVEMENT → 升职、完成项目、达成目标
RELATIONSHIP → 认识新朋友、结婚、关系变化
OTHER → 无法归入以上类别的通用事件
每条 MemoryEvent 的核心字段：
subject + object + predicate + action_type + context
+ timestamp_reference/event_time + emotion_label
+ impact_score + confidence + source_msg_id (+ event_metadata)
| 维度 | 技术选型 |
|---|---|
| 核心框架 | |
| 图谱存储 | |
| 向量检索 | |
| 结构化存储 | |
| 核心算法 | BM25 + RRF + HybridScorer (Ebbinghaus 时间衰减) |
| LLM 接入 | OpenAI-compatible API (Kimi / GPT / Claude / DeepSeek) |
- 身份锚定系统：支持多别名归一化与 Dual-Layer Profile。
- 统一身份引擎：实现 Big Five 与 EFSTB 双轴人格推理。
- 四轨融合架构：Vector + Graph + SQL + BM25 的 RRF 融合。
- 可审计证据链：核心认知判断可回溯到原始消息。
- 多模态情绪解析：支持文字、语调或穿戴设备指标。
- 主动关怀与提醒：基于长期事件在重要时间点主动触发。
- 离线记忆整合：模拟睡眠式 consolidation，压缩与固化长期记忆。
- 意图驱动操作系统：从“对话”走向可审计的外部动作调用。
- 开源社区版（Community）：包含核心认知记忆引擎，适合个人开发者、研究者与 AI Agent 项目使用。
- 商业授权版（Enterprise/Pro）：面向需要高可用、强合规、身份迁移和记忆精确回撤能力的企业级场景。
我们正在寻找战略合作伙伴、研究协作者与早期使用者，共同推进长期记忆基础设施。
- WeChat: [aiassisbot]
- Business Inquiries: [update later]
本项目基于 Apache License 2.0 协议开源。
第三方依赖许可请参阅 THIRD_PARTY_LICENSES.md。