Phase 2：The Hippocampus 验证实施方案

[!NOTE]

文档定位：本文档是 000-roadmap.md Phase 2 的详细工程实施方案，用于指导「The Hippocampus (仿生记忆)」的完整落地验证工作。涵盖技术调研、架构设计、代码实现、测试验证等全流程。

前置依赖：本阶段依赖 010-the-pulse.md Phase 1 的完成，需复用其统一存储基座 (Unified Schema) 和会话管理能力。

#1. 执行摘要

#1.1 定位与目标 (Phase 2)

Phase 2: The Hippocampus 是整个验证计划的记忆核心阶段，对标人类大脑的海马体 (Hippocampus) —— 负责将短期记忆转化为长期记忆的关键脑区。核心目标是：

1. 实现 Zero-ETL 记忆架构：摒弃传统 Redis (App) + VectorDB (Mem) 的割裂架构，Session Log 与 Semantic Memory 同库存储
2. 验证记忆巩固机制：实现从 Short-term 到 Long-term 的无缝流转（Fast Replay + Deep Reflection）
3. 验证生物遗忘机制：实现艾宾浩斯衰减算法，自动清理低价值记忆
4. 验证 Context Budgeting：实现动态上下文组装，精准控制 Token 预算

#1.2 核心认知架构 (Core Cognitive Architecture)

为了构建具备"长期心智"的 Agent，我们参照认知心理学模型，设计了更加体系化的记忆系统。该系统不仅是数据的存储库，更是信息流转与升维的加工厂。

#1.2.1 记忆模型：正交的三维视图 (Static View)

我们将长期记忆解耦为三个正交维度，分别解决"经历"、"知识"与"技能"的持久化问题：

#1.2.2 动态机制：海马体循环 (Dynamic View)

模仿人脑的海马体 (Hippocampus) 功能，我们在系统中引入了记忆巩固 (Consolidation) 与再激活 (Reactivation) 的动态循环：

1. Working Memory (工作记忆)：作为系统的"前额叶"，接收用户输入并维护当前的上下文窗口 (Context Window)。
2. Hippocampus (海马体/LTM)：长时记忆的存储中心，由情景 (Episodic)、语义 (Semantic) 和程序性 (Procedural) 三个正交的记忆区组成。
3. Cognitive Processes (认知过程)：连接 WM 与 LTM 的动态机制，通过以下四个关键过程维持系统的"新陈代谢"：
   • Encoding (编码)：将实时的短期交互转化为可存储的记忆痕迹。
   • Consolidation (巩固)：在后台异步运行，将碎片化的对话历史提炼为结构化的事实与知识。
   • Retrieval (检索)：基于语义相关性，在需要时将沉睡的长期记忆"再激活"并加载回工作记忆。
   • Decay (衰减)：模拟生物遗忘机制，定期清理低价值或长期未被访问的记忆，防止记忆库臃肿。

#1.2.3 关键特性 (Key Features)

1. 双重路径 (Dual Pathways):

   • 快路径 (Fast Path): 实时对话流直接进入工作记忆，保证响应速度。
   • 慢路径 (Slow Path): 异步进程在后台进行"反思"与"巩固"，将碎片化对话转化为结构化知识。

2. 联想召回 (Associative Recall):

   • 摒弃单纯的关键词匹配，利用 Embedding Vector 实现基于语义相似度的模糊召回，模拟"触景生情"的认知体验。

3. 生物性遗忘 (Biological Decay):

   • 引入基于 Ebbinghaus 遗忘曲线的 Retention Score，让低价值记忆随时间自然消退，保持记忆库的"信噪比"与鲜活性。

#1.3 执行导图 (Execution Map)

为了确保系统的正交性 (Orthogonality) 与自洽性 (Self-consistency)，我们将执行计划重构为分层递进的实施路径，确保每一层都在坚实的基础上构建。

#1.3.1 任务-文档锚定

我们将工程任务映射到架构的三个正交切面：基础架构 (Infra)、认知过程 (Process) 与 服务集成 (Service)。

[!NOTE]

版本对照：本计划属于 Engine Roadmap (Phase 2)，对应 Project Roadmap (002-task-checklist) 中的 Phase 3 (T3.3 记忆持久化)。

