#Agent Memory 架构设计与工程落地方案

本文档是 Negentropy 平台 Agent Memory 子系统的架构设计单一权威参考，融合学术前沿分类法、工业框架对标、当前 PostgreSQL 实现详述和双阶段演进路线图，并引入可量化的价值度量体系。

• 系统架构总览：framework.md
• Memory 与 Knowledge 职责边界：035-the-knowledge-base.md
• 知识图谱技术方案：036-the-knowledge-graph.md
• 理论基础白皮书（Phase 4）：026-memory-whitepaper.md
• 轻量上手手册（Phase 4）：memory-basics · memory-integration · memory-automation · memory-troubleshooting
• DDL 原型（历史参考）：schema/hippocampus_schema.sql

Phase 4 已完成增强（2026-05）：①Memory 类型分层差异化 + Core Memory Block；②Self-editing Memory Tools（5 个 Agent 主动管理工具）；③LoCoMo / LongMemEval 评测基线；④User-Guide 拆分 + 理论白皮书；⑤KG 双向同步接通；⑥PII regex 占位。详见 026-memory-whitepaper.md §2 与 §3。

#目录

0. 范围与事实源
1. 引言与项目定位
2. 学术认知框架：Agent Memory 分类体系
   • 2.4 工业实践深度对标：Claude Code 记忆架构
   • 2.5 工业实践深度对标：Agent Harness 设计模式
   • 2.6 Negentropy 差异化定位总结
3. 系统架构
4. 记忆形成 (Memory Formation)
5. 记忆演化 (Memory Evolution)
6. 记忆检索 (Memory Retrieval)
7. 记忆治理 (Memory Governance)
8. Memory Automation 控制面
9. PostgreSQL 阶段：当前实现深度解析
10. 终态愿景：多维记忆演进路线图
11. 价值量化体系 (Value Quantification System)
12. 安全与合规
13. 测试策略
14. 相关文档
15. 参考文献

#0. 范围与事实源（Single Source of Truth）

本文档的覆盖范围为 Memory 子系统（对应内化系部 InternalizationFaculty），不覆盖 Knowledge Base（对应感知系部 PerceptionFaculty）。两者的边界说明以 035-the-knowledge-base.md 为准。

权威源文件索引：

#1. 引言与项目定位

#1.1 为什么 Agent Memory 是核心

Negentropy（熵减引擎）以**「一核五翼」架构**^[1]对抗知识的无序趋势。Agent Memory 是内化系部 (InternalizationFaculty) 的核心实现，对抗的熵增目标是 遗忘 —— 将碎片化信息体系化为稳固的长期知识。

在 Google ADK 生态中^[12]，Memory 承担以下职责：

• 会话持久化：继承 BaseMemoryService，将 Session 对话转化为可检索的长期记忆
• 个性化上下文：为 Agent 提供 user-scoped 的记忆上下文，实现跨会话个性化响应
• 知识巩固：通过巩固任务将碎片记忆提炼为结构化 Fact，对抗遗忘

#1.2 Memory 与 Knowledge 的本质区别

Memory 和 Knowledge 是 Negentropy 中两个正交的认知子系统，各有独立的生命周期和治理模型。详细的职责拆分以 035-the-knowledge-base.md 为权威定义，此处仅做摘要：

#1.3 设计原则

• 仿生认知 (Biologically-Inspired)：基于艾宾浩斯遗忘曲线^[2]的指数衰减模型，以「海马体 (Hippocampus)」隐喻命名 Schema
• 控制面/数据面分离：前端不直接编辑 SQL，不直接暴露 cron.job 等数据库内部结构
• 单一事实源 (SSOT)：自动化配置以服务端 memory_automation_configs 为唯一权威，UI 仅读写该契约
• 受控运维：只允许对预定义过程执行 enable / disable / reconcile / run
• 渐进降级：未安装 pg_cron 时仍可查看配置和函数定义，调度能力优雅退化为只读

#2. 学术认知框架：Agent Memory 分类体系

本章建立读者对 Agent Memory 全貌的认知锚点，聚焦于对 Negentropy 有直接指导意义的维度。

#2.1 Agent Memory 三维分类法

基于 Maharana 等人的综合综述^[3]，Agent Memory 可从形态 (Forms)、功能 (Functions)、拓扑 (Topologies) 三个正交维度进行分类。下图高亮了 Negentropy 当前实现所覆盖的区域（实线）与未来计划区域（虚线）：

图例：🟩 已实现 · 🟨 部分实现 · ⬜ 未来规划

#2.2 Negentropy 的记忆类型映射

将心理学分类法具体映射到 Negentropy 的 4 种记忆存储：

#2.3 记忆动态学：形成-演化-检索

Agent Memory 的生命周期遵循形成 (Formation) → 演化 (Evolution) → 检索 (Retrieval) 三阶段模型^[3][4]：

对应的代码路径：

• Formation：PostgresMemoryService.add_session_to_memory() → _simple_consolidate() 或 consolidation_worker.consolidate()
• Evolution：MemoryGovernanceService.calculate_retention_score() + cleanup_low_value_memories() SQL 函数
• Retrieval：PostgresMemoryService.search_memory() 的 4 级回退策略

#2.4 工业框架对标

Negentropy 的 Memory 实现并非基于独立中间件，而是采用 PostgreSQL 单栈深度集成策略。以下为与主流 Agent Memory 框架的能力对标^{[16][17][18][19]}：

Negentropy 的差异化定位：不引入外部图数据库或独立记忆服务，而是在 PostgreSQL 16+ 上实现向量检索(pgvector)、图存储(Apache AGE)、全文检索(tsvector)、定时调度(Unified Scheduler) 的统一方案，降低运维复杂度和数据一致性风险。

#2.4 工业实践深度对标：Claude Code 记忆架构

本节基于 ThreeFish-AI/claude-code（Claude Code 可运行版逆向工程）和 shareAI-lab/learn-claude-code（从零构建 Agent Harness）的源码分析，提炼可指导 Negentropy 记忆模块的关键设计模式。

#2.4.1 AutoDream 记忆整理机制

Claude Code 的 AutoDream 是一个后台记忆整合机制，在会话间自动审查、组织和修剪持久化记忆文件。

