Adapte Codex and Claude Code (腾讯犀牛鸟开源)

[soongao]

关联 Issue

Part of #235

概述

本 PR 新增 Codex 与 Claude Code Plugin适配。

实现前先拆解了现有 Memory Core/Gateway、OpenClaw、Hermes 的接入路径，并基于平台差异做了适配层拆分：

• MCP 作为 agent 查询面。
• CLI 作为生命周期能力层。
• hooks 作为平台事件触发点。
• Codex/Claude Code 各自通过 plugin、skill、CLAUDE.md/AGENTS.md和安装脚本接入现有 Gateway 能力。

主要改动

• 新增共用 MCP server：packages/tdai-memory-mcp

  • 暴露 tdai_memory_search 和 tdai_conversation_search。
  • 不暴露 health、capture、session-start、sync-turn、end-session 等生命周期能力。

• 新增共用 CLI 能力层：packages/tdai-memory-cli

  • 提供 session-start、prefetch、sync-turn、end-session。
  • 负责 Gateway 自动启动、hook stdin 解析、hook log、heartbeat 和 idle watchdog。
  • hooks 只负责在平台事件中触发 CLI，不承载记忆业务逻辑。

• 新增 Codex plugin：plugins/tdai-memory

  • 包含 .codex-plugin/plugin.json、.mcp.json、hooks/hooks.json、skills/tdai-memory/SKILL.md。
  • scripts/install-codex.sh 负责安装共用包、注册 plugin/MCP、写 Gateway 配置和 ~/.codex/AGENTS.md。

• 新增 Claude Code plugin：plugins/tdai-memory-claude-code

  • 包含 .claude-plugin/plugin.json、.mcp.json、hooks/hooks.json、skills/tdai-memory/SKILL.md。
  • scripts/install-claude-code.sh 负责安装共用包、写 Gateway 配置和 ~/.claude/CLAUDE.md。

• 新增 Rhino-Bird 文档

  • 记录源码阅读、平台适配对比、数据流、调试路径和验证方式。

设计说明

模块	职责
MCP	只负责 agent 主动查询长期记忆。
CLI	提供 Gateway 启动、prefetch、turn capture、session flush 等生命周期能力。
hooks	平台事件触发点，在 SessionStart、UserPromptSubmit、Stop 等事件中调用 CLI。
skill	告诉 agent 何时使用 MCP 查询记忆，避免把生命周期 CLI 当作查询工具。
AGENTS.md	Codex 静态 memory guide，不写动态召回结果。
CLAUDE.md	Claude Code 静态 memory guide，不写动态召回结果。

Gateway 作为旁路进程运行，session end 只 flush 当前 session，不等于关闭 Gateway。

自测清单

检查项	Codex	Claude Code	预期结果
安装脚本执行	scripts/install-codex.sh	scripts/install-claude-code.sh	脚本可重复执行，不破坏已有配置。
静态提示文件	~/.codex/AGENTS.md	~/.claude/CLAUDE.md	TDAI 标记块存在，内容为静态 memory guide。
Gateway 配置	~/.codex/tdai-memory/tdai-gateway.yaml	~/.claude/tdai-memory/tdai-gateway.yaml	配置文件存在，data dir 指向用户目录。
MCP 注册	Codex MCP 配置	Claude Code MCP 配置	平台能加载 tdai-memory-mcp。
MCP tools 列表	tdai_memory_search, tdai_conversation_search	tdai_memory_search, tdai_conversation_search	只暴露两个查询工具，不暴露 lifecycle 操作。
hooks 配置	plugins/tdai-memory/hooks/hooks.json	plugins/tdai-memory-claude-code/hooks/hooks.json	SessionStart、UserPromptSubmit、Stop 分别调用对应 hook wrapper。
Gateway 自动启动	触发 SessionStart 或 MCP 调用	触发 SessionStart 或 MCP 调用	Gateway health 返回 ok 或 degraded。
prefetch 触发	用户提交 prompt	用户提交 prompt	hook log 出现 prefetch prepared/completed。
sync-turn 触发	turn 结束	turn 结束	hook log 出现 sync-turn prepared/completed。
L0 捕获	~/.codex/tdai-memory/data/conversations	~/.claude/tdai-memory/data/conversations	JSONL 中出现 user/assistant turn。
L1 抽取	MCP search 或 records/*.jsonl	MCP search 或 records/*.jsonl	能查到结构化长期记忆。
L2 场景块	scene_blocks/*.md	scene_blocks/*.md	触发后生成或日志说明跳过原因。
L3 用户画像	persona.md	persona.md	触发后更新或日志说明跳过原因。
空闲关闭	idle watchdog	idle watchdog	超过 idle timeout 后关闭 hook 启动的 Gateway。
旁路能力隔离	MCP tools/list	MCP tools/list	health/capture/session-start/sync-turn/end-session 不出现在 agent tool 列表。
原有平台回归	OpenClaw/Hermes 基础链路	OpenClaw/Hermes 基础链路	本 PR 不改变既有 OpenClaw/Hermes 行为。

单元测试记录

已在本地执行与本次改动相关的 Python unit tests：

测试范围	命令	结果
MCP server unit tests	python3 -m pytest packages/tdai-memory-mcp/tests/unit -q	18 passed in 0.03s
CLI/hooks unit tests	python3 -m pytest packages/tdai-memory-cli/tests/unit -q	19 passed in 0.09s

本次单测覆盖 MCP protocol/tools/session config/supervisor/side-channel，以及 CLI、hook parsing、Gateway HTTP/start/watchdog/session config 等适配层逻辑。

[soongao]

补充说明：本次在已有 PR 上追加 SDK adapter 相关改动。

范围：

• 新增 packages/tdai-memory-agent-sdk/
• 覆盖 Codex SDK / Claude Code SDK adapter 示例与测试
• 不修改顶层 src/ 下的 gateway/core 代码

验证：

• npm run typecheck
• npm run build
• npm test

真实 Codex SDK 场景已跑通，并在用户目录生成文件：

• ~/.tdai-memory/codex-sdk/data/conversations/2026-07-04.jsonl
• ~/.tdai-memory/codex-sdk/data/records/2026-07-04.jsonl
• ~/.tdai-memory/codex-sdk/data/scene_blocks/Engineering-Practice-TencentDB-Agent.md

[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! 🚀