#1.3.2 工期安排 (2.5 Days)

#2. 核心参考模型：仿生记忆机制

#2.1 Google ADK

#2.1.1 对标分析：Google ADK MemoryService

基于 Google ADK 官方文档^[3]，我们将复刻其核心能力，并映射到 PostgreSQL 生态：

#2.1.2 接口契约 (Interface Contract)

我们遵循 ADK 的 BaseMemoryService 标准接口，确保 Drop-in Compatible：

class BaseMemoryService(ABC):
    @abstractmethod
    async def add_session_to_memory(self, session: Session) -> None:
        """Trigger: 异步触发记忆巩固 (Inflow)"""
        ...

    @abstractmethod
    async def search_memory(self, *, app_name: str, user_id: str, query: str) -> SearchMemoryResponse:
        """Trigger: 实时检索相关记忆 (Retrieval)"""
        ...

#2.1.3 工作流参考 (Workflow Reference)

Memory Bank 的核心价值在于将 写入 (Consolidation) 与 读取 (Retrieval) 解耦：

关键洞察：

1. 正交性: 记忆生成 (Worker) 与 记忆使用 (Agent) 互不阻塞。
2. 双向流: Session 数据流入 Memory，Memory 知识流回 Agent。
3. 白盒化: 我们将原版黑盒的 Vertex AI 逻辑替换为可观测的 ConsolidationWorker。

#2.1.4 写入策略 (Writing Strategy)

结合 LangGraph 的设计理念^[2]，我们在时序图中明确区分了两种写入路径：

我们的决策：

• Fast Replay: 作为热路径的补充，通过 Session 快速回溯。
• Deep Reflection: 必须异步。因为 Fact Extraction 需要昂贵的 LLM 推理，绝不能阻塞用户对话。

#2.2 LangGraph Memory 设计模式

LangGraph 的 Memory 设计为我们提供了重要的实现参考^[2]。

#2.2.1 持久化机制对照

LangGraph 提供两套互补的持久化机制，与我们的实现形成清晰映射：

#2.2.2 三类记忆的实现参考

LangGraph 的三类记忆在我们的方案中通过统一的 Repository 接口实现：

# Semantic Memory: 用户偏好存储
store.put(namespace=(user_id, "preferences"), key="food", value={"likes": ["pizza"], "dislikes": ["spicy"]})

# Episodic Memory: 情景记忆检索
memories = store.search(namespace=(user_id, "episodes"), query="similar task")

# Procedural Memory: Agent 自我进化
store.put(("agent_instructions",), "main", {"instructions": new_instructions})

#2.3 综合对比分析 (Comparative Analysis)

基于上述调研，我们将取长补短，构建 The Hippocampus 引擎：

#2.4 调研交付物摘要

[!NOTE] 本节汇总任务 P2-1-1 ~ P2-1-5 的调研成果。详细的技术分析已在前文展开，此处仅做索引索引与交付确认。

#2.4.1 核心交付物索引

#2.4.2 关键技术选型确认

基于上述调研，我们确认以下核心技术栈映射：

#3. 架构设计：Hippocampus Schema 扩展

#3.1 Schema 扩展设计

在 Phase 1 的 Unified Schema 基础上，新增以下记忆相关表：

#3.2 记忆模型职责边界 (Memory Responsibilities)

遵循 AGENTS.md 的 Orthogonal Decomposition (正交分解) 原则，我们将三种记忆严格映射到三张表中，确保职责互不重叠且自洽。

#3.2.1 职责正交矩阵

#3.2.2 关于 memory_type='semantic' 的消歧

在 memories 表的定义中，memory_type 包含 semantic 枚举，这与 facts 表看似重叠。为了消除歧义 (Entropy Reduction)，我们做出以下 明确界定：

1. facts 表 (Primary Semantic):

   • 定义: 经过深度固化、去重且结构化的确切知识。
   • 场景: "用户不喜欢吃辣", "用户的职业是工程师"。这是系统认为"为真"的事实。