四阶段整理流程（src/services/autoDream/consolidationPrompt.ts）：

1. Orient（定位）：ls 记忆目录，读取 MEMORY.md 索引，浏览现有文件避免重复
2. Gather（采集）：按优先级收集新信号（日志 > 过时记忆 > 会话记录），使用窄关键词 grep 而非全文读取
3. Consolidate（整合）：合并新信号到现有文件（而非创建近似重复），转相对日期为绝对日期，删除被推翻的事实
4. Prune（修剪）：MEMORY.md ≤200 行 / 25KB，每条 ≤150 字符

三重门控调度（src/services/autoDream/autoDream.ts）：

Negentropy 适配：PostgreSQL 方案中，Orient 阶段映射为 _is_duplicate() 的 cosine similarity 检测；Consolidate 映射为 _simple_consolidate 的分段提取+去重；Prune 映射为 retention_score 驱动的 cleanup_low_value_memories()。门控策略映射到 AsyncScheduler 的应用层调度器回退。

#2.4.2 三层上下文压缩策略

Claude Code 采用三层递进压缩策略管理有限上下文窗口：

MicroCompact 维护一个白名单（COMPACTABLE_TOOLS），将超过时间窗口的工具输出替换为 [Old tool result content cleared]。Session Memory Compact 使用已提取的 Session Memory 作为压缩摘要，无需额外 API 调用。

Negentropy 适配：映射到 ContextAssembler 的 token 预算管理——先注入高优先级 Facts（Layer 1），再用最近 Memories 填充（Layer 2），最后用对话历史补充（Layer 3）。

#2.4.3 记忆四类型分类法

Claude Code 记忆系统使用封闭的四类型系统（src/memdir/memoryTypes.ts）：

漂移防御（TRUSTING_RECALL_SECTION）：系统 Prompt 中设有"Before recommending from memory"——记忆命名了特定函数/文件/标记时，必须先验证其是否仍存在。

Negentropy 适配：直接映射到 facts 表的 fact_type 字段（preference/profile/rule/custom），与四类型高度对齐。

#2.5 工业实践深度对标：Agent Harness 设计模式

基于 shareAI-lab/learn-claude-code 的渐进式 Agent 构建教程，提炼以下设计模式：

三层压缩管线（agents/s06_context_compact.py）：MicroCompact（替换旧工具输出）→ AutoCompact（token 超阈值时 LLM 摘要）→ ManualCompact（用户手动触发）。Transcripts 保存完整历史到磁盘，"Nothing is truly lost — just moved out of active context."

Skill 按需加载（agents/s05_skill_loading.py）：两层注入——系统提示放 skill 名称（~100 tokens/skill），tool_result 按需加载完整 body（~2000 tokens）。

Task Graph 持久化（agents/s07_task_system.py）：JSON 文件 DAG，blockedBy 依赖边，pending → in_progress → completed 状态机，完成时自动解除依赖。

Negentropy 吸收：MicroCompact 思路应用于巩固管线的分段策略（保留最近 K 条完整，旧消息缩略）；Task Graph 模式已在项目 TaskCreate/TaskUpdate 中实现。

#2.6 Negentropy 差异化定位总结

#3. 系统架构

#3.1 Memory 子系统全景图

#3.2 数据模型

Memory 子系统包含 6 张核心表（及 5 张辅助表），其 ER 关系如下：

索引策略：

#3.3 服务分层架构

#4. 记忆形成 (Memory Formation)

Agent Memory 的形成是将实时对话的短期上下文转化为可持久检索的长期记忆的过程^[3]。

#4.1 Session-to-Memory 转化流程

PostgresMemoryService.add_session_to_memory() 提供两条路径：

ADK Event 解析逻辑：_simple_consolidate 支持三种 Content 格式的适配：

1. Content 对象（.parts[].text）
2. dict 类型（["parts"][]["text"]）
3. 原始 str 类型

#4.2 事实提取 (Fact Extraction)

Phase 1 采用 PatternFactExtractor（基于正则的模式匹配），Phase 2 引入 LLMFactExtractor（LLM 驱动的语义提取）作为默认提取器，PatternFactExtractor 保留为降级后备。

#4.2.1 两级提取策略

LLMFactExtractor 遵循 knowledge/llm_extractors.py 的成熟模式：

• 批处理（≤10 turns/批）减少 API 开销
• JSON structured output 保证解析可靠性
• 指数退避重试（max 3 attempts）
• 提取失败自动降级到 L2

FactService.upsert_fact() 基于 PostgreSQL 的 ON CONFLICT DO UPDATE 实现 upsert 语义：

• 唯一约束：(user_id, app_name, fact_type, key) — 每个用户的每个 key 只有一个有效值
• 向量化：Fact 可选 embedding，支持语义检索
• 有效期管理：valid_from / valid_until 支持时态查询（当前值 vs 历史值）

参考文献 ^[6][29]。

#4.3 巩固任务 (Consolidation Jobs)

consolidation_jobs 表支持三种任务类型，映射到认知科学中的记忆巩固层级^[2]：

trigger_maintenance_consolidation() SQL 函数按 lookback_interval 时间窗口自动创建巩固任务：

-- 为最近活跃的 threads 创建巩固任务（排除已存在的）
INSERT INTO consolidation_jobs (thread_id, job_type, status)
SELECT id, 'full_consolidation', 'pending'
FROM threads
WHERE updated_at > NOW() - p_interval
  AND id NOT IN (
      SELECT thread_id FROM consolidation_jobs
      WHERE created_at > NOW() - p_interval
  )

#5. 记忆演化 (Memory Evolution)

记忆不是静态存储，而是一个持续演化的动态系统^[3]。MAGMA 架构^[8]提出了双流记忆演化（延迟敏感的事件摄入 + 异步结构巩固）的理念。Negentropy 当前以艾宾浩斯遗忘曲线为核心驱动记忆演化。

#5.1 多因子自适应遗忘曲线模型

基于 Ebbinghaus 遗忘曲线^[2]的指数衰减，扩展为 五因子自适应模型（ACT-R 认知架构^[45] + FadeMem^[46]）：

retention = min(1.0, time_decay × frequency_boost × type_multiplier × semantic_importance / 5.0 + recency_bonus)

