feat(adapters): 跨平台记忆适配器 — Claude Code / Codex / Dify (#235)

[Elyxiya]

描述

本 PR 实现了 Issue #235 所要求的跨平台记忆适配器，为 TencentDB-Agent-Memory 核心记忆引擎提供了统一的多平台接入能力。

核心交付物

1. 统一适配器 SDK（TypeScript + Python 双语言）

• MemoryAdapterBase 抽象基类：封装全部 Gateway 通信、熔断器（5 次连续失败 / 60 秒冷却）、健康检查和优雅降级
• MemoryGatewayClient：HTTP v3 API 客户端，支持 L0/L1/L2/L3 四层记忆操作
• 平台只需实现 4 个抽象方法即可完成接入

2. Claude Code 适配器（MCP Server）

• 基于 stdio 的 JSON-RPC 2.0 协议，无需外部 MCP SDK 依赖
• XML 标签格式的上下文注入（<relevant-memories>、<user-persona>、<scene-navigation>）
• 支持 tools/list 和 tools/call 方法，暴露 3 个记忆工具

3. Codex CLI 适配器

• 生命周期 Hook 模型（beforePromptBuild、afterResponse、onToolCall）
• Markdown 格式的上下文注入，适配 OpenAI function-calling 工具格式
• 提供工厂函数 createCodexAdapter() / createCodexHooks()

4. Dify 适配器（Python 插件）

• XML 标签格式的上下文注入，适配 Dify 的 Prompt 模板
• 支持 Dify 凭证系统（self.runtime.credentials 覆盖环境变量）
• 双语（中/英）工具 YAML Schema
• 支持多种消息格式（{query, answer} 对、{role, content} 列表、纯字符串）

设计亮点

特性	说明
4 方法合约	每个平台仅需实现 formatRecallResult、getToolDefinitions、formatToolResult、normalizeMessages
熔断器	5 次连续失败后暂停调用 60 秒，之后自动半开探测
优雅降级	所有方法在失败时返回空结果而非抛出异常，宿主 Agent 永不崩溃
并行召回	recall 操作并行获取 L1 + L3 + L2，最小化延迟
双语 SDK	TypeScript（Claude Code / Codex / OpenClaw）和 Python（Dify / Hermes）共享相同接口契约

测试

• 82 个 TypeScript 测试全部通过（Vitest）
• 36 个 Python 测试全部通过（pytest）
• 覆盖范围：4 个抽象方法格式化、消息归一化、熔断器常量、环境变量配置、凭证配置、优雅降级行为

# TypeScript 测试
npx vitest run src/adapters/claude-code/adapter.test.ts \
  src/adapters/codex/codex-adapter.test.ts \
  src/adapters/sdk/base-adapter.test.ts
# 结果：82 passed (82)

# Python 测试
cd MemoryCore/dify-plugin && python -m pytest test_provider.py -v
# 结果：36 passed

文档

• docs/architecture.md：完整架构图（Mermaid），包含高层架构、四层记忆模型、类层次结构、召回/捕获数据流、熔断器状态机
• docs/adaptation-guide.md：新平台适配指南，含 TypeScript 和 Python 逐步教程、测试骨架、常见陷阱
• docs/platform-comparison.md：平台对比矩阵，含召回格式、消息归一化、工具定义、配置、性能特征对比

关联 Issue

Fix #235

修改类型

• New feature | 新功能
• Documentation update | 文档更新

自测清单

• Verified locally | 本地验证通过
• No existing features affected | 无影响现有功能

其他说明

文件清单

MemoryCore/src/adapters/
├── sdk/                          # 统一适配器 SDK（TypeScript）
│   ├── types.ts                  # 核心接口与数据类型
│   ├── gateway-client.ts         # v3 API HTTP 客户端
│   ├── base-adapter.ts           # MemoryAdapterBase 抽象基类
│   ├── base-adapter.test.ts      # SDK 基类测试
│   └── index.ts                  # Barrel 导出
├── claude-code/                  # Claude Code MCP 适配器
│   ├── adapter.ts                # ClaudeCodeAdapter + main()
│   ├── mcp-server.ts             # JSON-RPC 2.0 over stdio
│   ├── adapter.test.ts           # 适配器测试
│   ├── index.ts                  # Barrel 导出
│   └── README.md
├── codex/                        # Codex CLI 适配器
│   ├── codex-adapter.ts          # CodexAdapter + 工厂函数
│   ├── hooks.ts                  # CodexHooks 生命周期集成
│   ├── codex-adapter.test.ts     # 适配器测试
│   ├── index.ts                  # Barrel 导出
│   └── README.md
├── docs/                         # 架构文档
│   ├── architecture.md
│   ├── adaptation-guide.md
│   └── platform-comparison.md
└── index.ts                      # 顶层 Barrel（已更新）

MemoryCore/dify-plugin/           # Dify 插件（Python）
└── memory_tencentdb_dify/
    ├── types.py                  # Python 类型定义
    ├── gateway_client.py         # Python HTTP 客户端
    ├── base_adapter.py           # Python MemoryAdapterBase
    ├── provider.py               # Dify Provider + 工具定义
    └── __init__.py

[Maxwell-Code07]

Thank you for submitting this PR and participating in Tencent Rhino-bird Open-source Training Program!
We have successfully received your submission. The program is currently in full swing, and we will complete the Code Review for you as soon as possible. Please keep an eye on the status notifications for this PR so you can follow up promptly once the review feedback is provided.
Thanks again for your contribution and open-source spirit! 🚀