2. memories 表中的 semantic 类型 (Secondary/Transient):

   • 定义: 尚未完全结构化，或难以用 KV 表达的泛化知识片段。也可以理解为"关于某个知识点的非结构化描述"。
   • 场景: "用户详细阐述了他对人工智能未来的看法"（一段 500 字的观点）。这不适合存为 KV Fact，但它是一段具备"语义价值"的记忆，比单纯的"对话切片 (episodic)"更抽象。
   • 推荐策略: 初期 优先使用 episodic 和 summary。仅当需要存储大段非结构化知识（如文档片段 RAG）时使用 semantic 类型。此时 memories 充当了轻量级的 Vector DB。

[!TIP]

设计心法:

• memories 是 Agent 的 "日记本" (叙事)。
• facts 是 Agent 的 "档案库" (画像)。
• instructions 是 Agent 的 "员工手册" (规则)。

#3.3 核心 Schema 定义 (Single Source of Truth)

为了遵循 Entropy Reduction (熵减) 原则，避免文档与代码的 drift，所有的 DDL 和 SQL 函数定义已收敛至统一的 Schema 文件维护。

[!IMPORTANT]

Source of Truth: src/cognizes/engine/schema/hippocampus_schema.sql

该文件包含：

1. Tables: memories, facts, consolidation_jobs, instructions
2. Indexes: PGVector HNSW 索引与 B-Tree 辅助索引
3. Functions: calculate_retention_score (艾宾浩斯衰减), cleanup_low_value_memories (自动清理), get_context_window (上下文组装)

#4. 实施指南

#4.1 Step 1: 记忆 Schema 扩展部署

#4.1.1 部署执行 (Deployment Execution)

本 Schema 设计具备 幂等性 (Idempotency)，可重复执行。

# 确保位于项目根目录，并正确配置 PSQL 环境变量
# export PGPASSWORD=your_password

# 执行部署 (包含 Tables, Indexes, Functions)
psql -d 'cognizes-engine' -f src/cognizes/engine/schema/hippocampus_schema.sql

#4.1.2 验收验证 (Verification SOP)

执行以下 SOP 确保对象创建正确：

# 1. 验证核心表结构 (4 Tables)
psql -d 'cognizes-engine' -c "\dt" | grep -E 'memories|facts|consolidation_jobs|instructions'

# 2. 验证向量索引 (HNSW)
psql -d 'cognizes-engine' -c "SELECT indexname, indexdef FROM pg_indexes WHERE indexname = 'idx_memories_embedding';"

# 3. 验证功能函数 (3 Functions)
psql -d 'cognizes-engine' -c "\df calculate_retention_score"
psql -d 'cognizes-engine' -c "\df cleanup_low_value_memories"
psql -d 'cognizes-engine' -c "\df get_context_window"

# 4. 功能冒烟测试 (Function Smoke Test)
psql -d 'cognizes-engine' -c "SELECT calculate_retention_score(5, NOW() - INTERVAL '3 days') AS score;"
# 预期结果: score < 1.0 (e.g., ~0.95)

#4.1.3 定时任务配置 (pg_cron) - P2-2-8

我们通过 PostgreSQL 内建的定时任务来实现记忆系统的自维护 (Self-Maintenance)。

前提条件: 需先安装并启用 pg_cron 扩展（详见 010-the-pulse.md）。

Step 1: 注册定时任务 (Execution)

-- 1. 记忆清理 (每日凌晨 02:00)
-- 清理访问率低且陈旧的记忆，保持 Context 清爽
SELECT cron.schedule(
    'cleanup_memories',
    '0 2 * * *',
    $$SELECT cleanup_low_value_memories(0.1, 7)$$
);

-- 2. 周期性巩固 (每小时)
-- 扫描最近活跃的会话，生成 consolidate 任务
SELECT cron.schedule(
    'trigger_consolidation',
    '0 * * * *',
    $$SELECT trigger_maintenance_consolidation('1 hour'::interval)$$
);

Step 2: 任务验证 (Verification)

# 1. 验证任务是否注册
psql -d 'cognizes-engine' -c "SELECT jobid, schedule, command FROM cron.job;"

# 2. 手动触发测试 (验证函数逻辑)
psql -d 'cognizes-engine' -c "SELECT trigger_maintenance_consolidation('1 day'::interval);"
# 预期: 返回生成的 job 数量

#4.2 Step 2: Memory Consolidation Worker 实现

#4.2.1 核心架构设计