其中:
  time_decay         = e^(-λ_type × days_elapsed)
  frequency_boost    = 1 + ln(1 + access_count)
  type_multiplier    = 记忆类型乘子（偏好 1.3 / 流程 1.2 / 事实 1.15 / 情景 1.0）
  semantic_importance = 1 + min(0.5, related_count × 0.1)
  recency_bonus      = max(0, 1 - days_since_creation / 365) × 0.1

记忆类型衰减率映射：

• λ_type：记忆类型特定的衰减常数，覆盖默认 0.1
• days_elapsed：距最后访问的天数（last_accessed_at）
• access_count：累计访问次数。频率因子使用对数增长，避免高频访问过度膨胀分数
• related_count：同 thread 关联的事实和记忆数量（语义重要性）
• recency_bonus：1 年内创建的记忆获得额外 [0, 0.1] 加分
• 分数范围：[0.0, 1.0]

典型衰减曲线（λ=0.1, access_count=0）：

代码实现：

• Python：MemoryGovernanceService.calculate_retention_score() — engine/governance/memory.py
• Python：PostgresMemoryService._calculate_initial_retention() — engine/adapters/postgres/memory_service.py
• SQL：calculate_retention_score() plpgsql 函数 — schema/hippocampus_schema.sql §5

#5.2 访问计数强化 (Retrieval-Enhanced Retention)

每次检索召回后，_record_access() 异步更新被召回记忆的访问行为，使遗忘曲线动态生效：

UPDATE memories SET
    access_count = access_count + 1,
    last_accessed_at = NOW()
WHERE id IN (recalled_memory_ids);

为何选择对数增长（1 + ln(1 + n)）而非线性增长：

• 线性增长（1 + n）会导致高频访问的记忆保留分数失控膨胀
• 对数增长在低频区间灵敏，高频区间饱和，符合认知科学中「频率效应递减」的规律

#5.3 Retention Cleanup 自动化

cleanup_low_value_memories() SQL 函数执行两步逻辑：

1. 全量更新 retention_score：调用 calculate_retention_score() 重算所有记忆的保留分数
2. 清理低价值记忆：删除 retention_score < threshold 且 created_at < NOW() - min_age_days 的记忆

配置映射关系（详见第 8 章）：

• retention.decay_lambda → calculate_retention_score() 的 p_decay_rate 参数
• retention.low_retention_threshold → cleanup_low_value_memories() 的 p_threshold 参数
• retention.min_age_days → cleanup_low_value_memories() 的 p_min_age_days 参数
• retention.auto_cleanup_enabled + cleanup_schedule → pg_cron cleanup_memories 任务

#5.4 Memory Consolidation 策略

与学术前沿的对标：

#5.4.1 摘要巩固策略 (Summary Consolidation)

受认知科学记忆再巩固 (Reconsolidation) 理论^[26]启发，MemorySummarizer 定期将用户的碎片记忆和事实重蒸馏为结构化画像摘要。该策略借鉴：

摘要生成流程：

1. 加载用户活跃 facts + 近期高 retention 记忆
2. LLM 生成 ~200-400 tokens 的结构化画像（角色/偏好/风格/规则）
3. upsert 至 memory_summaries 表（TTL 24h 可配置）
4. ContextAssembler 优先注入摘要，无摘要时降级到原始拼接

参考文献 ^{[10][23][26][29][30]}。

#5.5 记忆重要性评分 (Importance Scoring)

重要性评分（importance_score）量化每条记忆的固有价值，与保留分数（动态衰减）互补。基于 ACT-R 认知架构^[45]的基础水平激活公式和 FadeMem^[46]多因子模型，五因子加权公式：

importance = min(1.0,
    base_activation * 0.30 +    # ACT-R log-sum 访问间隔
    access_frequency * 0.25 +   # log(access_count) 归一化
    fact_support * 0.20 +       # 关联事实数 / 10
    type_weight * 0.15 +        # preference(0.9) > procedural(0.75) > fact(0.6) > episodic(0.4)
    recency_bonus * 0.10        # max(0, 1 - days_since_creation / 90)
)

记忆类型重要性权重：

计算时机：

• 巩固存储时：PostgresMemoryService._simple_consolidate() 计算初始评分
• Fact upsert 时：FactService.upsert_fact() 计算初始评分
• 访问后：_record_access() 增量提升 +0.02

代码实现：MemoryGovernanceService.calculate_importance_score() — engine/governance/memory.py

#5.6 记忆冲突与信念修正 (Conflict Resolution)

当新事实与现有事实矛盾时，基于 AGM 信念修正理论^[49]和 Doyle 真值维护系统^[50]，通过三阶段检测自动解决冲突。

检测阶段：

冲突分类：

解决策略：

数据模型：Fact 新增 superseded_by、status（active/superseded）、superseded_at 字段；新建 memory_conflicts 表记录冲突历史。

代码实现：ConflictResolver — engine/governance/conflict_resolver.py

Phase 7 增强：DedupMergeStep 在 soft-delete 之前会检测关联 facts 的 key 碰撞。 当发现偏好反转等矛盾时，委托 ConflictResolver（基于 AGM 信念修正理论）执行显式解决：

• supersede — 新值取代旧值（与原 soft-delete 行为一致）
• keep_both — 跳过 soft-delete，保留两条记忆（独立但相关的事实）
• merge — 合并两者值

无冲突时保持原有机械合并行为不变（向后兼容）。

#5.7 主动召回 (Proactive Recall)

基于 Spreading Activation Theory^[51]和 Context-Dependent Memory^[52]，在新会话创建时主动注入高相关性记忆，减少 Agent 的「冷启动」信息缺失。

复合评分公式：

proactive_rank = importance_score * 0.40
               + recency_score * 0.30
               + frequency_score * 0.20
               + 0.10  （常量基线）

缓存策略：

• TTL 1 小时：memory_preload_cache 表按 (user_id, app_name) 缓存
• 失效触发：巩固完成、事实插入、冲突解决时自动 invalidate_cache()
• 缓存命中直接返回，未命中则计算并写入

代码实现：ProactiveRecallService — engine/adapters/postgres/proactive_recall_service.py

#5.8 记忆关联 (Memory Associations)

