双系统架构：System1 与 System2

dual-mem 在顶层将记忆处理划分为两个相互协作的子系统，对应 Kahneman 双过程理论的工程化映射：

• System1（默认模式）：负责 LLM 驱动的提取、摘要、对账（reconcile）、基础画像维护以及 MemAgent 编排。dual_mem/agent/ 子包即为此子系统。资料来源：dual_mem/agent/__init__.py
• System2（dual 模式启用）：通过聚类、Agent 循环、工具调用、回写与跨领域扫描，把 L2/L4 事实蒸馏为 L6 Schema 与 L7 Intention。资料来源：dual_mem/system2/__init__.py

两种模式由 mode 字段控制：system1 适合助手、客服机器人等快速集成场景；dual 在此基础上开启图关联与背景/定时蒸馏，适合深度用户建模、意图与行为模式抽取。资料来源：README_EN.md

flowchart LR
    User[用户/Agent] -->|write| W[Writer 子包<br/>dual_mem/writer]
    W --> S1[System1<br/>agent/* 提取/摘要/对账]
    S1 --> L0["L0–L5 节点<br/>短期与事实层"]
    L0 -->|background| S2[System2<br/>system2/* 聚类/蒸馏]
    S2 --> L6L7["L6 Schema / L7 Intention"]
    L0 --> R[Retrieval 子包<br/>三路召回 + 演化链展开]
    L6L7 --> R
    R --> User

L0–L7 分层记忆模型

dual-mem 的记忆按语义抽象度从原始对话到深层行为模式分为 8 个层级：

L2 与 L4 由 dual_mem/agent/prompts.py 中的提取提示词显式产出；layer 字段接受 "l2_fact" 或 "l4_identity"。资料来源：dual_mem/agent/prompts.py

L6/L7 由 System2 在背景或定时触发时产出：create_schema 与 create_intention 是两类核心操作，schema 内容创建后不可变。资料来源：dual_mem/system2/__init__.py

演化链（supersedes）

同一维度上的状态演进（如所在地、职业、长期偏好）通过显式 supersedes 指针串成链。SDK 读侧会自动展开 evolution_chain，供 LLM 看到完整历史。资料来源：dual_mem/sdk_models.py

典型链结构（A 为最新、C 为最旧）：

• A：「用户搬到东京。」
• B：「用户搬到上海。」(supersedes C)
• C：「用户住在北京。」

注意：偏好并存（如「喜欢咖啡」+「也喜欢茶」）不构成链，应作为独立 ADD。

三路召回与混合检索

读侧默认走 hybrid 路径：无 LLM、含 embedding；通过 5 路 anchor 检索 + fusion 重排。retrieval/ 子包提供三路分类：profile（画像）、proactive（前摄）、normal（普通）。资料来源：dual_mem/retrieval/__init__.py

retrieval/intent.py 通过概念性触发词（how、why、风格、模式等）和导航噪声正则将查询路由到最合适的召回路径。资料来源：dual_mem/retrieval/intent.py

retrieval/formatter.py 负责把三类结果合并为带日期前言的上下文字符串，默认仅渲染当前 head，include_superseded=True 时展开历史版本。

接入模式

dual-mem 提供 5 种接入方式：SDK（MemoryClient 异步、SyncMemoryClient 同步）、REST、CLI、MCP、Skill。REST 与 MCP 共享同一份 MEMORY_TOOL_CONTRACTS，由 MemoryOperations 统一实现，保证 tool 名与 HTTP 路径一一对应。资料来源：dual_mem/api/contracts.py

CLI 示例（v0.1.2 起支持 --content 或 --messages-file/--messages-json 二选一）：

dual-mem add --content "用户在深圳做 ML" --user-id u1
dual-mem add --messages-file messages.json --user-id u1
dual-mem search "drink preference" --user-id u1
dual-mem digest   # dual 模式：触发 System2 蒸馏

默认情况下省略 app_id 即使用 default_app_id="default"；user_id 是主要的隔离键。资料来源：README_EN.md

常见失败模式与注意

• 混淆链与并存偏好：对「新增爱好」错误使用 supersedes 会让历史被遮蔽。资料来源：dual_mem/agent/prompts.py
• storage_dir 未自动创建：v0.1.2 起 SDK 已自动建目录，但旧版本需手动 mkdir。
• System2 仅在 dual 模式运行：system1 模式下 digest 命令无效。
• 意图路由偏差：包含 ID、URL、版本号等导航噪声的查询可能被错误路由，建议在 prompt 侧先归一化。

另见

• README_EN.md
• mkdocs.yml — 文档站点导航与扩展配置
• skills/dual-mem/SKILL.md — Agent Skill 接入约定
• examples/_common.py — 演示如何以独立 storage_dir 复现 demo

概览

dual-mem 的写入链路是 system1 模式下的核心数据通路。每当调用方执行 client.add(content=...) 或 client.add(messages=[...]) 时，写入链路会按顺序触发三个 LLM 驱动的处理阶段：Attentional Gate → Extractor → Reconciler。前两个阶段由 MemAgent 串行调度，落库后由 Reconciler 在向量召回的基础上合并演化链。

该链路的关键设计目标是：

• 过滤低价值信息：通过 Gate 计算 novelty / biographical_relevance / emotional_arousal，避免把"纯寒暄"灌入存储。
• 结构化抽取：Extractor 把对话/段落拆分为 identity / facts / intentions / basic_info / emotion / is_ephemeral 等字段，第三人称、自包含。
• 演化追踪：Reconciler 把新记忆与既有 L2/L4 节点做向量检索，按 supersedes 指针形成"演化链"，确保旧认知可追溯。

flowchart LR
    A["add(content or messages)"] --> B["Gate<br/>novelty/biography/arousal"]
    B -->|通过| C["Extractor<br/>identity/facts/intentions"]
    B -->|降级启发式| C
    C --> D["fast-write<br/>L2_FACT / L4_IDENTITY"]
    D --> E["Reconciler<br/>向量召回 + LLM 决策"]
    E --> F["ADD / DELETE<br/>supersedes 链头更新"]
    F --> G[(存储层<br/>nodes + edges)]

资料来源：dual_mem/agent/__init__.py:1-7 资料来源：examples/01_system1.py:1-13

各阶段职责

Gate：注意门控

Gate 与 Extractor 在同一次 LLM 调用中完成输出，避免额外往返。提示词要求模型在 JSON 顶层附带 gate_decision 对象，包含 novelty、biographical_relevance、emotional_arousal 三个 0.0–1.0 维度分数，以及 reason 简短理由。当 LLM 调用失败时，链路会降级为启发式判断，保证写入不被阻塞。

资料来源：dual_mem/agent/prompts.py:EXTRACT_GATE_APPEND_ZH

Extractor：结构化抽取

Extractor 输出 is_ephemeral、emotion、identity、facts、intentions、basic_info 等字段，并对每条记忆生成 1–3 个 tags。is_ephemeral=true 时下游不再写入；否则按 layer 字段（L2_FACT 或 L4_IDENTITY）落到对应存储桶。

抽取阶段还支持多轮对话 messages 输入：当整段对话超过上下文比例时，仅截断 assistant 轮，user 轮始终完整保留，因为它是"记忆主信号"。role=system 的消息在 add 时会被丢弃。

资料来源：dual_mem/agent/prompts.py:EXTRACT_ZH 资料来源：dual_mem/config.default.yaml:extract_history_context_ratio

fast-write：直落 L2/L4

抽取结果不经过 System2 的 ReAct 循环，而是直接以 add 原子的方式写入 L2_FACT 与 L4_IDENTITY 节点。该路径默认 reconcile_sync=false，即写入立即返回，演化链合并异步进行；如需同步演化，可在配置中开启 reconcile_sync=true。

资料来源：examples/01_system1.py:11-13 资料来源：dual_mem/config.default.yaml:reader_mode

Reconciler：演化链合并

Reconciler 的核心流程包含四步：

1. 向量召回：对新记忆（可选地先用 LLM 改写查询）做 embed，在 L2/L4 ACTIVE 层检索候选。
2. 进化链合并：_merge_chains 把候选按链头分组，附带 history_versions。
3. LLM 决策：中英 prompt（RECONCILE_ZH/EN）输入新旧记忆，要求输出 updates 数组；supersedes 与 tags 是数组类型，未变更时输出 {"updates": []}。
4. 解析校验：_parse_ops 归一化 LLM 输出，去重冲突的 supersedes / DELETE。

输出操作类型包括 ADD（含 supersedes 旧节点）、DELETE（软删，标 SHADOW / is_latest=False），并附带 update_type（OVERRIDE / SUPPLEMENT / TEMPORAL / NEGATE / CONFLICT），由下游写入 node.custom。

资料来源：dual_mem/agent/reconciler.py:核心流程（Reconciler.reconcile）

演化链与 supersedes

演化链（evolution_chain）是 dual-mem 的核心数据结构。一条链代表同一维度上的状态演化，例如"所在地"、"编程语言偏好"。

链的语义约定：

• 同主题不同时态：链 A → B → C（A 最新，C 最旧）描述的是同一维度上的不同认知；A 是当前真值，B/C 是历史声明。
• 附加信息保留：B/C 在被取代时，可能仍携带其他维度上的有效信息，这些信息不会被删除，而是由新节点选择性吸收。
• 共存不取代：并列偏好（如"喜欢咖啡" + "也喜欢茶"）应通过 ADD 独立写入，而不是 supersedes。

Reconciler 决策时严格区分"取代"与"补充"：高召回保守模式下，禁止把多条记忆合并成一条，不同实体/日期/对象的事件必须独立保留。

资料来源：dual_mem/agent/prompts.py:RECONCILE_ZH 段落 Understanding supersedes chains 资料来源：dual_mem/agent/prompts.py:RECONCILE_POLICY_CONSERVATIVE_ZH

MemoryItem.to_dict() 在序列化时会自动展开 evolution_chain，把每个 EvolutionItem 的 content 与 memory_at 一并输出，便于上层调用方一次性读取完整历史。

资料来源：dual_mem/sdk_models.py:to_dict 字段说明

配置开关

写入链路的关键参数集中在 dual_mem/config.default.yaml，下表列出与本主题最相关的条目：

资料来源：dual_mem/config.default.yaml:extract_* / embed_merge_l1_gate / reader_mode

典型用法与失败模式

正确用法：add(content=...) 用于单条稳定画像；add(messages=[...]) 用于会话结束批量写入。memory_search 应在 memory_add 之前或之后按需调用。

应避免的写入：纯寒暄、临时上下文、"ok / thanks" 类无实质内容的输入应在 Gate 阶段被识别为 is_ephemeral=true，不要直接落库。

失败模式：

• Gate / Extractor 的 LLM 调用失败时，会走降级启发式，不会阻塞写入，但抽取质量会下降。
• Reconciler 的 LLM 输出若违反 JSON 格式或类型约束，会被 _parse_ops 拒绝整批操作；此时新记忆以"未合并"状态留在存储中，需要后续重试。

资料来源：skills/dual-mem/SKILL.md:何时写入 / CLI 示例 资料来源：examples/01_system1.py:期望：第二轮写入后，"现在用什么编程语言"应命中 Python，并附 Java→Python 演化链

See Also

• 架构总览
• 快速上手
• MCP 集成
• 读路径：hybrid / legacy 模式在 dual_mem/retrieval/__init__.py 中定义
• 系统 2 异步精炼：dual_mem/system2/__init__.py

1. 概述与设计目标

dual_mem/retrieval 子包负责记忆系统的读侧（reader），核心职责是把用户查询转换为高质量、可解释的召回结果。其模块级 docstring 明确指出：包含三路由召回、演化链展开、意图分类以及 hybrid（向量 + BM25）重排工具 资料来源：dual_mem/retrieval/__init__.py:1-7。

自 v0.1.1 起，混合模式（reader_mode: hybrid）取代传统三路由成为默认读路径：无需调用 LLM、仅依赖 embedding 即可完成主要工作；通过 5 路 anchor + 融合排序（fusion）实现高召回。社区 release notes 也将该点作为重点升级列出 资料来源：v0.1.1 Highlights（README_EN.md / release tag）。

设计目标可归纳为三条：

1. 无 LLM 也能跑：默认 hybrid 路径不依赖 LLM 推理，仅靠 embedding + 启发式 + BM25 即可工作，便于离线/低延迟场景。
2. 结构可解释：每条召回结果携带 category（profile / fact / identity / schema / intention / raw 等）、score、tags 和可选的 evolution_chain，上层 Agent 可基于类别与分值做后处理 资料来源：dual_mem/sdk_models.py:1-40。
3. 演化链透明：写入时显式的 supersedes 指针在读侧自动展开为 evolution_chain（新→旧），让模型看到「同一维度上状态的迁移」 资料来源：dual_mem/agent/prompts.py:1-30。

2. 混合检索的总体架构

混合检索的输入是一个查询字符串（也支持 messages 形式），输出是一组 MemoryItem 对象。下图展示了核心模块协作关系。

flowchart LR
    Q[query] --> A[intent classification<br/>retrieval/intent.py]
    A --> R[anchor_search<br/>5 路 anchor 召回]
    R --> E[evolution chain expansion<br/>reader.py]
    E --> H[hybrid_engine<br/>融合排序]
    H --> S[hybrid_scoring<br/>语义 + BM25 加权]
    S --> F[fusion_scorer<br/>图证据加成]
    F --> O[MemoryItem 列表]

各模块的角色如下：

• retrieval/intent.py：对查询做导航/概念类意图分类，使用 _NAV_REGEX 识别版本号、URL、UUID 等导航型查询，使用 _CONCEPTUAL_TRIGGERS 识别「怎么、为什么、整体风格」等概念型查询 资料来源：dual_mem/retrieval/intent.py:1-40。
• retrieval/anchor_search.py：负责 5 路 anchor 召回（典型包含：原查询向量、查询扩展向量、profile/fact/schema/intention 分层 anchor），把不同入口命中的节点收集到统一候选池。
• retrieval/reader.py：读侧编排器，把意图分类结果路由到 anchor 召回，并在召回后触发演化链展开。
• retrieval/hybrid_engine.py：融合多路 anchor 召回结果，去重并产生候选池。
• retrieval/hybrid_scoring.py + retrieval/bm25.py：在候选池内做 语义相似度 × BM25 加权重排。
• retrieval/fusion_scorer.py：把图存储中的 L6 Schema 证据做加成（hybrid_evidence_boost_max 上限、hybrid_evidence_saturate 饱和计数）。

3. 配置参数与权重

混合检索的全部旋钮集中在 dual_mem/config.default.yaml 中，便于调优召回质量与延迟。

资料来源：dual_mem/config.default.yaml:读路径段。

权重 0.6 / 0.4 体现了 hybrid 的设计哲学：以语义为主、关键词为辅——BM25 在长尾、专有名词、版本号等场景下补足纯向量召回的盲点；而图证据加成（最大 0.3）则让 L6 Schema 在分数上压过零散 L2 Fact，引导上层 Agent 优先选择已凝练的行为模式而非单条事实。

4. 演化链展开与结果结构

读侧的最后一环是把 supersedes 链展开为 evolution_chain 字段。社区 release 明确指出：显式 supersedes 指针在读侧会自动展开历史 资料来源：v0.1.1 Highlights。MemoryItem 上的字段语义如下：

• evolution_chain：同主题演化历史（新→旧），无链时为 None。
• category：路由类别（profile / fact / identity / schema / intention / raw），便于上层做条件渲染。
• tags：1–3 个小写主题关键词，优先复用已有标签以减少标签碎片化（写入时 prompt 中已约束） 资料来源：dual_mem/agent/prompts.py:1-50。
• memory_at / gmt_created / gmt_modified：三段时间戳分别表示对话时间、入库时间与最后修改时间，辅助时序判断。

典型使用模式：Agent 在收到 evolution_chain 不为空的 MemoryItem 时，应将其视作「一个维度的状态迁移」而非「多条独立事实」。例如居住地维度 A→B→C：A 是当前真值，B/C 可能在其它维度仍携带有效信息，需要分别判别后再消费 资料来源：dual_mem/agent/prompts.py:Understanding supersedes chains 段。

5. 常见失败模式与排查

1. 查询被误判为导航型：URL/版本号正则 _NAV_REGEX 命中过宽，导致概念型查询走了短路径。检查 query 是否含 v\d+\.\d+ 等模式。
2. BM25 权重过大致长尾主导：当语料以专有名词为主时，把 hybrid_w_bm25 调高（如 0.5）；反之偏向语义。
3. 图证据加成饱和：当 L6 Schema 数远大于 hybrid_evidence_saturate（默认 5）时，加成被夹紧到 0.3 上限；可通过提升上限或先做更细粒度分面来缓解。
4. 演化链未展开：通常是写入侧未生成 supersedes 指针（Reconcile 步骤被跳过），需检查 extract_retry_on_failure 与 LLM 调用日志 资料来源：dual_mem/config.default.yaml:extract 段。

See Also

• 系统架构总览（Architecture）
• 快速开始（Quickstart）
• REST/MCP 接入
• 释放说明 v0.1.2
• 释放说明 v0.1.1

概览

dual-mem 是一个面向 LLM 应用与 Agent 的双系统分层记忆 SDK。同一套核心逻辑（System1 即时抽取 + System2 异步巩固）通过统一的 MemoryOperations 操作层，对外暴露五种接入方式：SDK（同步/异步）、REST、MCP、CLI、Skill。v0.1.2 起 REST 与 MCP 共享同一份工具契约，避免接口分裂 (README.md、dual_mem/api/contracts.py:1-30)。

下表为五种接入方式的关键对比：

SDK 接入（同步 / 异步）

异步入口 MemoryClient 面向 asyncio 工作流；v0.1.2 新增的 SyncMemoryClient 为同步调用封装，底层复用同一 MemoryOperations，避免阻塞场景下重复造轮子 (README_EN.md)。

读侧返回统一使用 MemoryItem 数据类，包含 memory_id / content / category / score / tags / memory_at / gmt_created / gmt_modified / evolution_chain 字段；其中 evolution_chain 用于展开 supersedes 演化历史 (dual_mem/sdk_models.py:1-50)。例如 dual 模式下 client.digest() 触发 System2 ReAct 循环与跨域 sweeper (examples/02_dual.py:1-30)。

REST / MCP 接入

REST 与 MCP 共用 MEMORY_TOOL_CONTRACTS 中的稳定工具 ID：memory_add / memory_search / memory_list / memory_get / memory_update / memory_delete / ...。每个工具声明 http.method / http.path，MCP 端直接复用 name 字段，因此同一套契约可直接驱动 REST 路由与 MCP tool schema (dual_mem/api/contracts.py:10-30)。

启动方式：

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

响应模型 MemoryItem（Pydantic）与 SDK 数据类对齐，保证跨端点一致 (dual_mem/api/schemas.py:1-30)。

CLI 与 Skill 接入

CLI 适合调试：dual-mem add --content "..." --user-id u1 单条写入；--messages-file messages.json 支持会话级批量（v0.1.2 新增）。检索端不调 LLM，仅消耗 embedding，5 路 anchor + fusion 召回。

Skill 通过 skills/dual-mem/SKILL.md 描述 Agent 集成规范：建议「每轮 search、会话结束 add(messages)」以节省 token；当用户纠正旧信息时由 supersedes 形成演化链 (skills/dual-mem/SKILL.md:1-30)。

配置与部署

最小配置由 config.default.yaml 首次启动自动生成，关键字段包括 embed_base_url / embed_api_key / embed_model / embed_dim / default_app_id / app_whitelist / auth_disabled / mode (system1|dual)。user_id 是主隔离键，app_id 缺省回落到 default；REST 鉴权可通过 auth_disabled: true 在本地关闭 (dual_mem/config.default.yaml:1-30)。

依赖按 extras 拆分：[api] [cli] [mcp]，按需安装可减小运行时体积 (README_EN.md)。文档站点由 mkdocs.yml 描述（locale=zh，readthedocs 主题） (mkdocs.yml:1-10)。

常见问题

• 存储目录不存在：v0.1.2 起 storage_dir 自动创建，不再需要手动 mkdir。
• MCP 启动失败：检查 dual-mem-mcp 是否安装（[mcp] extra），以及 Host 端 transport（stdio / streamable-http）。
• 检索召回空：默认 hybrid 路径需要可用 embedding；检查 embed_api_key 与 embed_dim 是否与模型一致。
• 演化链未展开：读侧需走默认 hybrid 路径才会自动展开 evolution_chain；直查 memory_get 仅返回当前节点。

See Also

• 架构总览
• 快速上手
• 安装指南
• MCP 集成

Pitfall Log / 踩坑日志

项目：shibing624/dual-mem

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/shibing624/dual-mem | host_targets=mcp_host, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/shibing624/dual-mem | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/shibing624/dual-mem | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/shibing624/dual-mem | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/shibing624/dual-mem | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/shibing624/dual-mem | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/shibing624/dual-mem | release_recency=unknown