Memory Consolidation Worker 采用两阶段巩固策略，模拟人类大脑的记忆巩固过程：

#4.2.2 核心代码实现 (Source of Truth)

为了遵循 Entropy Reduction (熵减) 原则，具体的业务逻辑代码已收敛至源文件维护。

[!IMPORTANT]

Source of Truth: src/cognizes/engine/hippocampus/consolidation_worker.py

该模块实现了 MemoryConsolidationWorker 类，负责：

1. Fast Replay: 使用 _generate_summary 快速生成对话摘要。
2. Deep Reflection: 使用 _extract_facts 深度提取结构化事实 (Facts) 和洞察 (Insights)。
3. Vectorization: 调用 _generate_embedding (Gemini text-embedding-004) 生成向量。
4. Storage: 将处理结果分别存入 memories (Summary/Insight) 和 facts (Preference/Proflie) 表。

#4.2.3 使用示例 (SDK)

# 使用示例: 手动触发记忆巩固
import asyncio
import asyncpg
from cognizes.engine.hippocampus.consolidation_worker import MemoryConsolidationWorker, JobType

async def main():
    # 1. 创建数据库连接池 (通常由 DatabaseManager 管理)
    pool = await asyncpg.create_pool("postgresql://aigc:@localhost/cognizes-engine")

    # 2. 初始化 Worker
    worker = MemoryConsolidationWorker(pool)

    # 3. 执行完整巩固 (Full Consolidation)
    # 包含: Fast Replay (摘要) + Deep Reflection (事实提取)
    job = await worker.consolidate(
        thread_id="your-thread-id",
        job_type=JobType.FULL_CONSOLIDATION
    )

    print(f"Job completed: {job.result}")
    await pool.close()

if __name__ == "__main__":
    asyncio.run(main())

#4.3 Step 3: Biological Retention 实现

#4.3.1 艾宾浩斯遗忘曲线原理

艾宾浩斯遗忘曲线描述了记忆随时间衰减的规律。我们将其应用于 Agent 记忆系统：

公式：

其中：

• $\text{time\_decay} = e^{-\lambda \times \text{days\_elapsed}}$ (指数衰减)
• $\text{frequency\_boost} = 1 + \ln(1 + \text{access\_count})$ (对数加成)
• $\lambda = 0.1$ (默认衰减系数)

#4.3.2 Memory Retention Manager 实现

[!IMPORTANT]

Source of Truth: src/cognizes/engine/hippocampus/retention_manager.py

负责实现艾宾浩斯遗忘曲线算法，自动管理记忆的保持与清理：

1. Retention Score Calculation: 根据时间衰减和访问频率计算分值。
2. Access Recording: 记录访问历史 (record_access)，提升高频记忆的权重。
3. Low Value Cleanup: 周期性清理低价值 (score < 0.1) 且陈旧的记忆 (cleanup_low_value_memories)。

#4.3.3 Context Window 组装器实现

[!IMPORTANT]

Source of Truth: src/cognizes/engine/hippocampus/context_assembler.py

负责根据 Token 预算动态组装 LLM 上下文窗口。该模块 (ContextAssembler 类) 实现了 Python 侧的预算分配逻辑，而非单纯依赖 SQL：

1. Budgeting: 根据配置比例 (System 10%, Memory 30%, History 40%...) 分配 Token 预算。
2. Assembly: 检索并筛选 System Prompt, Top-K Memories, Recent History, 和 Facts。
3. Truncation: 确保总 Token 数不超过模型限制。

#4.4 Step 4: OpenMemoryService 实现 (ADK 适配器)

本服务作为 ADK MemoryService 的 PostgreSQL 适配器，对外提供统一的记忆读写接口。

[!IMPORTANT]

Source of Truth: src/cognizes/adapters/postgres/memory_service.py

#4.4.1 核心能力 (Capabilities)

该服务封装了底层的 Worker 和 Manager，提供以下核心 API：

1. add_session_to_memory(session_id, consolidation_type):

   • 功能: 触发记忆巩固流程。
   • 实现: 委托给 MemoryConsolidationWorker 异步执行。
   • ADK 映射: 对应 ADK MemoryService.add_memory().