基于 Associative Memory Theory^[53]和 Spreading Activation^[51]，自动发现并维护记忆间的关联关系，支持多跳扩展检索。

四种自动链接策略：

多跳扩展：

起始记忆 → 关联查找 (weight > 0.6) → 追加关联记忆 → 最多 3 跳 → Token 预算控制

BFS 遍历关联图，每跳只追加权重大于 0.6 的强关联，最终在 Token 预算内返回扩展上下文。

数据模型：memory_associations 表，UNIQUE(source_id, target_id, association_type)。

代码实现：AssociationService — engine/adapters/postgres/association_service.py

#6. 记忆检索 (Memory Retrieval)

#6.1 混合检索架构

PostgresMemoryService.search_memory() 实现 4 级回退检索策略，确保在不同基础设施条件下都能返回结果：

#6.2 Hybrid Search 实现细节

_hybrid_search_native() 调用 PostgreSQL 中预定义的 hybrid_search() SQL 函数^[11]：

SELECT id, content, semantic_score, keyword_score, combined_score, metadata
FROM {NEGENTROPY_SCHEMA}.hybrid_search(
    :user_id, :app_name, :query, :embedding::vector(1536),
    :limit, :semantic_weight, :keyword_weight
)

关键设计决策：

• 参数化绑定：embedding 参数通过 :embedding 绑定变量传递，而非字符串拼接，防止 SQL 注入
• Schema 前缀：统一使用 NEGENTROPY_SCHEMA 常量确保与 ORM 一致
• 默认权重：semantic_weight=0.7, keyword_weight=0.3 — 语义优先，关键词补充

#6.3 Context Window 组装

get_context_window() SQL 函数按 Token Budget 三段式分配组装上下文：

Token 估算：采用 tiktoken BPE 编码器精确计数（Phase 1 曾使用 LENGTH(content) / 4 粗略估算）。Python 侧通过 TokenCounter 工具类调用，SQL 函数 get_context_window() 保留 LENGTH/4 作为 DB 侧快速估算，Python 端后校正。参考文献 ^[25]。

Token Budget 硬性校验（Phase 2++ 增强）：组装完成后校验 token_count <= budget_total（memory_ratio + history_ratio）。超标时按行截断（优先保留先召回的高相关性内容），并输出 context_budget_overflow 结构化日志。参考 MemGPT^[7] Virtual Context Management 的分页截断策略。

搜索结果标准化（Phase 2++ 增强）：每条搜索结果携带 search_level (hybrid|vector|keyword|ilike)、score_type (combined|cosine_distance|ts_rank|retention_proxy) 和 raw_score 元数据，通过 custom_metadata 传播至 ADK MemoryEntry。参考 Observability Engineering^[48] 的结构化可观测性理念。

#6.4 与学术检索范式的对标

#6.5 检索效果反馈闭环 (Retrieval Feedback Loop)

基于 Rocchio 相关性反馈^[27]和 Learning-to-Rank^[28]范式，建立"检索→记录→反馈→调权"的闭环，量化记忆系统的有效性。

RetrievalTracker 在 search_memory() 返回结果后自动记录检索事件，并支持显式反馈 API：

评估维度对齐 LongMemEval^[9]：

参考文献 ^[9][27][28]。

#7. 记忆治理 (Memory Governance)

#7.1 GDPR 合规审计

MemoryGovernanceService 提供三种审计决策，同时处理 Memory 和关联 Fact 确保 GDPR 合规：

#7.2 版本控制与幂等性

• 乐观锁：expected_versions 参数，调用前获取当前版本号，执行时检测冲突
• 幂等性键：idempotency_key 参数，基于 UniqueConstraint("app_name", "user_id", "memory_id", "idempotency_key") 防止重复提交
• 审计链：每次决策创建 MemoryAuditLog 记录，version 单调递增

#7.3 审计工作流

#8. Memory Automation 控制面

本章完整保留原有 Memory Automation 设计与实施文档，是该控制面的权威参考。

#8.1 定位

Memory Automation 模块负责用户长期记忆的形成、保留、检索与治理的自动化管控，区别于静态共享的 Knowledge。为避免控制面与数据面耦合，设有 Memory / Automation 二级导航页，统一展示与管理仿生记忆自动化过程，包括：

• 艾宾浩斯遗忘曲线参数
• Memory Retention 清理任务
• Context Assembler 组装预算
• Maintenance Consolidation 周期触发
• PostgreSQL 受管函数与 pg_cron 调度状态
• 最近执行日志与受控运维动作

#8.2 设计原则

• 控制面/数据面分离：前端不直接编辑任意 SQL，不直接面向 cron.job 暴露数据库内部结构。
• Single Source of Truth：自动化配置以服务端 memory_automation_configs 为唯一事实源，UI 仅读写该契约。
• 受控运维：只允许对预定义过程执行 enable / disable / reconcile / run。
• 渐进降级：未安装 pg_cron 时仍可查看配置和函数定义，但调度能力退化为只读。

当前设计延续了 ADK MemoryService 的"写入/检索解耦"模式与 LangGraph 的"短期状态/长期记忆分层"思路^[12][13]：实时响应走检索热路径，深度巩固与周期维护走后台过程。在 PostgreSQL 落地时，调度层以 pg_cron 作为可选增强能力，而不是将数据库内部对象直接暴露为前端控制面^[14][15]。

#8.3 核心对象

#8.4 受管过程

#8.5 PostgreSQL 初始化前置条件

要让 Memory / Automation 进入可用状态，PostgreSQL 至少需要满足以下条件。

#8.5.1 最小可用

• 已执行当前 Alembic migration，包含 negentropy.memory_automation_configs。
• 仿生记忆依赖表已存在：memories、events、threads、consolidation_jobs。
• 已安装 vector 扩展，支持 memories.embedding 的向量检索。
• 应用连接用户可读取 pg_extension，以便后端探测系统能力。
• 应用连接用户需可在 negentropy schema 中执行受管函数的 CREATE OR REPLACE FUNCTION。

#8.5.2 完全可用

在"最小可用"基础上，再补齐以下能力即可让调度控制面可写：

