Agent Memory System

版权所有 © 2024 kiwifruit

本程序采用 GNU General Public License v3.0 许可证。

详见: GNU General Public License v3.0

任务目标

• 本 Skill 用于：为智能体构建完整的记忆能力基础设施，实现 Context Engineering 核心能力
• 触发条件：元技能，强制常驻运行（always: true）
• 核心能力：
  • 选择：噪声过滤 + 相关性筛选
  • 压缩：链结构提取（因果/逻辑/操作/叙事/时间）+ 工具结果压缩
  • 检索：结果重排序 + 多样性保证
  • 状态：任务进度追踪 + 目标对齐
  • 记忆：冲突检测 + 跨会话关联

架构概述

本 Skill 采用四层架构，以认知模型层为核心，ContextOrchestrator 为统一入口和总控中心：

┌─────────────────────────────────────────────────────────────────┐
│                  顶层：总控层（统一入口）                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │           ContextOrchestrator（总控中心）                   │  │
│  │  • Token预算管理  • 检索决策  • 多源协调  • 结果压缩        │  │
│  │  • 认知模型构建  • 全局调度  • 可观测性管理                │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  中间层：协调层                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │           认知模型层（核心业务逻辑）                       │  │
│  │  • CognitiveModelBuilder  • CausalChainExtractor          │  │
│  │  • KnowledgeGapIdentifier • RetrievalDecisionEngine       │  │
│  │  • ...（其他5个组件）                                    │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │        双轨架构（认知模型的具体实现层）                    │  │
│  │  • 轨道A：语义桶提炼  • 轨道B：链提取  • 融合层          │  │
│  │  • 5种链类型：因果/逻辑/操作/叙事/时间                    │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  基础层：存储层                                 │
│  • ShortTermMemory  • LongTermMemory  • MemoryIndexer          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  底层：基础设施层                               │
│  • type_defs  • encryption  • privacy  • monitoring            │
└─────────────────────────────────────────────────────────────────┘

ContextOrchestrator 是系统的总控中心和统一入口（顶层），负责：

• Token 预算管理
• 检索决策
• 多源协调（认知模型、双轨、存储层）
• 结果压缩
• 全局调度

认知模型层是协调层的核心（中间层），负责：

• 认知模型构建
• 链提取（5种）
• 知识缺口识别
• 检索决策
• 状态推理

双轨架构是协调层的子层（中间层），为认知模型层提供技术实现：

• 轨道A：语义桶提炼
• 轨道B：链提取（因果/逻辑/操作/叙事/时间）
• 融合层：关联、验证、摘要

详见：架构总览、双轨架构总览

前置准备

依赖安装

pip install pydantic>=2.0.0 typing-extensions>=4.0.0 cryptography>=41.0.0 redis>=4.5.0 tiktoken>=0.5.0 mmh3>=3.0.0

存储路径配置

所有模块初始化时必须指定存储路径：

base_path = "./memory_data"
key_storage_path = f"{base_path}/keys"
sync_state_path = f"{base_path}/sync_state"
index_storage_path = f"{base_path}/memory_index"
credential_path = f"{base_path}/credentials"

Redis 连接（可选，推荐）

from scripts import create_redis_adapter

redis_adapter = create_redis_adapter(host="localhost", port=6379)
if redis_adapter.is_available():
    print("Redis 连接成功")

核心流程

1. 隐私配置（必需）

from scripts import PrivacyManager, ConsentStatus

privacy_manager = PrivacyManager(user_id="user_123")

# 检查隐私同意状态
status = privacy_manager.get_consent_status("memory_storage")

if status != ConsentStatus.GRANTED:
    # 创建同意请求（返回 PENDING 状态的记录）
    record = privacy_manager.request_consent(
        consent_type="memory_storage",
        description="是否允许存储交互记忆？"
    )

    # 智能体负责向用户呈现描述信息并获取同意
    # 例如：向用户展示 "是否允许存储交互记忆？"
    # 如果用户同意，调用以下方法授予同意：
    # privacy_manager.grant_consent(record.consent_id)

    # 注意：request_consent() 不会弹窗，智能体需要负责与用户交互

2. 初始化核心模块

from scripts import (
    PerceptionMemoryStore,
    ShortTermMemoryManager,
    LongTermMemoryManager,
    ContextReconstructor,
)

perception = PerceptionMemoryStore()
short_term = ShortTermMemoryManager()
long_term = LongTermMemoryManager()
reconstructor = ContextReconstructor()

3. 处理对话

# 创建会话
session_id = perception.create_session()
perception.store_conversation(session_id, user_message, system_response)

# 短期记忆
from scripts import SemanticBucketType
short_term.store_with_semantics(
    user_message,
    SemanticBucketType.USER_INTENT,
    "话题",
    0.8
)

4. 上下文重构

context = reconstructor.reconstruct(situation, long_term.get_all_memories())

5. 使用统一入口（推荐）

from scripts import create_context_orchestrator

orchestrator = create_context_orchestrator(
    user_id="user_123",
    session_id="session_456",
    max_context_tokens=32000,
)

# 准备上下文
prepared = orchestrator.prepare_context(
    user_input="用户输入",
    system_instruction="系统指令",
)

重要说明：ContextOrchestrator 是系统的总控中心和统一入口（顶层），负责协调所有层级的执行。推荐始终使用 ContextOrchestrator 而非直接调用内部模块。

高级功能

上下文压缩

本系统提供完整的上下文压缩能力，支持 5 种压缩策略和自动压缩。