2. search_memory(query, user_id, app_name):

   • 功能: 语义检索相关记忆。
   • 实现: 调用 Gemini retrieval_query 模型生成向量，在 memories 表执行 HNSW 相似度搜索。
   • 结果: 返回 SearchMemoryResponse 对象，包含匹配的记忆片段及其相关度分数。

3. get_context_window(user_id, app_name, query):

   • 功能: 构建 LLM 上下文窗口。
   • 实现: 调用 ContextAssembler (Python 类) 动态组装 System Prompt (Instructions) + Facts + Memories + History，确保严格遵守 Token 预算。
   • 说明: 虽然底层存在 SQL 函数 get_context_window，但为了更精细的控制，应用层逻辑是主要的组装者。

#4.4.2 接口契约验证

为了确保适配器符合 ADK 标准，请执行以下集成测试：

# 运行 Memory Service 集成测试
pytest tests/integration/engine/test_memory_service.py

#4.5 Step 5: AG-UI 记忆系统可视化接口

[!NOTE]

对标 AG-UI 协议：本节实现 The Hippocampus 与 AG-UI 可视化层的集成，提供记忆巩固状态、记忆召回来源和记忆健康度的可视化能力。

参考资源：

• AG-UI 协议调研
• AG-UI 官方文档

#4.5.1 记忆可视化架构

#4.5.2 AG-UI 事件映射表

#4.5.3 MemoryVisualizer 实现

[!IMPORTANT]

Source of Truth: src/cognizes/engine/hippocampus/memory_visualizer.py

#4.5.4 前端展示组件规范

#4.5.5 任务清单

#4.5.6 验收标准

#5. 验证 SOP (Phase 2)

[!IMPORTANT]

本节提供 Phase 2: The Hippocampus 完整验收流程，请按顺序逐步执行。

Phase 2 验证是一次深入的认知功能评估 (Cognitive Assessment)。我们需要依次确认记忆中枢结构完备 (Schema Anatomy)、神经单元逻辑自洽 (Unit Logic)、记忆回路畅通 (Memory Circuit) 以及海马体承载极限 (Performance Capacity)。

#5.1 Step 1: Schema 部署验证

# 1.1 确保 Phase 1 Schema 已部署
psql -d 'cognizes-engine' -c "\dt threads"
# 应显示 threads 表

# 1.2 部署 Hippocampus Schema
psql -d 'cognizes-engine' -f src/cognizes/engine/schema/hippocampus_schema.sql

# 1.3 验证表创建
psql -d 'cognizes-engine' -c "\dt"
# 应显示: memories, facts, consolidation_jobs, instructions

# 1.4 验证索引
psql -d 'cognizes-engine' -c "\di" | grep -E "(memories|facts)"

# 1.5 验证函数
psql -d 'cognizes-engine' -c "\df calculate_retention_score"
psql -d 'cognizes-engine' -c "\df cleanup_low_value_memories"

# 1.6 测试衰减函数
psql -d 'cognizes-engine' -c "SELECT calculate_retention_score(5, NOW() - INTERVAL '3 days', 0.1);"
# 应返回 0.x 的浮点数

验收标准：

• memories, facts, consolidation_jobs, instructions 表存在
• HNSW 向量索引已创建
• calculate_retention_score 函数可正常调用
• cleanup_low_value_memories 函数存在

#5.1.1 Step 1.1: pg_cron 定时任务配置 (P2-2-8, P2-3-4)

[!IMPORTANT]

pg_cron 定时任务用于自动触发记忆巩固和低价值记忆清理，需配置后 Phase 2 验收才能完整通过。

# 1.1 检查 pg_cron 扩展是否已安装 (Phase 1 已完成)
psql -d 'cognizes-engine' -c "SELECT * FROM pg_extension WHERE extname = 'pg_cron';"
# 应返回 1 行记录

# 1.2 配置定时任务 - 每天凌晨 2 点清理低价值记忆 (P2-3-4)
psql -d 'cognizes-engine' -c "
SELECT cron.schedule(
    'cleanup_memories',
    '0 2 * * *',
    \$\$SELECT cleanup_low_value_memories(0.1, 7)\$\$
);
"
# 应返回任务 ID (如 1)