• 已安装 pg_cron 扩展。
• 应用连接用户可访问 cron.job，用于查看、启停、重建受管任务。
• 应用连接用户可访问 cron.job_run_details，用于展示 Recent Logs。
• 应用连接用户可执行 cron.schedule 与 cron.unschedule，用于创建、更新与移除受管任务。

说明：

• pg_cron 是增强能力，不是 Memory Automation 的硬依赖；未安装时页面仍可查看配置和函数状态。
• Recent Logs 依赖 cron.job_run_details；日志为空不必然表示任务未运行，也可能是日志表不可访问。

#8.6 PostgreSQL 初始化步骤

推荐按"迁移 -> 能力检查 -> 打开控制面 -> 保存并同步 -> 验证"的顺序完成初始化。

#8.6.1 执行 migration

uv run --project apps/negentropy alembic upgrade head

执行后，至少应确认 memory_automation_configs 已创建：

SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_schema = 'negentropy'
  AND table_name = 'memory_automation_configs';

#8.6.2 检查底层扩展

SELECT extname, extversion
FROM pg_extension
WHERE extname IN ('vector', 'pg_cron')
ORDER BY extname;

判定原则：

• vector 缺失：Memory 检索链路本身不完整，应先补齐。
• pg_cron 缺失：Automation 页面进入"调度只读"降级态，但函数与配置仍可用。

#8.6.3 检查受管函数依赖表

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'negentropy'
  AND table_name IN ('memories', 'events', 'threads', 'consolidation_jobs')
ORDER BY table_name;

这些表分别支撑：

• memories：长期记忆本体与 retention 清理。
• events、threads：get_context_window() 的历史拼装。
• consolidation_jobs：周期性巩固任务投递。

#8.6.4 打开 Automation 页面并执行一次"保存并同步"

推荐使用管理员账号进入 Memory / Automation 页面执行一次"保存并同步"。当前实现会：

• 始终把配置写入 negentropy.memory_automation_configs
• 始终 reconcile 受管函数
• 仅在 pg_cron 可用时 reconcile 受管任务

这意味着初始化主路径应以控制面为准，而不是人工先手写完整 SQL。

这一顺序对应"配置为事实源、数据库对象为受管派生物"的控制面模式，可降低函数定义和调度命令被人工漂移改坏的概率^[12][15]。

如果"保存并同步"失败，应优先检查两类权限：

• negentropy schema 中受管函数的创建或替换权限。
• cron.schedule / cron.unschedule 的执行权限，而不只是 pg_cron 是否已安装。

#8.7 系统能力与状态判断

Automation 页面中的系统能力对应后端运行时探测结果：

常见状态解释：

• healthy：配置、函数、任务、日志能力都满足当前期望。
• degraded：至少一个能力位、函数状态或 job 状态不满足当前期望，但控制面仍可部分使用。

#8.8 一期接口

• GET /memory/automation
• GET /memory/automation/logs
• POST /memory/automation/config
• POST /memory/automation/jobs/{job_key}/enable
• POST /memory/automation/jobs/{job_key}/disable
• POST /memory/automation/jobs/{job_key}/reconcile
• POST /memory/automation/jobs/{job_key}/run

#8.9 配置到运行时的映射

• retention.decay_lambda：映射到 calculate_retention_score() 与 cleanup_low_value_memories() 的默认衰减参数。
• retention.low_retention_threshold / retention.min_age_days：映射到 cleanup_low_value_memories() 的默认清理阈值与最小保留天数。
• context_assembler.max_tokens / memory_ratio / history_ratio：映射到 get_context_window() 的默认参数，控制记忆与历史的预算切分。
• consolidation.lookback_interval：映射到 trigger_maintenance_consolidation() 的默认时间窗口。
• retention.auto_cleanup_enabled / consolidation.enabled 与各自 schedule：映射到受管 pg_cron 任务是否启用及其 cron 表达式。

#8.10 过程摘要与启动路径

#8.10.1 Retention Cleanup

• 目标：基于艾宾浩斯遗忘曲线更新 retention 并清理低价值记忆。
• 受管函数：calculate_retention_score()、cleanup_low_value_memories()
• 受管任务：cleanup_memories
• 启动方式：
  • 在 Automation Config 中设置 retention.decay_lambda
  • 设置 low_retention_threshold、min_age_days
  • 打开 auto_cleanup_enabled
  • 设置 cleanup_schedule
• 验证方式：
  • Managed Jobs 中出现 cleanup_memories
  • command 包含当前阈值、天数与衰减系数

#8.10.2 Context Assembler

• 目标：在检索路径中按 token budget 组装长期记忆与近期历史。
• 受管函数：get_context_window()
• 受管任务：无
• 启动方式：
  • 在 Automation Config 中设置 max_tokens
  • 设置 memory_ratio 与 history_ratio
  • 点击"保存并同步"以更新函数默认参数
• 验证方式：
  • Functions 中的 get_context_window 定义与当前配置一致

说明：Context Assembler 没有独立 cron 任务，它通过函数默认参数参与实时检索，而不是后台调度。

#8.10.3 Maintenance Consolidation

• 目标：按时间窗口批量创建巩固任务。
• 受管函数：trigger_maintenance_consolidation()
• 受管任务：trigger_consolidation
• 启动方式：
  • 在 Automation Config 中设置 consolidation.schedule
  • 设置 lookback_interval
  • 打开 consolidation.enabled
• 验证方式：
  • Managed Jobs 中出现 trigger_consolidation
  • command 中包含当前 lookback_interval

#8.11 页面使用说明

#Automation Config

Automation Config 是唯一可写的业务配置入口，其底层权威存储为 negentropy.memory_automation_configs。

"保存并同步"的效果如下：

• 始终保存当前配置快照。
• 始终按当前 effective config 重新生成受管函数定义。
• 仅在 pg_cron 可用时重建 cleanup_memories 与 trigger_consolidation。

建议：

• 修改 Context Assembler 参数后，优先在 Functions 面板核对 get_context_window() 是否已更新。
• 修改调度参数后，优先在 Managed Jobs.command 中核对命令是否与当前配置一致。

#Managed Jobs

Managed Jobs 只管理两个预定义 job key：

• cleanup_memories
• trigger_consolidation

按钮行为如下：

