🤔 aiduMEM — AI 思想引擎

优忆思理念——有上下文优化，有记忆体系，有思考集成

不只是记忆 — 是思考。

优化不是改重构代码，而是植入优秀的逻辑；
记忆不是记事，而是不忘过往的点点滴滴；
思考不是 reasoning，而是做所有事都有 reason，有 result。

中文 | 📖 English

aiduMEM 是什么？

aiduMEM（优忆思）是一个 AI 思想引擎 —— 为 AI Agent 提供持久化记忆与推理能力。它不是简单的键值存储，而是让 AI 会记忆、会思考、会进化。

基于 mem0 构建，aiduMEM 在其之上搭建了一套完整的 认知架构：

架构

┌──────────────────────────────────────────────────┐
│              🤔 aiduMEM — AI 思想引擎             │
│              FastAPI REST API :8767               │
├──────────────────────────────────────────────────┤
│  hot/        → 搜索、添加、增删改查（主路径）       │
│  speed/      → 异步合并 + 快速通道                 │
│  pipeline/   → 召回漏斗 + 混合检索                 │
│  salience/   → 信任评分 + 冲突检测                 │
│  legacy/     → 事实、观察、场景                    │
│  extended/   → 自动记忆、工作区、广播               │
│  federation/ → 多 Agent 联邦 · MoE 门控             │
├──────────────────────────────────────────────────┤
│  mem0（向量记忆）+ Qdrant（向量存储）              │
│  facts.db（结构化知识）                            │
│  FTS5 trigram（全文搜索兜底）                      │
└──────────────────────────────────────────────────┘

快速开始

方式一：从 PyPI 安装（最快捷）

pip install aidumem

方式二：Docker 容器运行（GitHub Packages / GHCR）

docker pull ghcr.io/monkey2jack/aidumem:latest
docker run -d -p 8767:8767 --name aidumem ghcr.io/monkey2jack/aidumem:latest

方式三：源码克隆运行

# 1. 克隆
git clone https://github.com/monkey2jack/aiduMEM.git
cd aiduMEM

# 2. 创建虚拟环境
python3.12 -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置（复制并编辑）
cp mem0_config_local.json.example mem0_config_local.json
# 编辑 mem0_config_local.json，填入你的 LLM 和 Embedding API Key

# 5. 启动
python api_server.py
# API 运行在 http://localhost:8767

接口列表

示例：搜索

curl -s -X POST http://localhost:8767/search \
  -H "Content-Type: application/json" \
  -d '{"query": "我之前说过项目截止日期是什么？", "user_id": "me", "limit": 5}'

示例：添加记忆

curl -s -X POST http://localhost:8767/add \
  -H "Content-Type: application/json" \
  -d '{"messages": "[{\"role\":\"user\",\"content\":\"项目截止日期是3月15号\"}]", "user_id": "me"}'

aduMEM 的独特之处

🔮 相关性闸门（Relevance Gate）

普通 RAG 系统对每条消息都去搜索记忆。aiduMEM 的相关性闸门用启发式 + 动态实体匹配判断当前消息是否真的需要记忆检索。日常闲聊直接跳过 → Token 消耗降低 100 倍，响应速度从 10ms 降到 1ms。

🌊 潮浪并忆（Tidal Coalescing）

短消息不逐条调用 LLM。异步缓冲后按 session 分组，一次 LLM 调用处理多条。Tech/intimate/default 三档策略，快冲慢攒各取所需。

⏳ 遗忘曲线衰减（Ebbinghaus Decay）

记忆有保质期。Identity 和 Preference 是永久轨道（零衰减），Emotion 是加速衰减（1.5 倍），一般事实按标准遗忘曲线自然消退。让 AI 学会忘记不重要的事。

🕰️ 克罗诺斯双时间轴（Chronos Dual Timeline）

valid_from / valid_to 时间窗口：过期事实降权但不删除，未生效事实排在后面。所有铁律类记忆（identity/preference lane）永不过期。

🏛️ 万神殿联邦记忆（Pantheon Federation）

万神殿里住着所有神，但每次只请出需要的那一位。

借鉴 MoE（Mixture-of-Experts）思想：底层建成完整的多 Agent 联邦基础设施，日常只激活当前 Agent 的热通道。

• 联邦身份：每条记忆都带 agent_id / profile / shared，多个 Agent 可共用一套库而互不污染
• MoE 门控：默认走热通道（一次 SQL，5ms 级）；仅在显式请求或查询含联邦意图时才唤起其他 Agent。单 Agent 环境永远不付联邦成本
• 四级无缝降级：L1 本 Agent → L2 分层加权 → L3 同 profile 联邦 → L4 跨 profile 全局。任何一级异常自动跳下一级，永不整链失败
• 分层衰减：episodic 事件 30 天、semantic 配置 180 天、procedural 铁律永不衰减。衰减只降权不删行
• 写入去重：Jaccard 三态判定——≥0.85 合并、≥0.70 更新、<0.70 新增。不写垃圾比事后清理便宜一百倍
• 游标广播：拉取其他 Agent 的新共享事实，不重不漏、只读聚合不产生副本