# 1.3 配置定时任务 - 每小时触发记忆巩固检查 (P2-2-8)
psql -d 'cognizes-engine' -c "
SELECT cron.schedule(
    'trigger_consolidation',
    '0 * * * *',
    \$\$SELECT trigger_maintenance_consolidation('1 hour'::interval)\$\$
);
"
# 应返回任务 ID (如 2)

# 1.4 验证定时任务创建成功
psql -d 'cognizes-engine' -c "SELECT jobid, jobname, schedule, command FROM cron.job;"
# 应显示 cleanup_memories 和 trigger_consolidation 两个任务

# 1.5 查看任务执行日志 (首次配置后可能为空)
psql -d 'cognizes-engine' -c "SELECT * FROM cron.job_run_details ORDER BY start_time DESC LIMIT 5;"

# 1.6 手动测试清理函数 (可选)
psql -d 'cognizes-engine' -c "SELECT cleanup_low_value_memories(0.1, 7);"
# 应返回清理的记录数 (可能为 0)

验收标准：

• pg_cron 扩展已安装
• cleanup_memories 定时任务已创建 (每天 02:00)
• trigger_consolidation 定时任务已创建 (每小时)
• cron.job 表显示 2 个任务

删除任务 (如需重新配置)：

# 删除指定任务
psql -d 'cognizes-engine' -c "SELECT cron.unschedule('cleanup_memories');"
psql -d 'cognizes-engine' -c "SELECT cron.unschedule('trigger_consolidation');"

#5.2 Step 2: 单元测试验证

[!NOTE]

验证 Memory Consolidation Worker 的核心逻辑 (P2-4-3)。

#5.2.1 运行单元测试

对应测试文件：

• 单元测试: tests/unittests/engine/hippocampus/test_consolidation_worker.py
• 测试配置: tests/unittests/engine/hippocampus/conftest.py

# 2.1 运行 Hippocampus 单元测试
uv run pytest tests/unittests/engine/hippocampus/ -v --tb=short
uv run pytest tests/unittests/engine/hippocampus/test_consolidation_worker.py -v

关键验证点:

1. Fast Replay: 应生成 Summary
2. Deep Reflection: 应提取 Facts
3. Full Consolidation: 应执行两个阶段
4. Mock Isolation: 外部依赖 (LLM, DB) 均使用 Mock

#5.2.2 覆盖率检查 (可选)

# 2.2 查看测试覆盖率 (需先安装 pytest-cov)
# uv add pytest-cov --dev
uv run pytest tests/unittests/engine/hippocampus/ -v --cov=src/cognizes/engine/hippocampus --cov-report=term-missing

验收标准：

• 35 个单元测试全部通过
• 覆盖以下模块:
  • consolidation_worker.py (数据类、枚举、格式化逻辑)
  • retention_manager.py (保留分数分布)
  • context_assembler.py (Token 估算、上下文格式化)
  • memory_service.py (服务参数验证)
  • memory_visualizer.py (事件类型、进度计算)

#5.3 Step 3: 集成测试验证

# 3.1 运行 Hippocampus 集成测试
uv run pytest tests/integration/engine/hippocampus/ -v -s --tb=short

# 3.2 查看详细输出 (含性能指标)
uv run pytest tests/integration/engine/hippocampus/ -v -s

验收标准：

• 16 个集成测试全部通过
• Schema 测试通过: 表结构、索引、函数、约束
• Read-Your-Writes 延迟 < 100ms
• 情景分块检索性能 P99 < 50ms (1K 规模)
• 保留分数分布统计正确
• 访问计数递增正确
• Fact Upsert 约束生效

#5.4 Step 4: 性能与一致性测试 (10 万规模)

[!NOTE]

验证系统的核心性能指标 (P2-3-7) 和一致性保证 (P2-2-13)。

#5.4.1 Step 4.1: Read-Your-Writes 延迟测试

验证新写入的记忆能否在下一个 Turn 立即可见，确保 Zero-ETL 架构的即时性。

对应测试文件：tests/integration/engine/hippocampus/test_read_your_writes.py

# 运行 Read-Your-Writes 测试
uv run pytest tests/integration/engine/hippocampus/test_read_your_writes.py -v -s

关键验证点:

1. 执行记忆巩固 (写入)
2. 立即执行记忆检索 (读取)
3. 验证新写入的记忆立即可见
4. 延迟 < 100ms (P99)

#5.4.2 Step 4.2: 情景分块检索性能测试

验证在 10 万记忆规模下，按时间切片检索的性能。

对应测试文件：tests/integration/engine/hippocampus/test_episodic_performance.py

# 1. 准备性能测试数据 (自动清理旧数据并生成 100K 新数据)
uv run python tests/performance/hippocampus/seed_data.py --action all --count 100000

# 2. 运行完整性能测试
uv run pytest tests/integration/engine/hippocampus/test_episodic_performance.py -v -s -k "full"

关键验证点:

1. 10 万条记忆规模
2. 随机生成 7 天窗口查询
3. 验证复合索引使用 (Index Scan)
4. 延迟 < 100ms (P99)

验收标准：

• 10 万规模时间切片查询 P99 < 100ms
• 查询使用索引扫描 (非全表扫描)

#5.5 Step 5: 模块导入验证

# 5.1 验证模块可导入
uv run pytest tests/integration/engine/hippocampus/test_imports_check.py -v

验收标准：

• 所有模块可正常导入 (tests passed)
• 无循环依赖错误

#5.6 Step 6: 全量测试验证

# 6.1 运行所有测试 (包括 Phase 1)
uv run pytest tests/ -v --tb=line

# 6.2 查看测试统计
uv run pytest tests/ -v --tb=line 2>&1 | tail -5

验收标准：

• Phase 1 测试: All passed
• Phase 2 单元测试: All passed
• Phase 2 集成测试: All passed
• 总计: All tests passed

#5.7 验收总结清单

[!TIP]

完成上述所有验收项后，勾选状态为 ✅，Phase 2: The Hippocampus 验收通过，可进入 Phase 3: The Perception。

#6. 验收基准

#6.1 功能验收矩阵

#6.2 性能验收指标

#6.3 兼容性验收

#6.5. 交付物清单

#6.5.1 Schema 文件

#6.5.2 代码文件

#6.5.3 测试文件

#6.5.4 目录结构

src/cognizes/
├── core/
│   └── repositories/          # Core Data Access Layer
│       ├── memory.py
│       └── facts.py
├── engine/
│   ├── schema/
│   │   └── hippocampus_schema.sql
│   └── hippocampus/           # Phase 2: The Hippocampus
│       ├── consolidation_worker.py
│       ├── retention_manager.py
│       ├── context_assembler.py
│       ├── memory_service.py
│       └── memory_visualizer.py
tests/
├── unittests/
│   └── engine/
│       └── hippocampus/       # Unit Tests
└── integration/
    └── engine/
        └── hippocampus/       # Integration & Performance Tests

#7. 风险与缓解策略

#7.1 技术风险

#7.2 工程风险

#8. 附录

#8.1 Prompt 模板参考

请见独立文档: prompt_template.md

#8.2 衰减算法参数调优指南

[!TIP]

Configuration Locations:

1. Runtime App: Update src/config.py (passed to RetentionManager).
2. Periodic Cleanup: Update pg_cron schedule or SQL function defaults in hippocampus_schema.sql.

#9. 参考文献

[1] Psychology Today, "Types of Memory," Psychology Today, 2024. [Online]. Available: https://www.psychologytoday.com/us/basics/memory/types-of-memory

[2] LangChain, "LangGraph Memory Overview," LangChain Documentation, 2025. [Online]. Available: https://docs.langchain.com/oss/python/langgraph/memory

[3] Google, "ADK Memory Documentation," Google ADK Docs, 2025. [Online]. Available: https://google.github.io/adk-docs/sessions/memory/

[4] Google, "ADK Sessions Documentation," Google ADK Docs, 2025. [Online]. Available: https://google.github.io/adk-docs/sessions/

[5] LangChain, "LangGraph Memory Agent," GitHub Repository, 2024. [Online]. Available: https://github.com/langchain-ai/memory-agent

[6] LangChain, "LangGraph Memory Template," GitHub Repository, 2024. [Online]. Available: https://github.com/langchain-ai/memory-template

[7] SII-GAIR, "Context Engineering 2.0: The Context of Context Engineering," SII-GAIR Technical Report, 2025.

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