• 启用/停用：切换 enabled 配置，并尝试同步数据库中的 cron 任务。
• 重建：按当前 effective config 重新生成 schedule 与 command。
• 手动触发：立即执行当前 job 对应 SQL，不等待 cron。

状态语义：

• scheduled：数据库中的 job 与当前期望一致。
• disabled：当前配置未启用该 job。
• missing：当前配置要求启用，但数据库中未找到对应 job。
• drifted：数据库中的 schedule 或 command 与当前配置不一致。
• degraded：pg_cron 不可访问，页面只能展示期望态。

#Functions

Functions 面板只展示受管函数，而不是数据库中的全部函数。

状态语义：

• present：数据库函数定义与当前 effective config 生成的期望 SQL 一致。
• missing：数据库中未找到该函数。
• drifted：数据库中的函数定义与当前配置期望不一致。

建议把这里作为"配置是否真正下沉到 PostgreSQL"的最终核验面。

#Recent Logs

Recent Logs 的数据源是 cron.job_run_details。

需要注意：

• 日志为空不必然表示没有任务运行。
• 首次配置后为空属于正常现象。
• 如果 pg_cron 未安装，或日志表不可访问，页面会返回空列表并给出降级原因。
• 日志更适合用于核对最近一次执行结果，不应视为长期审计存储。

#8.12 PostgreSQL 操作示例

以下 SQL 主要用于验证与排障；日常初始化优先通过 Automation 控制面执行。

#检查扩展

SELECT extname, extversion
FROM pg_extension
WHERE extname IN ('vector', 'pg_cron');

#检查受管函数

SELECT p.proname AS function_name
FROM pg_proc p
JOIN pg_namespace n ON p.pronamespace = n.oid
WHERE n.nspname = 'negentropy'
  AND p.proname IN (
    'calculate_retention_score',
    'cleanup_low_value_memories',
    'get_context_window',
    'trigger_maintenance_consolidation'
  )
ORDER BY p.proname;

#检查受管任务

SELECT jobid, jobname, schedule, command, active
FROM cron.job
WHERE jobname IN ('cleanup_memories', 'trigger_consolidation')
ORDER BY jobname;

#查看最近日志

SELECT jobid, runid, status, return_message, start_time, end_time
FROM cron.job_run_details
ORDER BY start_time DESC
LIMIT 10;

#手动验证受管过程

SELECT negentropy.cleanup_low_value_memories(0.1, 7, 0.1);
SELECT negentropy.trigger_maintenance_consolidation('1 hour'::interval);

说明：

• 手动执行适合验证函数本身是否可用，不替代 Managed Jobs 的长期调度。
• get_context_window() 依赖向量参数与业务上下文，通常应通过服务侧检索路径验证，而不是手工拼接 SQL。

#8.13 降级矩阵与排障

说明：

• "降级"表示 snapshot 仍然返回，但 health.status 为 degraded，并在 degraded_reasons 中给出原因。
• 调度相关动作包括 enable / disable / reconcile / run，在调度能力不可用时统一进入只读。

常见排障建议：

• pg_cron_not_installed
  • 执行 SELECT * FROM pg_extension WHERE extname = 'pg_cron';
  • 若未安装，页面仍可使用配置与函数控制面，但调度保持只读。
• pg_cron_unavailable
  • 优先检查应用连接用户是否可访问 cron.job。
  • 如果 cron.job 可读但启用、重建仍失败，再检查 cron.schedule / cron.unschedule 的执行权限。
  • 若扩展已安装但权限不足，Managed Jobs 会显示降级态。
• pg_cron_logs_unavailable
  • 检查 cron.job_run_details 是否存在且可读。
  • Recent Logs 为空时，不应直接判定调度未执行。
• function_drifted
  • 优先执行一次"保存并同步"，让后端按当前配置重建受管函数。
• job_drifted
  • 对照 Managed Jobs.command 与 cron.job.command，确认 schedule 与参数是否被外部改动。

#8.14 实施记录

• 新增 Memory Automation service，封装配置持久化、函数 reconcile、pg_cron 任务管理与日志读取。
• 新增 memory_automation_configs 表，保存后端托管配置。
• 新增 /memory/automation 页面与 API 代理，管理员可对白盒化过程执行受控运维动作。
• 将 /memory 现有 policies 摘要改为从 automation 配置派生，避免双源。

#8.15 验证清单

• Memory 主导航出现 Automation 二级入口。
• 管理员可查看配置、函数、任务与日志。
• 保存配置后自动 reconcile 预定义函数，并在调度可用时同步 reconcile 预定义任务。
• pg_cron 未安装或不可访问时页面进入降级只读态，但配置与函数状态仍可查看。
• 现有 Dashboard / Timeline / Facts / Audit 行为不回归。

#9. PostgreSQL 阶段：当前实现深度解析

#9.1 数据库存储设计

当前 Memory 系统完全基于 PostgreSQL 16+ 实现，利用以下扩展能力：

DDL 原型参见 schema/hippocampus_schema.sql（历史参考，当前运行时以 Alembic migration 和 Automation 控制面为准）。

#9.2 Service 实现分析

#9.3 API 端点全景

#9.4 当前阶段的局限性

#10. 终态愿景：多维记忆演进路线图

#10.1 演进路线总览

#10.2 Phase 2: 图记忆与时序增强

#Memory Graph

将 Memory 之间的语义关联存储为 Apache AGE 图边，复用 036-the-knowledge-graph.md 的 AGE 基础设施：

• 节点：每条 Memory 和 Fact 作为图节点
• 边：因果关系（CAUSES）、时序关系（FOLLOWS）、主题关联（RELATED_TO）
• 查询：Cypher 图遍历实现「关联记忆发现」—— 给定一条记忆，找到所有语义关联的记忆链

#Bi-Temporal Model

参考 Zep/Graphiti^[18]的双时态模型，为记忆边引入时间有效性：

优势：支持「当前什么是真的」和「过去某时刻什么是真的」两类时态查询。

#Sleep-Inspired Consolidation

引入类 SleepGate^[22]的三阶段巩固机制：

1. 冲突感知标记：检测新记忆与现有记忆的矛盾
2. 选择性遗忘：基于冲突检测结果，自动失效/压缩过时记忆
3. 巩固压缩：合并相关记忆为更紧凑的摘要表示

