🇨🇳中文 | 🌐English

dual-mem: Dual-System Layered Memory SDK

dual-mem 让 Agent 真正记住用户——不是堆聊天记录，而是像人一样：先快速记下今天说了什么，再慢慢整理成用户画像、习惯和未来打算。分层存储、偏好会变就更新、检索时自动带出相关记忆。通过 SDK / REST / MCP / CLI / Skill 即插即用。

记忆架构（L0–L7）

dual-mem 的核心是一套 八层记忆模型——借鉴人脑「先感知、再编码、再巩固、再抽象」的分层过程，从原始对话一路沉淀到画像、习惯与打算，并带 演化链（偏好变了留历史，不粗暴覆盖）：

偏好变了（Java → Python）不会覆盖旧记录，而是 演化链 保留历史，读的时候给你 最新版 + 变更轨迹。

双系统：短期记忆 × 深度记忆

对话 add ──▶ System1 短期记忆（秒级可用）
                │
                └──▶ System2 深度记忆（dual：后台巩固，越用越准）

检索侧按 画像 / 主动推荐 / 常规记忆 三路分组，语义 + 关键词混合召回，读记忆不额外调 LLM（只需 embedding）。

为什么选 dual-mem

🔥 News

• [2026/06/20] v0.1.2：MemoryOperations 统一 REST/MCP；SyncMemoryClient；CLI messages；post-extract embed 合并；MCP 启动修复与文档。
• [2026/06/19] v0.1.1：Attentional Gate 改为 LLM 主路径（失败降级启发式）；依赖拆分为 [api] / [cli] / [mcp] extras；默认 hybrid 读路径。
• [2026/06/18] v0.1.0：首版开源 — system1 / dual 两档、演化链、REST /v1/memories/ 契约、MCP 工具集。

架构一览

  你的 Agent / 应用
        │  SDK · REST · MCP · CLI · Skill
        ▼
   MemoryClient（写入 System1 / 检索 / 演化链）
        │
   向量 + 图 + 本地存储

实现细节（Gate、Reconcile、混合检索管线等）见 架构文档 · 在线文档。

安装

需要 Python ≥ 3.11。

pip install dual-mem              # 核心 SDK
pip install dual-mem[all]         # + REST / CLI / MCP

开发安装：

git clone https://github.com/shibing624/dual-mem.git
cd dual-mem
pip install -e ".[dev]"

快速开始

脚本 / 同步应用（推荐入门）：

from dual_mem import SyncMemoryClient

with SyncMemoryClient(mode="system1", storage_dir="./.dual_mem_data") as client:
    client.add(
        content="我最爱的编程语言是 Java，已经用了5年。",
        user_id="alice",
    )
    res = client.search(
        query="用户的编程语言偏好",
        user_id="alice",
    )
    for m in res.memories.profile:
        print(m.content)

FastAPI / asyncio Agent 用异步客户端（同一内核，可 await）：

import asyncio
from dual_mem import MemoryClient


async def main():
    client = MemoryClient(mode="system1", storage_dir="./.dual_mem_data")
    await client.add(content="...", user_id="alice")
    await client.aclose()


asyncio.run(main())

配置位于 ~/.dual_mem/config.yaml（首次启动自动创建）。LLM 与 Embedding 两套 API key 均必填。

→ 参数详解、多轮对话、aclose()、Agent 集成最佳实践见 Quickstart 文档（在线：Quickstart）。

功能特性

• 八层记忆 + 演化链 — 从 raw 对话到行为模式、意图，偏好变更可追溯
• System1 短期记忆 — 写入即结构化；过滤寒暄，只记有价值的信息
• System2 深度记忆（dual）— 后台归纳 L6/L7，越聊越懂用户
• 混合检索 — 语义 + 关键词；画像 / 主动 / 常规三路召回
• 同步 & 异步 SDK — SyncMemoryClient 给脚本；MemoryClient 给 FastAPI / Agent
• OpenAI 兼容 — 任意 LLM / Embedding 端点
• 单产品默认 — 省略 app_id 时用 default_app_id（默认 "default"）；user_id 为主隔离键

两档模式

REST / MCP / CLI

pip install dual-mem[all]

dual-mem serve --host 0.0.0.0 --port 8000          # REST
dual-mem-mcp                                          # MCP stdio
dual-mem-mcp --transport streamable-http --port 8765 # MCP HTTP /mcp
dual-mem add --content "用户喜欢咖啡" --app-id default --user-id u1
dual-mem search "饮品偏好" --app-id default --user-id u1
dual-mem digest   # dual：触发 System2

REST 契约：POST /v1/memories/、POST /v1/memories/search、GET|DELETE /v1/memories/{id} 等。MCP 分 本地 uvx（已实现）与 云端 HTTP（REST 底座已就绪，HTTP MCP 待封装）两条路径，详见 MCP 接入。

示例

查看 examples/ 获取完整示例，涵盖：

→ 查看完整示例目录

python examples/01_system1.py
python examples/02_dual.py
python examples/03_rest_api.py
python examples/04_cli.py

示例需真实 LLM + Embedding API key，会产生少量费用。

文档

完整使用文档：https://shibing624.github.io/dual-mem

本地预览：

pip install -r requirements-docs.txt
mkdocs serve

社区与支持

• GitHub Issues — 提交 issue
• 微信群 — 添加微信号 xuming624，备注 "llm"，加入技术交流群

引用

如果您在研究中使用了 dual-mem，请引用：

Xu, M. (2026). dual-mem: Dual-System Layered Memory SDK for LLM Applications. GitHub. https://github.com/shibing624/dual-mem

许可证

Apache License 2.0

贡献

欢迎贡献！请查看 CONTRIBUTING.md。

致谢

• chromadb/chroma — 向量存储
• kuzudb/kuzu — 图存储
• tiangolo/fastapi — REST 层
• modelcontextprotocol/python-sdk — MCP 集成
• mem0ai/mem0 — 记忆 SDK 生态