# 注册一个 Agent 到联邦
curl -X POST "http://localhost:8767/federation/agents/register?agent_id=agent_b&profile=default"

# 联邦检索（门控自动决策）
curl "http://localhost:8767/federation/recall?query=项目截止日期&agent_id=agent_b&top_k=5"

🛡️ 埃癸斯护盾（Aegis · v14 新增）

神盾护住的不是代码，是代码背后的人。

仓库里没有任何硬编码的身份、绝对路径、服务器地址或密钥。仓库根由 __file__ 自动解析，一切可变项走环境变量注入（见 环境变量）。克隆到任何目录、任何机器，python api_server.py 直接跑。

🌈 伊里斯彩虹桥（Iris · v15 新增）

信使不只送信，还要确认信真的送到了。

v15 起 aiduMEM 提供 Hermes Agent 官方 MemoryProvider 插件，不再依赖 shell hook
解析 payload 字段：

cp -r integrations/hermes-plugin/aidumem ~/.hermes/plugins/
hermes config set memory.provider aidumem

接通后拿到全套生命周期钩子——turn 开头注入常驻块与相关检索、每轮后台归档、
压缩前把即将丢掉的对话先落进长期记忆、镜像宿主内置 MEMORY.md 写入、
三个可直接调用的工具（aidumem_search / aidumem_remember / aidumem_status）、
数据目录纳入宿主备份。详见 integrations/INTEGRATION_GUIDE.md。

同版本一并修掉了三类静默失效——注入链断了不出声、词表漏配了不出声、
启动缺配置不出声。现在都会明确告警：

• shell hook 的 payload 解析改为三层兼容（extra.conversation_history / 顶层 / 旧 messages）
• 相关性闸门与实体抽取的词表改为惰性编译 + 热更新，不再在 import 时定死
• AIDUMEM_ENTITY_KEYWORDS 未配置时，启动日志与 /health 探针都会显式提示

🔧 零配置混合检索

BM25 trigram（零延迟兜底） + BGE-M3 向量 + Reranker 重排序 + 召回漏斗相关性排序。向量服务超时自动热切换到本地全文搜索。

接入 Hermes Agent

两种方式不要同时开（会重复注入白烧 token）。完整步骤、验证方法与回滚见
integrations/INTEGRATION_GUIDE.md。

⚠️ 安全：aiduMEM 服务自身不做鉴权，默认只监听 127.0.0.1。要跨机访问请在前面
挂带认证 + TLS 的反向代理，别把服务直接暴露到公网——那等于把全部记忆公开可读可写。

技术栈

• 运行时：Python 3.12+、FastAPI、Uvicorn
• 记忆内核：mem0 v2.0.5
• 向量存储：Qdrant（通过 qdrant-client）
• 结构化数据：SQLite（facts.db、observations.db、scenes.db）
• 全文搜索：SQLite FTS5 + trigram 分词器
• 向量化：可配置（兼容 OpenAI Embedding API）
• 重排序：可配置（兼容 OpenAI Rerank API）
• 大模型：兼容任何 OpenAI 格式的 API

配置说明

aiduMEM 从 mem0_config_local.json 读取配置。主要字段：

{
  "llm": {
    "provider": "openai",
    "config": {
      "model": "你的模型",
      "api_key": "你的密钥",
      "base_url": "你的接口地址"
    }
  },
  "embedder": {
    "provider": "openai",
    "config": {
      "model": "BAAI/bge-m3",
      "api_key": "你的密钥",
      "base_url": "your-embedding-endpoint"
    }
  },
  "vector_store": {
    "provider": "qdrant",
    "config": {
      "collection_name": "aidu_mem",
      "host": "localhost",
      "port": 6333
    }
  }
}

环境变量

v14 Aegis 起，所有与部署环境相关的可变项都通过环境变量注入，全部可选——不设置就走安全默认值。

完整清单连注释见仓库根的 .env.example，cp .env.example .env 起步。
systemd 单元模板见 deploy/aidumem-api.service。

例：把数据放到独立盘、自定义实体词表

export AIDUMEM_DATA_DIR=/data/aidumem
export AIDUMEM_ENTITY_KEYWORDS="Alice|Bob|ProjectX"
python api_server.py

路线图

• MCP（Model Context Protocol）服务端模式
• 多 Agent / 多 Profile 联邦记忆（v13.0 Pantheon ✅）
• 零硬编码可移植部署（v14.0 Aegis ✅）
• Hermes 官方 MemoryProvider 插件（v15.0 Iris ✅）
• 跨机器联邦（HTTP 对端拉取，非同库）
• 多用户工作区隔离
• 记忆整合仪表盘
• 自定义衰减曲线插件系统
• REST API → GraphQL 适配器

参与贡献

欢迎贡献！请先开一个 Issue 讨论你想做的改动。

许可证

MIT 许可证 — 详见 LICENSE。

_{思考版本 · Iris·伊里斯 | 由 monkey2jack & Aowen 构建}