#10.3 Phase 3: 多智能体与自组织

#Multi-Scope Memory

参考 Mem0^[16]的四层作用域模型：

#MAGMA-Style Multi-Graph

参考 MAGMA^[8]的四图架构，将每条记忆同时映射到：

1. Semantic Graph：语义相似度边
2. Temporal Graph：时间顺序边
3. Causal Graph：因果关系边
4. Entity Graph：实体共现边

配合自适应遍历策略 (Adaptive Traversal Policy)，根据查询意图选择最相关的图视图进行检索。

#Self-Organizing Memory

参考 EverMemOS^[24]，实现记忆的自组织能力：

• 自动聚类：基于嵌入向量的在线聚类，发现记忆主题
• 冲突消解：跨记忆矛盾检测与自动消解
• 重要性自适应：超越固定 Ebbinghaus 公式，基于实际使用模式动态调整权重

#10.4 技术决策记录 (ADR)

#10.5 Phase 5 实施记录（开工于 2026-05）

详细工程契约见 026-memory-whitepaper.md §4；user-guide 高级特性开关见 memory-basics.md §2.5。

§9.4 局限性表对应行更新（Phase 5 实施完成后逐项打勾）：

#11. 价值量化体系 (Value Quantification System)

#11.1 设计哲学

遵循 AGENTS.md 的反馈闭环 (Feedback Loops) 原则：每一项工程行动都应产生可观测的反馈信号。Memory 价值量化体系的目标是：证明 Memory 子系统对 Agent 智能水平的可测量贡献。

#11.2 核心指标四层模型

#11.3 LongMemEval 基准对标

参考 LongMemEval^[9]（ICLR 2025）的 5 项核心能力维度，设计 Negentropy 的记忆能力评估方案：

#11.4 可观测性仪表盘设计

#11.5 反馈闭环：指标驱动的自动调参

Memory 价值量化不仅用于展示，更构成自我进化 (Evolutionary Design) 闭环：

#12. 安全与合规

#12.1 数据安全

• SQL 注入防护：embedding 参数通过 :embedding 参数化绑定传递，杜绝字符串拼接
• 通配符注入防护：ilike 回退中使用 re.sub(r"([%_])", r"\\\1", query) 转义 LIKE 特殊字符
• Schema 隔离：所有表和函数统一使用 NEGENTROPY_SCHEMA 常量前缀

#12.2 GDPR 合规矩阵

#12.3 权限模型

#13. 测试策略

#13.1 单元测试

cd apps/negentropy
uv run pytest tests/unit_tests/engine/test_memory_governance.py -v

覆盖场景：

• 遗忘曲线计算：新鲜记忆 / 高频访问 / 长期未访问 / 指数衰减公式 / 边界值 / 自定义 λ
• 审计决策逻辑：retain / delete / anonymize / 版本冲突 / 幂等性

#13.2 集成测试

cd apps/negentropy
uv run pytest tests/integration_tests/engine/adapters/postgres/test_memory_service.py -v
uv run pytest tests/unit_tests/engine/test_memory_automation_service.py -v

覆盖场景：

• PostgreSQL 混合检索（需要 pgvector）
• Fact upsert 唯一约束
• Automation 配置持久化与 reconcile

#13.3 基准测试方案

#14. 相关文档

• Memory 与 Knowledge 职责边界：035-the-knowledge-base.md
• 知识图谱技术方案：036-the-knowledge-graph.md
• 理论基础白皮书：026-memory-whitepaper.md
• 系统架构总览：framework.md
• DDL 原型（历史参考）：schema/hippocampus_schema.sql
• 外部设计文档：020-the-hippocampus.md

#15. 参考文献

#学术论文

[1] ThreeFish-AI, "Negentropy: One Root, Five Wings Agent System," GitHub Repository, 2026.

[2] H. Ebbinghaus, "Memory: A Contribution to Experimental Psychology," Teachers College, Columbia University, 1885/1913.

[3] S. Maharana et al., "Memory in the age of AI agents: A survey," arXiv preprint arXiv:2512.13564, Dec. 2025.

[4] Z. Zhang et al., "A survey on the memory mechanism of large language model based agents," ACM Trans. Inf. Syst., 2025.

[5] E. Gamma, R. Helm, R. Johnson, and J. Vlissides, "Design Patterns: Elements of Reusable Object-Oriented Software," Addison-Wesley, 1994.

[6] K. Shinn et al., "Reflexion: Language agents with verbal reinforcement learning," NeurIPS, 2023.

[7] C. Packer et al., "MemGPT: Towards LLMs as operating systems," arXiv preprint arXiv:2310.08560, 2023.

[8] T. Zhu et al., "MAGMA: A multi-graph based agentic memory architecture for AI agents," arXiv preprint arXiv:2601.03236, Jan. 2026.

[9] D. Wu et al., "LongMemEval: Benchmarking chat assistants on long-term interactive memory," ICLR, 2025.

[10] D. Edge et al., "From local to global: A Graph RAG approach to query-focused summarization," arXiv preprint arXiv:2404.16130, 2024.

[11] G. V. Cormack, C. L. A. Clarke, and S. Buettcher, "Reciprocal rank fusion outperforms condorcet and individual rank learning methods," SIGIR'09, 2009.

#工业框架

[12] Google, "Memory: Long-term knowledge with MemoryService," Agent Development Kit Documentation, 2026. [Online]. Available: https://adk.dev/sessions/memory/

[13] LangChain, "Memory," LangGraph Documentation, 2026. [Online]. Available: https://langchain-ai.github.io/langgraph/concepts/memory/

[14] Citus Data, "pg_cron," GitHub README, 2026. [Online]. Available: https://github.com/citusdata/pg_cron

[15] ThreeFish-AI, "The Hippocampus," agentic-ai-cognizes, 2026. [Online]. Available: https://github.com/ThreeFish-AI/agentic-ai-cognizes/blob/master/docs/design/020-the-hippocampus.md

[16] Mem0, "Platform documentation," Mem0, 2025. [Online]. Available: https://docs.mem0.ai/

[17] Cognee, "Cognee documentation," Cognee, 2025. [Online]. Available: https://docs.cognee.ai/