# 启用上下文压缩
orchestrator.enable_context_compression(
    enable_auto_compress=True,
    auto_compress_threshold=0.8,
    default_strategy="priority_based",
)

# 手动压缩
compressed_blocks = orchestrator.compress_context(
    blocks=blocks,
    compression_ratio=0.7,
    strategy="priority_based"
)

详细说明：上下文压缩 API、压缩规则

质量评估与监控

本系统提供完整的 metadata 质量评估、自定义类型生命周期管理和使用监控能力。

# 启用质量评估
orchestrator.enable_quality_assessment(
    storage_path="usage_stats.json",
    enable_monitoring=True,
)

# 评估 metadata 质量
assessment = orchestrator.assess_metadata_quality(metadata, ContextSource.CUSTOM)
print(f"质量评分: {assessment.score}")

详细说明：质量评估与监控 API

上下文类型扩展

本系统支持通过 混合方案 处理已知和未知类型的上下文信息：

• 已知类型：使用标准来源 + subtype 字段
• 未知类型：使用 CUSTOM 来源 + custom_type 字段

# 注册自定义类型
orchestrator.register_custom_type(
    custom_type="workflow_step",
    priority=ContextPriority.HIGH,
    required_fields=["step_id", "status"]
)

详细说明：上下文类型扩展

错误处理与纠正机制

本系统内置错误处理和纠正机制，支持 Agent 工具调用的可靠性规范。

详细说明：工具调用可靠性规则

注意事项

1. 路径必传：所有存储路径无默认值，必须显式传入
2. 隐私优先：处理用户数据前必须初始化 PrivacyManager 并获取同意
3. 敏感数据：系统自动识别密码、账号等敏感信息，默认不存储
4. 类型安全：所有函数必须有类型注解，禁止使用裸 dict
5. 异步优先：提炼、热度计算等后台异步执行
6. 降级策略：模块故障时自动降级，保证核心流程可用
7. 统一入口：推荐使用 ContextOrchestrator 作为统一入口，避免直接调用内部模块
8. Skill 定位：本 Skill 是能力扩展包，由智能体动态加载，非独立应用
9. 隐私同意流程：request_consent() 不会弹窗，智能体需要负责向用户呈现描述信息并调用 grant_consent() 授予同意

常见问题

Q: 如何选择存储方案？

A:

• 文件存储：默认方案，适合大多数场景，无需额外依赖
• Redis 存储：高性能场景，需要部署 Redis 服务器

Q: 如何优化 Token 使用？

A: 使用 ContextOrchestrator 自动管理 Token 预算，系统会智能压缩和筛选内容。

Q: 如何处理记忆冲突？

A: 系统自动检测和解决冲突，无需手动处理。ContextOrchestrator 内置冲突解决机制。

Q: 如何导出和导入记忆数据？

A: 使用 LongTermMemoryManager 的 export() 和 import() 方法。

Q: 如何监控记忆系统性能？

A: 系统内置监控能力，可通过 ContextOrchestrator 获取性能统计信息。

Q: Skill 如何运行？

A: 本 Skill 是智能体的能力扩展包，由智能体动态加载和执行。不需要独立启动服务器或监听端口。所有交互通过智能体与用户的对话完成。

详见 architecture_execution_model.md。

资源索引

参考文档

核心模块

本系统包含 67 个脚本模块，按四层架构分类为总控层、协调层、存储层、基础设施层。

查看完整模块索引：详见 module_index.md（包含所有 67 个模块的详细信息、用途和使用建议）

阶段实施总结

本 Skill 采用四层架构，分阶段实施：

• 阶段 1：基础架构（CUSTOM 枚举值、MetadataValidator、PriorityResolver）
• 阶段 2：高级功能（自定义类型注册、动态优先级规则、批量解析、缓存机制）
• 阶段 3：质量评估与生命周期管理（MetadataQualityAssessor、CustomTypeLifecycleManager、UsageMonitor、QualityReportGenerator）
• 阶段 4：性能优化（LRUCache、PerformanceMonitor、BatchProcessor）
• 阶段 5.1：上下文压缩（ContextCompressor、CompressionStrategy、/compact 命令、自动压缩）
• 阶段 5.2：链感知压缩（链元数据增强、CHAIN_AWARE 压缩策略、链类型权重配置）
• 阶段 6：双轨架构（协调层子层，为认知模型层提供技术实现）
  • 轨道A：语义桶提炼
  • 轨道B：链提取（5种链类型：因果/逻辑/操作/叙事/时间）
  • 融合层：关联、验证、摘要
  • 触发器：协同提取触发
• 阶段 7：四层架构澄清与文档完善
  • 明确ContextOrchestrator为顶层总控中心和统一入口
  • 明确认知模型层为协调层核心业务逻辑
  • 明确双轨架构为协调层子层，为认知模型层提供技术实现
  • 完善架构总览、API参考文档、双轨架构文档
• 阶段 8：文档完善（API 参考文档、最佳实践、故障排查指南、上下文压缩规则、链感知压缩文档）

性能特性

• LRU 缓存：优先级解析缓存，提升 40x 性能
• 批量处理：优化的批量验证、解析、评估
• 性能监控：实时监控操作延迟、吞吐量、缓存命中率
• 上下文压缩：减少 token 数量，提升上下文利用率

质量保证

• 质量评估：多维度评分（完整性、准确性、一致性、实用性）
• 生命周期管理：自定义类型的创建、使用、废弃、清理
• 使用监控：统计 metadata 使用情况，生成改进建议
• 压缩质量：压缩质量评分，确保关键内容不丢失