记忆是如何工作的

Memmy 的记忆由本地 Memory 服务承载。默认服务地址是 http://127.0.0.1:18960，数据保存在 ~/.memmy/memory-service/memory.sqlite。Hook、插件、memmy-memory CLI 和桌面端最终都读写这一个服务，因此不同 Agent 可以共享同一套记忆。

一次请求的完整链路

链路可以拆成七步：

1. Hook 或插件在请求进入 Agent 前打开或复用 Memmy 会话，并调用 turn.start。
2. Memory 服务在新 episode 的第一轮判断请求意图，决定是否召回以及允许召回哪些层。
3. 查询被整理为语义查询、关键词、短词模式和结构化错误片段。
4. 各召回通道并行返回候选，再按记忆层、通道排名、质量和时间衰减融合。
5. 候选经过相对阈值、去重、MMR 多样性选择和可选的 LLM 过滤。
6. 命中项被渲染为“历史上下文”注入 Agent；当前用户请求始终优先。
7. 回合结束后，turn.complete 写入原始回合和 L1 轨迹，后台任务再继续摘要、反思、评分、向量化和高层记忆演化。

四个记忆层

写入、索引与演化

自动回合采集

turn.complete 会先保存 Raw Turn，然后按捕获到的步骤写入 L1。默认会保留：

• 最多 4,000 字符的用户或 Agent 文本；
• 每个工具输出最多 2,000 字符；
• 最多 8 个派生标签；
• 工具名、输入、结果、错误签名、回合状态和来源 Agent；
• 启发式摘要，随后可由摘要模型异步改写；
• value、alpha 和 priority 等质量信号。

当前默认开启反思合成和写入后向量化。L1 使用摘要文本生成 vec_summary；L2、L3 和 Skill 使用统一的 vec。索引失败会进入重试队列，不会阻塞当前 Agent 回合。

显式写入和历史导入

memory.add 默认写入 L1，也可以显式指定其他层。普通手动写入会立即进入文本索引并异步生成向量。

从 Agent 历史扫描导入的 L1 会先进入 summary_queued 流程，完成摘要和向量索引后才参与召回，避免半成品记忆被提前注入。

Episode、反馈与高层记忆

• 连续 follow-up 默认合并到同一 episode，最大间隔为 2 小时。
• episode 因主题切换、会话关闭或空闲 2 小时而关闭后，会先生成/评分反思。
• 默认等待 30 秒反馈窗口，再计算任务奖励并向 episode 内的 L1 反向传播。
• 达到条件的 L1 进入候选池并归纳为 L2；新 L2 会继续触发 L3 抽象和 Skill 结晶。
• 用户明确反馈、工具连续失败和成功/失败分布还会修正价值、生成避坑经验或 decision repair。

关键演化默认值：

召回在什么时候发生

不同入口使用不同记忆层：

新 episode 的第一轮还会做意图门控：

turn_start 会排除当前 session 自己的 L1，防止刚发生的内容通过长期记忆路径回声式重复；L2、L3 和 Skill 不受这个排除规则影响。

readOnlyInjectionProfile 只在 domain: research 时缩小召回层：可选 experience（仅 L2）、skill、skill_experience 或 all。非 research 域始终按 all 处理。

查询如何被准备

1. 如果配置了 evolution 模型，服务先从完整请求中提取一个更适合向量化的语义查询和最多 5 个关键词。提取失败时使用原始请求和规则关键词，不会中断搜索。
2. 中文短语会补充二字模式；代码、路径和错误文本会提取结构化片段。
3. 只有数据库中存在可用向量时才生成查询向量；查询向量超时或失败时，全文、短词和结构通道仍可继续。
4. enableQueryRewrite 默认关闭。开启后，evolution 模型会生成 3 个互补查询，每个查询独立召回，再用独立的 RRF 合并结果。

到底有几路召回

从“检索方法”看有 4 类；从 ranker 的 channel 名称看有 6 个：

vec、vec_summary、vec_action、fts、pattern、structural。

候选量来自以下公式：

• 向量池：对应 tierTopK × candidatePoolFactor；
• 默认分别是 Tier 1：3 × 4 = 12，Tier 2：5 × 4 = 20，Tier 3：2 × 4 = 8；
• FTS 和 pattern：max(对应 tierTopK, keywordTopK)，默认都是 20；
• 所有通道合并后，再按 Tier 截断为 12 / 20 / 8。

本地 SQLite 向量检索会先从相应层和字段的最近 2,000 条向量记录中建立本次搜索窗口，再交给 sqlite-vec 取 Top K；这个 2,000 是当前固定常量，不在 config.yaml 中。

候选如何过滤、融合与排序

进入 ranker 前

• 只读取 activated 和 resolving 状态；archived、deleted 和未完成导入索引的记录不会进入召回。
• Skill 必须是 active 或 candidate，且 eta >= minSkillEta，默认 0.1。
• L3 的置信度必须达到 l3Abstraction.minConfidenceForRetrieval，默认 0.2。
• tagFilter: auto 只约束 L1 向量通道：先按查询推导出的标签检索；如果没有标签命中，会放宽为无标签的摘要向量检索。on 始终严格，off 不使用这个标签门控。

相关度融合

每个候选先取所有命中通道中的最高分，再叠加层级质量：

L1 bonus    = min(weightPriority, 0.3) × max(value, 0) × 时间衰减
Skill bonus = skillEtaBlend × eta
L2 bonus    = 0.2 × clamp01(gain，或反馈经验的 salience / confidence)
RRF bonus   = 0.4 × Σ 1 / (rrfConstant + channelRank + 1)
relevance   = max(channelScore) + 层级 bonus + RRF bonus

阈值、episode 聚合与 MMR

