feat(examples): add Codex memory plugin example

[0xble]

Description

Add a Codex memory plugin example for OpenViking that follows the same product
model as the Claude and OpenClaw integrations:

• transparent recall on UserPromptSubmit
• transparent capture on Stop
• optional manual MCP tools for explicit OpenViking control

The example stays isolated under examples/ and includes the practical hook
installer and runtime bootstrap needed for Codex today.

Related Issue

N/A

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• Add a real examples/codex-memory-plugin bundle with .codex-plugin/plugin.json, .mcp.json, hooks/, scripts/, TypeScript source, and built server output.
• Make transparent memory the default path with UserPromptSubmit recall and Stop capture instead of an MCP-only workflow.
• Rename the explicit manual tools to openviking_recall, openviking_store, openviking_forget, and openviking_health to make the OpenViking boundary explicit.
• Add full and recall_only modes so the plugin can either own live capture or act as a recall-only layer on top of an existing OpenViking deployment.
• Add plugin-side idempotency for duplicate Codex hook delivery so repeated hook invocation becomes a no-op instead of causing duplicate recall/capture side effects.
• Expand the README with architecture, config, flow diagram, verification steps, limitations, and troubleshooting.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

Manual validation performed on macOS:

cd examples/codex-memory-plugin
npm ci
npm run build
npm run install:hooks

Hook-first end-to-end validation was exercised with fresh Codex sessions
against a running local OpenViking server:

codex --no-alt-screen -C /tmp

Session 1:

Do not use any tools. Just reply directly. For future reference, my weird constellation codeword is [UNIQUE_TOKEN]. Respond in one short sentence.

Session 2:

Do not use any tools. Just answer directly: what is my weird constellation codeword?

Observed result:

• the second fresh session answered the exact stored token directly

Additional macOS validation covered:

• optional manual MCP tool path via openviking_health, openviking_recall, openviking_store, and openviking_forget
• recall_only mode behavior, including Stop hook removal and manual store/delete rejection
• duplicate hook delivery idempotency so repeated deliveries do not duplicate plugin side effects

No automated tests were added for this example because the repository does not currently provide a stable CI harness that can authenticate Codex, install hooks into a temporary Codex home, and exercise stdio MCP plus hook-driven behavior end to end. This PR uses execution-backed manual validation instead.

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

A full terminal demo video was recorded for the hook-first Codex flow on macOS:

https://screen.studio/share/xGfDrJQG

Additional Notes

• This example is intentionally plugin-first: transparent recall/capture is the default path, while manual MCP tools are optional.
• Codex still requires explicit hook installation via ~/.codex/hooks.json in this flow; the plugin manifest alone does not install lifecycle hooks yet.
• Codex still shows generic hook start/completion rows in the TUI. The example removes plugin-branded labels and raw memory dumps, but that remaining UI behavior is a Codex limitation rather than an OpenViking plugin choice.
• The example is compatible with Codex native memory remaining enabled. The intended boundary is Codex native memory for local implicit adaptation and OpenViking for explicit long-term memory plus transparent hook-driven recall/capture.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[github-actions]

Failed to generate code suggestions for PR

[qin-ctx]

Thanks for the contribution. Before this is merged, could you please supplement a few reviewer-facing details so the example is easier to verify end to end?

• Runtime verification: the current PR body shows npm ci and npm run build, which confirms install/build, but not that the MCP server actually ran successfully with Codex. Please add the exact manual verification you performed end to end against a running OpenViking server.
• Functional status: please state clearly whether memory_recall, memory_store, memory_forget, and memory_health were all exercised successfully on macOS, and whether there are any known limitations or untested paths.
• Screenshots / terminal captures: since this is an integration example, a short terminal capture or screenshot showing codex mcp add, the server starting, and at least one successful tool invocation would make review much easier.
• Testing note: if no automated tests are being added for this example, please explicitly explain why, and what manual validation is being used instead.
• Flow / design diagram: the README already describes the recall feedback sequence. Please add a small flow or sequence diagram showing Codex -> MCP server -> OpenViking, especially the async used() / commit() path, so reviewers can understand the interaction model quickly.

That additional context would make the feature much easier to review and validate.

[0xble]

Thanks for the contribution. Before this is merged, could you please supplement a few reviewer-facing details so the example is easier to verify end to end?

• Runtime verification: the current PR body shows npm ci and npm run build, which confirms install/build, but not that the MCP server actually ran successfully with Codex. Please add the exact manual verification you performed end to end against a running OpenViking server.
• Functional status: please state clearly whether memory_recall, memory_store, memory_forget, and memory_health were all exercised successfully on macOS, and whether there are any known limitations or untested paths.
• Screenshots / terminal captures: since this is an integration example, a short terminal capture or screenshot showing codex mcp add, the server starting, and at least one successful tool invocation would make review much easier.
• Testing note: if no automated tests are being added for this example, please explicitly explain why, and what manual validation is being used instead.
• Flow / design diagram: the README already describes the recall feedback sequence. Please add a small flow or sequence diagram showing Codex -> MCP server -> OpenViking, especially the async used() / commit() path, so reviewers can understand the interaction model quickly.

That additional context would make the feature much easier to review and validate.

Thanks, that makes sense. I’ll add the missing reviewer-facing validation context up next

[0xble]

I just updated the PR to address the reviewer-facing gaps you called out

A few implementation details changed since the original PR, so one clarification up front: this is no longer just an MCP-only example. Because Codex’s practical integration point for “memory that just works” is lifecycle hooks, the example evolved from a manual MCP demo into a hook-first plugin flow, with MCP tools kept as the explicit control layer

The default path is now:

• transparent recall on UserPromptSubmit
• transparent capture on Stop
• optional manual OpenViking MCP tools

I also renamed the explicit manual tools to make the boundary clearer:

• openviking_recall
• openviking_store
• openviking_forget
• openviking_health

What was added or clarified:

• Runtime verification:

  • The PR body now includes the actual end-to-end macOS verification flow against a running local OpenViking server, not just npm ci / npm run build.
  • This includes a fresh-session hook-first store + fresh-session recall flow in Codex itself.

• Functional status:

  • The PR body now states the macOS validation that was exercised.
  • The explicit manual tool path was also exercised on macOS.
  • Known limitations and current setup constraints are called out in the PR body and README.

• Screenshots / terminal capture:

  • Full demo video attached in the PR conversation.
  • It shows the hook-first Codex flow end to end on macOS.

• Testing note:

  • The PR body now explains why no automated tests were added for this example.
  • In short, the repo does not currently provide a stable CI harness for authenticating Codex, installing hooks into a temporary Codex home, and exercising stdio MCP plus hook-driven behavior end to end, so this example uses execution-backed manual validation instead.

• Flow / design diagram:

  • The README now includes a sequence diagram covering Codex -> hooks / optional MCP server -> OpenViking, including the async used() / commit() feedback path.

Two current limitations are also stated explicitly:

• Codex still requires explicit hook installation via ~/.codex/hooks.json in this flow.
• Codex still shows generic hook start/completion rows in the TUI, even though the example now avoids plugin-branded labels and raw memory dumps.

[0xble]

Recorded a demo video here: https://screen.studio/share/xGfDrJQG