[18] P. Rasmussen et al., "Zep: A temporal knowledge graph architecture for agent memory," arXiv preprint arXiv:2501.13956, Jan. 2025.

[19] Letta, "Letta platform documentation," Letta, 2025. [Online]. Available: https://docs.letta.com/

[29] Mem0, "Memory extraction and consolidation pipeline," Mem0 Documentation, 2025. [Online]. Available: https://docs.mem0.ai/open-source/quickstart

[30] Letta (MemGPT), "Self-editing memory and virtual context management," Letta Documentation, 2025. [Online]. Available: https://docs.letta.com/

#基准测试

[20] ICLR 2026 Workshop, "MemAgents: Memory for LLM-based agentic systems," OpenReview, 2026.

[21] Y. Wang et al., "Anatomy of agentic memory: Taxonomy and empirical analysis," arXiv preprint arXiv:2602.19320, 2026.

[22] X. Chen et al., "Learning to forget: Sleep-inspired memory consolidation for resolving proactive interference in LLMs," arXiv preprint arXiv:2603.14517, 2026.

[23] Y. Li et al., "LightMem: Lightweight and efficient memory-augmented generation," arXiv preprint arXiv:2510.18866, 2025.

[24] EverMemOS, "A self-organizing memory operating system for structured long-horizon reasoning," 2026.

#Phase 2+ 增强参考文献

[31] C. D. Manning, P. Raghavan, and H. Schütze, Introduction to Information Retrieval. Cambridge, UK: Cambridge University Press, 2008.

[32] G. Shani and A. Gunawardana, "Evaluating recommendation systems," in Recommender Systems Handbook, F. Ricci, L. Rokach, B. Shapira, and P. B. Kantor, Eds. New York, NY: Springer, 2011, pp. 257–297.

[33] P. F. Christiano et al., "Deep reinforcement learning from human preferences," in Adv. Neural Inf. Process. Syst. (NeurIPS), vol. 30, pp. 7299–7307, 2017.

[34] S. Es et al., "RAGAS: Automated evaluation of retrieval augmented generation," in ECAI 2024, 2024.

[35] J. Carbonell and J. Goldstein, "The use of MMR, diversity-based reranking for reordering documents and producing summaries," in Proc. 21st ACM SIGIR, Melbourne, Australia, 1998, pp. 335–336.

[36] A. Dong, Y. Chang, Z. Zheng, H. Zha, and K. Mei, "A time machine for search engine," in Proc. 33rd ACM SIGIR, Geneva, Switzerland, 2010, pp. 609–616.

[37] A. Z. Broder, "On the resemblance and containment of documents," in Proc. SEQUENCES, Positano, Italy, 1997, pp. 21–29.

[38] M. S. Charikar, "Similarity estimation techniques from rounding algorithms," in Proc. 34th ACM STOC, Montreal, Canada, 2002, pp. 380–388.

[39] P. Indyk and R. Motwani, "Approximate nearest neighbors: Towards removing the curse of dimensionality," in Proc. 30th ACM STOC, Dallas, TX, 1998, pp. 604–613.

[40] M. R. Henzinger, "Finding near-duplicate web documents: A large-scale evaluation of algorithms," in Proc. 29th ACM SIGIR, Seattle, WA, 2006, pp. 284–291.

[41] J. Zhang et al., "Machine learning testing: Survey, landscapes, and horizons," IEEE Trans. Softw. Eng., vol. 48, no. 2, pp. 508–539, Feb. 2022.

[42] D. Sculley et al., "Hidden technical debt in machine learning systems," in Adv. Neural Inf. Process. Syst. (NeurIPS), vol. 28, pp. 2503–2511, 2015.

[43] T. Y. Chen, F.-C. Kuo, H. Liu, and S. L. Poon, "Metamorphic testing: A review of challenges and opportunities," ACM Comput. Surveys, vol. 51, no. 1, pp. 1–27, Jan. 2018.

[25] R. Sennrich, B. Haddow, and A. Birch, "Neural machine translation of rare words with subword units," ACL, 2016.

[26] S. J. Sara, "Reconsolidation and the stability of memory traces: A new perspective," Current Opinion in Neurobiology, vol. 35, pp. 110-115, 2015.

[27] J. J. Rocchio, "Relevance feedback in information retrieval," in The SMART Retrieval System, G. Salton, Ed. Englewood Cliffs, NJ: Prentice-Hall, 1971, pp. 313-323.

[28] C. J. C. Burges et al., "Learning to rank using gradient descent," ICML, 2005.

#Phase 2++ 增强参考文献

[44] T. Haerder and A. Reuter, "Principles of transaction-oriented database recovery," ACM Comput. Surveys, vol. 15, no. 4, pp. 287–317, Dec. 1983.

[45] J. R. Anderson et al., "An integrated theory of the mind," Psychological Review, vol. 111, no. 4, pp. 1036–1060, 2004.

[46] FadeMem, "Biologically-inspired forgetting for agent memory," arXiv preprint arXiv:2601.18642, 2026.

[47] M. Nygard, Release It!, 2nd ed. Raleigh, NC: Pragmatic Bookshelf, 2018.

[48] C. Majors, L. Fong-Jones, and G. Miranda, Observability Engineering. Sebastopol, CA: O'Reilly, 2022.

#Phase 3 增强参考文献

[49] C. E. Alchourrón, P. Gärdenfors, and D. Makinson, "On the logic of theory change," J. Symbolic Logic, vol. 50, no. 2, pp. 510–530, 1985.

[50] J. Doyle, "A truth maintenance system," Artificial Intelligence, vol. 12, no. 3, pp. 231–272, 1979.

[51] A. M. Collins and E. F. Loftus, "A spreading-activation theory of semantic processing," Psychological Review, vol. 82, no. 6, pp. 407–428, 1975.

[52] D. R. Godden and A. D. Baddeley, "Context-dependent memory in two natural environments," British J. Psychology, vol. 66, no. 3, pp. 325–331, 1975.

[53] E. Tulving, "Episodic and semantic memory," in Organization of Memory, E. Tulving and W. Donaldson, Eds. New York: Academic Press, 1972, pp. 381–403.

文档维护：本文档与代码同步演进。架构变更时需同步更新对应章节，保持代码事实与文档描述的一致性。