1. 每个 Tier 的预排序候选池先按相关度、命中通道数和向量分排序。
2. 同一 episode 如果至少有 2 条高位 L1，且代表轨迹的向量相似度达到 0.45、value 不为负，会生成最多包含 6 步的 episode rollup。
3. 低于最高相关度 20% 的候选被丢弃；默认开启多通道豁免，命中至少 2 个通道的候选可以保留。
4. 对长标识符、错误码等高熵查询，L1/L2 还必须有 FTS、pattern 或 structural 的关键词确认；Skill 和 L3 例外。
5. MMR 以 0.7 × relevance - 0.3 × redundancy 选择结果。默认 smart seed 要求每个 Tier 的首个候选至少达到全局最高相关度的 70%。
6. 最后去重同一 episode 的单条 L1 与 rollup，并在 Skill 已覆盖同一 Policy 时抑制重复 L2。

tier1TopK=3、tier2TopK=5、tier3TopK=2 同时决定候选池大小和默认全局返回上限 3 + 5 + 2 = 10，但它们不是最终结果中每个 Tier 的硬配额。请求显式传入 limit 时，最终 MMR 使用请求值。

LLM 最终过滤

默认在机械排序后优先使用 evolution 模型做相关性过滤；未配置 evolution 模型时会尝试 summary 模型：

LLM 可以明确丢弃全部候选；如果输出格式无效或调用失败，则保留机械排序的前 6 条。

如何注入 Agent 上下文

命中项会按以下顺序渲染：

1. L1 Trace 和相似 episode；
2. L2 Policy；
3. L3 Environment Knowledge；
4. Skill；
5. 从经验中提炼出的 decision guidance。

普通片段最多 640 字符。Skill 默认使用 summary 模式，只注入名称和最多 200 字符的描述；可改为 full，但仍受单片段 640 字符上限约束。最终 Markdown 会明确说明这些内容只是历史记忆，需要与当前请求和当前仓库状态核对。

在 config.yaml 中调整

主配置默认是 ~/.memmy/config.yaml；设置 MEMMY_CONFIG 时使用该路径。下面是当前有效的核心参数及默认值，可以只保留你要覆盖的字段：

memmyMemory:
  version: 1
  domain: ""
  algorithm:
    enableMemoryAdd: true
    enableMemorySearch: true
    enableQueryRewrite: false

    capture:
      maxTextChars: 4000
      maxToolOutputChars: 2000
      synthReflection: true
      embedAfterCapture: true
      batchThreshold: 12

    reward:
      gamma: 0.9
      lambda: 0.5
      delta: 0.1
      decayHalfLifeDays: 30
      feedbackWindowSec: 30

    l2Induction:
      minEpisodesForInduction: 1
      minSimilarity: 0.65
      candidateTtlDays: 30
      minTraceValue: 0.005
      minGain: 0.02
      archiveGain: -0.05

    l3Abstraction:
      minPolicies: 1
      minPolicyGain: 0.02
      minPolicySupport: 1
      clusterMinSimilarity: 0.3
      minConfidenceForRetrieval: 0.2

    skill:
      minEtaForRetrieval: 0.1
      minSupport: 1
      minGain: 0.02
      candidateTrials: 1

    session:
      followUpMode: merge_follow_ups
      mergeMaxGapMs: 7200000

    retrieval:
      tier1TopK: 3
      tier2TopK: 5
      tier3TopK: 2
      candidatePoolFactor: 4
      weightPriority: 0.4
      mmrLambda: 0.7
      rrfConstant: 60
      relativeThresholdFloor: 0.2
      minSkillEta: 0.1
      minTraceSim: 0.25
      episodeGoalMinSim: 0.45
      tagFilter: auto
      keywordTopK: 20
      skillEtaBlend: 0.15
      smartSeed: true
      smartSeedRatio: 0.7
      multiChannelBypass: true
      skillInjectionMode: summary
      skillSummaryChars: 200
      llmFilterEnabled: true
      llmFilterMaxKeep: 8
      llmFilterFallbackMaxKeep: 6
      llmFilterMinCandidates: 2
      llmFilterCandidateBodyChars: 500
      readOnlyInjectionProfile: all

保存后执行：

memmy-memory reload-config

召回、演化和模型配置可以热加载。修改 storage 后，reload 响应会返回 requiresRestart: true，此时需要重启 Memory 服务。算法参数集中在服务端，通常不需要重新安装 Agent Hook 或插件。

常见调优方向

• 提高召回率：增大 candidatePoolFactor 或 keywordTopK，降低 relativeThresholdFloor 或 minTraceSim。
• 减少噪声：提高 minTraceSim、relativeThresholdFloor、minSkillEta，或减小 llmFilterMaxKeep。
• 增加结果多样性：降低 mmrLambda；提高它会更偏向最高相关度。
• 处理多事实或间接问题：开启 enableQueryRewrite，代价是额外的 evolution 模型调用和延迟。
• 完全关闭记忆读或写：分别设置 enableMemorySearch: false 或 enableMemoryAdd: false；二者互不强制绑定。

如何检查某次召回

memmy-memory search "你的查询" --verbose

调试时重点看：

• candidateMemoryIds：各底层通道汇总出的原始候选；
• hits：融合、阈值和 MMR 后的候选；
• sourceMemoryIds：实际渲染进上下文的记忆；
• status：LLM 过滤是成功、关闭、跳过还是回退；
• 记忆管理的日志页：查看 memory.search 的 candidates、filtered、droppedByLlm 和统计信息。

记忆管理页

/memory 的侧栏按用途分为三组：

日志页对 memory.search 和 memory.add 提供专门详情（搜索候选、写入字段、结果状态），可用来解释某条记忆为何被命中或写入。