OpenViking Memory Hooks for TRAE CLI

Deprecated. TraeCode CLI 2.0 supports Codex-format plugins directly. New installations use examples/codex-memory-plugin through the trae-cli command alias, so this adapter is retained only for compatibility tests and removal of existing managed installations.

This directory provides the TRAE CLI lifecycle adapter for OpenViking memory: three lifecycle hooks, a PreToolUse URI guard, and the openviking-memory MCP server.

Installation

Install the supported TraeCode CLI 2.0 plugin through the shared installer:

bash examples/memory-plugin-shared/install.sh --harness trae-cli

The installer keeps trae-cli as the user-facing harness name and resolves it internally to the Codex-format plugin installation. The deprecated component is this standalone Hooks adapter, not the trae-cli harness.

It no longer installs this adapter. The previous installer behavior was to:

• assemble the shared runtime under $OPENVIKING_HOME/agent-integrations/memory-plugin-shared/lib;
• install this adapter under $OPENVIKING_HOME/agent-integrations/trae-cli;
• merge hooks into ${TRAECLI_HOME:-${TRAE_HOME:-~/.trae}/cli}/hooks.json;
• register openviking-memory in ${TRAE_HOME:-~/.trae}/traecli.toml.

Uninstall with:

bash examples/memory-plugin-shared/install.sh --harness trae-cli --uninstall --yes

Hook and MCP Surface

The draft registers four hook events:

TRAE CLI lifecycle hooks do not use TRAE / TRAE CN's decision: "approve" output. No-op lifecycle hooks emit {}; context injection emits only hookSpecificOutput.hookEventName plus hookSpecificOutput.additionalContext. Tool-call allow/deny decisions belong to PreToolUse via hookSpecificOutput.permissionDecision, and permission approval belongs to PermissionRequest via hookSpecificOutput.decision.behavior.

The MCP server is named openviking-memory, matching the Codex memory plugin name. The package keeps the same .mcp.json source shape as the other native hook integrations; the shared installer writes the equivalent Node proxy entry into TRAE CLI's configured traecli.toml:

{
  "mcpServers": {
    "openviking-memory": {
      "command": "node",
      "args": ["servers/mcp-proxy.mjs"],
      "cwd": ".",
      "startup_timeout_sec": 30
    }
  }
}

Runtime Boundary

This package follows the same source layout as examples/trae-memory-hooks: the repository directory contains only TRAE CLI-specific adapters. The shared runtime is assembled by the installer at install time.

• examples/memory-plugin-shared/lib/agent-hook-runtime.mjs handles profile injection, recall, capture, commit, session state, locking, credential loading, and pending retry replay.
• examples/memory-plugin-shared/lib/mcp-proxy-core.mjs handles the stdio to OpenViking /mcp proxy.
• examples/memory-plugin-shared/lib/agent-uri-guard.mjs handles PreToolUse blocking when local file or shell tools receive viking:// virtual paths.

The source package intentionally does not carry a vendored lib/ directory. The installer should copy examples/trae-cli-memory-hooks into $OV_HOME/agent-integrations/trae-cli and assemble the shared runtime into $OV_HOME/agent-integrations/memory-plugin-shared/lib, matching the existing TRAE installation model.

What Is Not Reused From Codex

• Codex plugin marketplace metadata and install commands.
• Codex-specific ${PLUGIN_ROOT} substitution.
• Codex-specific PreCompact commit flow.
• Codex transcript JSONL parsing and cx-<session_id> session prefix.
• Codex local compressor startup detection.

Current Compatibility Notes

The three hook entries are intended to be reusable if TRAE CLI sends hook input JSON close to the existing thin harness conventions:

• Session identity: conversation_id, session_id, sessionId, or generation_id.
• Workspace: cwd, workspace_roots, or workspaceRoots.
• User prompt: prompt, user_prompt, userPrompt, message, or text.
• Assistant response on stop: last_assistant_message, lastAssistantMessage, assistant_message, assistantMessage, response, output, or text_content.
• Tool call: tool_name, toolName, name, or tool; input under tool_input, toolInput, input, or arguments.

The three lifecycle wrappers enter scripts/trae-cli-hook.mjs, a CLI-only adapter that uses the fixed trae-cli client id and trcli- OpenViking session prefix. It intentionally does not carry the TRAE / TRAE CN tr- and trcn- branches.

If TRAE CLI uses different field names, adapt scripts/trae-cli-hook.mjs or the local text cleanup / turn parsing in scripts/trae-cli-turns.mjs. The shared OpenViking runtime and MCP proxy can remain unchanged.

User-Level Install Shape

An installer should render hooks/hooks.json by replacing __OPENVIKING_TRAE_CLI_ROOT__ with this directory's absolute path, then merge the rendered hooks into the current TRAECLI_HOME/hooks.json. In the common local setup this is:

~/.trae/cli/hooks.json

TRAE CLI also supports hooks in the active traecli.toml under [hooks], but the source shown by the TUI /hooks command is the source of truth. Prefer the user-level hooks file when installing this integration so the setup is not tied to one workspace.

MCP should be added to the active traecli.toml under [mcp_servers."openviking-memory"]. Project-level MCP files such as <workspace>/.trae/.mcp.json or <workspace>/.trae/mcp.json are supported by TRAE CLI, but they are not the recommended target for this integration. Confirm the effective MCP source with /mcp or traecli mcp list.

If an existing OpenViking TRAE hook set is already installed, replace or disable the old OpenViking entries rather than adding this draft beside them. Running both will duplicate recall and capture.

The installer validates the installed hook entrypoints and MCP configuration. Use /hooks, /mcp, or traecli mcp list to inspect the effective runtime configuration.