Add optional Codex adapter

[SiyaoZheng]

Description | 描述

This PR proposes an optional Codex adapter for TencentDB Agent Memory, supporting both Codex CLI and Codex App. It is more than a Codex manifest: it wires Codex hooks, MCP tools, JSONL history, and context injection into the shared Gateway/Core pipeline, keeps Codex-specific state under codex-plugin/, and leaves the existing OpenClaw and Hermes loading paths unchanged.

The main contribution is a complete Codex memory path around the existing four-layer memory system:

• Codex lifecycle coverage: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, PreCompact, PostCompact, and Stop hook handlers for recall, capture, tool/permission activity, compaction safety, and periodic flushes.
• Codex CLI and App packaging: a Codex plugin manifest, bundled hook config, bundled MCP config, CLI-compatible user-level hook fallback, and documented local-development registration path.
• Codex App adaptation and validation: App-session and archived JSONL import, plugin-cache loading behavior, App-observed hook execution, and real Codex App / local Codex history validation.
• Active recall and capture resilience: bounded additionalContext injection, injected-memory tag cleanup before persistence, pending-turn preservation when capture fails, project-scoped session-key prefixes, and local L0 JSONL fallback when the Gateway is unavailable or returns no useful context.
• Short-term context offload: large PostToolUse results are redacted, stored under local JSONL/ref/Mermaid artifacts, replaced with compact hook feedback, and retrievable through tdai_offload_lookup or the CLI.
• Historical onboarding: a Codex JSONL importer converts active and archived ~/.codex sessions into Gateway /seed input, supports dry-run/cwd/time filters, and can wait for the full L0 -> L1 -> L2 -> L3 pipeline.
• Model-facing retrieval tools: MCP tools for scoped L1 memory search, L0 conversation search, and offload lookup, with cross-project search and exact offload content disabled unless explicitly enabled outside the model context.
• Host-neutral Gateway/seed support: tdai-memory-gateway package bin, token-file auth, root/health endpoint support, optional started_at metadata, session-prefix search filtering, opt-in full-pipeline /seed waiting, and a prepack-safe optional script build path.
• Security and operability hardening: loopback-first Gateway policy, bearer auth, private token/state/offload files, atomic generated-token creation under concurrent autostart, redacted hook.log diagnostics, non-loopback request refusal by default, blocked credential-bearing /seed config_override keys, symlink-safe standalone file tools, and secure TLS defaults.

I am happy to split the Gateway/seed/security support from the Codex adapter files if that would make review easier.

Related Issue | 关联 Issue

Related to #5 and #6.

Change Type | 修改类型

• Bug fix | Bug 修复
• New feature | 新功能
• Documentation update | 文档更新
• Code optimization | 代码优化

Self-test Checklist | 自测清单

• Verified locally | 本地验证通过
• No existing features affected | 无影响现有功能
• npm test -> 4 files / 30 tests passed
• find codex-plugin/scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
• git diff --check
• npm run build:plugin
• npm pack --dry-run --json runs prepack, includes dist/src/gateway/cli.mjs, codex-plugin/.codex-plugin/plugin.json, codex-plugin/.mcp.json, codex-plugin/hooks/hooks.codex.json, and codex-plugin/scripts/mcp-server.mjs, and excludes Codex test files
• Codex CLI smoke: codex exec --json in this repo returned the expected response and created a captured Codex session with l0_recorded: 2
• Gateway CLI smoke: dist/src/gateway/cli.mjs starts with token-file auth and /health returns 200
• Gateway CLI tilde token-path smoke: TDAI_TOKEN_PATH=~/... expands consistently for adapter and spawned Gateway env
• Concurrent token smoke: generated Gateway token file is created atomically and reused across concurrent autostarts
• Gateway security smoke: unauthenticated tokenized request -> 401, authenticated -> 200, disallowed CORS origin -> 403, credential-bearing /seed config_override.llm.baseUrl -> 400, tokenless loopback POST -> 401 by default, explicit loopback dev opt-in reaches route validation
• MCP smoke: default model-facing schema exposes scoped tools only; cross-project and exact offload content require explicit env opt-in
• Scoped search regression: current-project results still return when 700 other-project candidates precede them
• Diagnostics regression: hook failures append redacted entries to private hook.log and query status reports log paths
• Privacy scan over the working tree found no sensitive private wording
• npm view @tencentdb-agent-memory/memory-tencentdb@0.3.4 bin checked; default package-bin launch no longer pins to a published version without tdai-memory-gateway

Additional Notes | 其他说明

Maintainer Review Checklist | 维护者评审确认

• External scan passes: GITHUB_OPENSOURCE_SCAN_PIPELINE is passing on head commit dafe266bc1aa966563431c041974b555f33aa8c1.
• GitHub Actions CI is fork-gated and currently awaits maintainer approval; the equivalent local checks are listed above to avoid asking maintainers to approve repeated exploratory runs.
• DCO is complete: this PR is a single commit and includes Signed-off-by: Siyao Zheng <zhengsy24@sjtu.edu.cn>.
• Codex host testing is documented: the checklist above includes Codex CLI smoke, Codex App/local history validation, bundled MCP packaging, Gateway smokes, security smokes, and package dry-run verification.

Relation to PR #7 | 与 PR #7 的关系

Thank you to the author of #7 for pushing the host-adapter direction forward. It may be useful to review this PR alongside #7 because the two PRs intentionally overlap in Gateway, daemon, auth, and packaging concerns while targeting different host surfaces.

#7 is valuable Claude Code + Codex CLI plugin work: it adds dual manifests, a shared hook path, daemon/token handling, manual memory skills, and a useful test baseline. This PR is complementary rather than a replacement: it contributes a fuller Codex adapter that covers Codex CLI and Codex App, with additional Codex App adaptation and validation.

The practical difference is the Codex feature surface covered here. This PR implements Codex lifecycle and retrieval paths that are not covered by #7's current scope, including tool and permission hooks, compact hooks, bundled MCP tools, large tool-output offload/lookup, local L0 fallback, Codex JSONL importer, scoped offload lookup, injected-memory cleanup, and defensive Gateway/security/packaging checks.

To reduce duplicate review effort, this PR also incorporates compatible host-neutral pieces in the same spirit: the tdai-memory-gateway package bin, bearer token-file handling, Gateway auth/CORS hardening, packaging fixes, and targeted tests. I am happy to rebase on #7, split this into smaller PRs, or fold the Codex-specific pieces into a combined host-plugin structure if maintainers prefer that path.

Security posture | 安全边界

The intent is balanced local-agent security rather than maximum lock-down:

• tokenless Gateway access exposes loopback GET probes only by default; loopback tokenless POST requires explicit development opt-in;
• non-loopback Gateway access requires explicit opt-in and bearer auth;
• Codex adapter requests refuse non-loopback Gateway URLs unless explicitly allowed;
• token files are private, owner-checked, and fail closed if configured but unreadable or empty;
• generated Gateway token files are atomically created and reused under concurrent autostart;
• hook diagnostics are written to a private hook.log after redaction;
• MCP defaults are project-scoped and do not expose cross-project or exact offload content unless enabled outside the model context;
• adapter state/offload files are private on POSIX filesystems;
• file-tool sandboxing rejects symlink escapes, including existing file symlinks;
• offload/backend TLS verification is secure by default.

DCO

Single commit, signed off as:

Signed-off-by: Siyao Zheng <zhengsy24@sjtu.edu.cn>