* feat: add OpenViking memory integration for TRAE CLI
Add TRAE CLI lifecycle hooks and MCP proxy support, wire the integration into the shared installer, and cover idempotent install and uninstall behavior.
Co-authored-by: TRAE CLI <noreply@bytedance.com>
* fix(trae-cli): cover archive installs and hook payload aliases
* fix: keep TRAE CLI installation explicit
Leave TRAE Desktop detection unchanged and avoid auto-selecting TRAE CLI. TRAE CLI remains available through an explicit harness selection or --harness trae-cli.
Co-authored-by: TRAE CLI <noreply@bytedance.com>
* fix(trae-cli): auto-select installed CLI commands
Detect traecli and traex only when they are available in PATH, then mark and select the TRAE CLI harness automatically.
---------
Co-authored-by: “bianhaonan” <“bianhaonan@bytedance.com”>
Co-authored-by: TRAE CLI <noreply@bytedance.com>
* feat(plugins): add Agent Plugins 1.0 portable package
Add agent-plugins/, an Agent Plugins 1.0 conformant package
(https://agent-plugins.org/specification) that any conforming client can
load: plugin.json manifest, an openviking-memory skill teaching the
hook-less recall + persist loop, and an mcp.json stdio entry running a
stdio -> streamable-HTTP proxy that resolves credentials from
OPENVIKING_* env -> ~/.openviking/ovcli.conf -> ~/.openviking/ov.conf,
same as the ov CLI.
servers/shared/* are generated copies of memory-plugin-shared/lib, wired
into sync.mjs / sync.test.mjs TARGETS so they cannot drift silently.
config.mjs / debug-log.mjs / mcp-proxy.mjs are adapted from
claude-code-memory-plugin with the hook-tuning knobs dropped.
plugin.test.mjs validates spec conformance (schema URLs and matching
spec versions, name rules, closed manifest root, semver, skill
frontmatter, referenced files staying inside the plugin root, node
--check on all .mjs) and runs in CI via pr.yml.
The skill treats tree/write/edit as optional, since they only exist on
servers that carry #3936.
Docs: docs/{en,zh}/agent-integrations/15-agent-plugins.md, registered in
the VitePress sidebar and the integration overview tables, plus a link
from the three root READMEs. The docs recommend the per-client plugin
whenever the harness has hooks, with the shared installer one-liner.
Based on #3994 by @ZaynJarvis.
Co-Authored-By: Zayn Jarvis <zaynjarvis@gmail.com>
* docs(agent-plugins): pluralize README title
---------
Co-authored-by: Zayn Jarvis <zaynjarvis@gmail.com>
Coding-agent plugins capped a tool part's `tool_output` at 2000 chars before
POSTing it to `/api/v1/sessions/{id}/messages`. That cap sits below the server's
own externalization threshold (`tool_output_externalization.threshold_chars`,
default 20000), so output in the 2k-20k band was destroyed for no reason and
anything larger never reached `ToolResultStore` - leaving `tool_output_ref`
permanently empty and the `/tool-results` read-back path unusable.
Raise the `captureToolMaxChars` default to 1000000 (a guard against pathological
payloads, not a truncation policy) and lift the opencode/pi clamps that would
otherwise pin it back to 20000. claude-code had no knob at all - two hardcoded
`TOOL_OUTPUT_PART_MAX_CHARS = 2000` constants - so it gains the same config
entry and both capture scripts now read it.
Also stop pi from sending tool output twice: for a tool-only payload the
rawText-derived text part re-rendered the same output the tool part carries.
* fix(retrieval): honor tier ceilings and stop cooling unserved recalls
Follow-up to #3534, from its post-merge review round.
- The abstract-to-overview substitute now applies only to categories whose
stored abstract is the whole file body. A resource or skill whose abstract is
missing (`processing_mode=vectors_only`) or over the per-entry cap read its
body and returned an overview instead, which for a short file is the body
almost verbatim — crossing the opt-in deepening boundary those categories are
documented to have, and doing it even under an explicit `detail="abstract"`.
They now degrade to a bare URI and their body is never read.
- A digest reporting `no_relevant` blanks `rendered`, so the client injects
nothing, yet those URIs still entered the dedup ledger and were cooled for
`dedup_turns` turns. That contradicted the ledger's own bare-URI grace rule
and held memories back from the later turn they were relevant to.
- Flat retrieval reaches built-in memory types outside the four named ones
(`cases`, `patterns`, `tools`, `trajectories`, skill-usage memories) and
reported them as an undeclared `memories` category that no tier or penalty
table covered, so other-peer hits skipped the score penalty and callers could
not pin their tier. The catch-all is now a declared category with both; it
stays out of `quotas`, whose buckets it would overlap. Skill-usage memories
also stop being misread as the `skills` category.
- ZCode, OpenCode and pi own an OV session id but did not forward it, so their
recalls silently ran without query expansion or cross-turn dedup.
- The context-request deadline covered only the server's 30s rewrite fuse, but
the pipeline is serial: expansion, retrieval and budgeting all precede it.
45s covers both fuses and the work between them.
- `plugin` config scope and the `/recall` successor example now match what the
code actually does.
* fix(retrieval): make the context deadline and expansion opt-out reachable
Forwarding a session id turns on server-side query expansion, an LLM call with
its own 5s fuse, but neither the deadline that was supposed to cover it nor the
switch that turns it off reached the two harnesses this PR newly enabled it for.
- `contextRequestTimeoutMs()` now derives the deadline from the request body
rather than from `cfg` plus a rewrite flag. The body is what states which
server stages will run: a session takes the expansion fuse, `rewrite` takes
the digest fuse, and a bare retrieval takes neither and keeps the caller's own
budget. Reading `cfg` alone could not tell those apart.
- OpenCode pinned `timeoutMs: 5000` after spreading the helper's options and pi
ignored them entirely, so the helper's deadline was dead code in both. Their
own budgets are now defaults rather than ceilings. OpenCode's 5s in particular
was shorter than the expansion fuse it had just enabled, so a legal request
would have been aborted client-side and dropped back to the path with neither
dedup nor expansion.
- OpenCode and pi read `OPENVIKING_RECALL_QUERY_EXPANSION` (and
`recallQueryExpansion` in their own config files) and set the `configured`
flag the shared body builder requires, so the documented opt-out exists where
the cost was introduced.
- The integration overview no longer implies every harness reads the same
environment knobs, and describes the deadline as per-stage rather than
rewrite-only.
* feat(retrieval): assemble auto-recall context server-side via /search mode="context"
Auto-recall assembly lived in every harness plugin: each one searched per
memory type, read hits back one by one, and stitched a context block with its
own budget and degradation rules. The implementations drifted, and the shared
weaknesses showed up in production injections — roughly half of the entries
degraded to a bare URI plus a score, character budgets distorted up to 6x on
CJK text, and adjacent turns re-injected the same memories.
This moves assembly into the server as one round trip. /find stays an unchanged
stateless primitive. /search gains mode="context" (mode="list" is the default
and byte-identical to before), and /recall becomes a thin preset over the same
kernel with its v1 field names folded onto the new contract.
New assembly kernel under openviking/retrieve/context_assembler/:
- Token budgeting with a CJK-aware estimate replaces the character budget.
- detail="auto" fills breadth-first then deepens: every candidate gets a
readable floor, then overview, then full for high-scoring entries. An
oversized tier falls back to the previous one instead of being truncated,
bounded by max_tokens / candidates * 2 per entry.
- Overview extraction dispatches by source: memory files use their leading
Summary section, code files reuse code_outline signatures, long documents use
a heading tree plus first paragraph.
- Directory hits start at overview and read their .overview.md sidecar, since
directories carry no stored abstract; their full tier stays capped at
overview. v1 injected the sidecar as if it were a whole file.
- Quotas generalize beyond memory types to resources and skills, with purpose
presets supplying ratios when quotas are absent.
- dedup_turns keeps a per-session ledger at {session_uri}/.recall_log.json so
every harness inherits cross-turn dedup; exclude_uris remains as the
stateless fallback.
- Rendering flattens to one <memory uri=... type=... score=... detail=...>
element per entry. Every tier carries its URI, so the model can always drill
down through the MCP read tool.
- Query expansion and digest rewriting are opt-in and fail closed: both have
timeout fuses, and a failed rewrite still returns the unrewritten block.
Retrieval failures are counted into stats rather than silently yielding an
empty block.
Plugins now send one context request, falling back to /recall and then to raw
find on older deployments, and cache that outcome so only the first turn pays
for the probe. The tri-state recallRewrite knob chooses between local host-CLI
compression and the server digest, and client-side settings move to a plugin
section in ovcli.conf.
* refactor(retrieval): give context tiers a per-category default
The tier ladder assumed `abstract` is a cheap summary. For memory files it
is not: the memory writer stores the whole stripped body in that scalar
because it doubles as the embedding text, so `abstract` costs the same as
`full` and the ladder runs `uri < overview < abstract = full`. Two of the
model's properties fell out of that: exempting `abstract` from the per-entry
cap let a single entry eat several times the budget, and `detail` — which
only ever set a ceiling — collapsed to two distinguishable behaviours across
its four values, since `auto` already allowed `full` for memory.
Tiers now come from a per-category constant table that treats the storage
shape as a given: `events` starts at overview (the one memory type whose
`# Summary` extraction is a real compression) and may deepen to full on
leftover budget; every other category is served at `abstract`, which for
memory already is the complete file at zero read cost and for resources and
skills is the generated 256-char summary. The table carries the note to move
`events` back to `abstract` once the writer stores a separate summary scalar.
Falling out of that: prefetch now reads only the candidates whose planned
tier needs a body rather than every candidate, `detail` becomes a real pin
(start and ceiling) and additionally accepts a per-category map, and
`full_score_threshold` is gone — leftover budget is spent in score order
instead of behind an absolute threshold the observed score band cannot
support. `auto` is still accepted on the wire as a synonym for "unset".
Assembly fixes found alongside:
- Removing the abstract cap exemption would turn an oversized abstract into
a bare URI, so it now falls back to overview first — for memory that is a
cheaper substitute, not a step up.
- Rewrite timeouts were reported as failures on Python 3.10, where
`asyncio.TimeoutError` is a separate class from the builtin.
- `stats.rewrite_usage` read `token_tracker` off `VLMConfig`, which has no
such attribute; usage was structurally always null. It now reads the model
instance's tracker and reports only when the call count moved by exactly
one, since that tracker is shared.
- A single malformed ledger record made every deduped recall in that session
fail, and the file was never rewritten, so it could not heal. Records are
now coerced on read and dropped on the next write, along with records left
ahead of the clock by an archive rotation.
- Entries served as a bare URI no longer enter the dedup cooldown: they lost
to budget pressure, not to the reader having already seen them.
- The render envelope only neutralised a literal `</memory>`, so a body could
forge a sibling entry with its own uri, type and score.
- Flat-mode gathering re-derived the category from the URI, reading
`viking://resources/backup/memories/events/log.md` as an event.
- Cooled and excluded URIs are compensated with extra rows, so a fully cooled
bucket falls through to the next-best hits instead of coming back empty.
- `/recall` quotas overlay the v1 bucket defaults again; `{"events": 5}` had
started dropping the other three buckets.
- The MCP `recall` signature sent its own defaults as if the caller had, which
resolved a different profile than `POST /recall`; an unknown `detail` value
raised `KeyError` through the whole call instead of degrading.
* feat(codex): inject profile context on session start
Reuse the shared profile builder for startup, clear, and resume hooks while preserving archive injection and orphan-session status output.
Co-authored-by: TRAE CLI <noreply@bytedance.com>
* fix(retrieval): raise rewrite timeout default to 30s
* docs(agents): document low-latency recall settings
* fix(codex): prefer luna as recall compressor fallback
* refactor(plugins): unify recall compression setting
* feat(plugins): enable recall compression by default
* docs(agents): use absolute links in image docs
* fix(retrieval): address context assembly review feedback
Co-authored-by: TRAE CLI <noreply@bytedance.com>
* test: trim redundant context assembly coverage
* fix(retrieval): address second-round context assembly review
- Drop the backticked `/search` from the deprecated-recall row in both API
overviews. The reference checker scans the whole row after the method cell
for backticked paths, so it read the description as a route named
`POST /search` and Build Docs failed on an unknown, undocumented route.
- Accept ovcli.conf's full field set in both Python readers. The file's schema
belongs to the Rust CLI, which writes `root_api_key`, `output`,
`echo_command`, `show_progress` and `verbose` and ignores unknown keys; the
two Python readers had drifted into stricter subsets, so the shipped example
already failed to load in both. Adding the new `plugin` section to a working
ovcli.conf would have broken `ov doctor` and every SDK client the same way.
- Return 400 from `mode="context"` for a request `mode="list"` also rejects.
Retrieval validates query and image_url before searching, and the gather
fuse swallowed that rejection along with genuine scope failures, so a body
of `{"mode":"context"}` came back 200 with an empty block instead of the
documented parameter error. Runtime failures still degrade into
`stats.retrieval_errors`.
- Let a context request that asks for a server-side digest outlast the
server's rewrite fuse. The plugin's ordinary 15s request timeout is shorter
than the 30s fuse, so a rewrite that finished inside its own budget was
aborted client-side, discarding the whole response — including the
uncompressed block the server returns when a rewrite fails — and falling
back to `/recall`. The deadline is only extended when the body actually
requests a rewrite, and `OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS` /
`plugin.recallContextTimeoutMs` pins it.
* chore(plugins): sync shared modules into the zcode snapshot
* fix(retrieval): align context quotas and plugin defaults
Restore cross-domain coding recall, reuse authoritative actor resource
scopes, and make bucket quotas the sole width control in purpose mode.
Keep plugin defaults server-owned while preserving explicit legacy limit
settings through quota conversion.
Co-authored-by: TRAE CLI <noreply@bytedance.com>
* fix(retrieval): preserve recall compatibility
Restore the deprecated recall threshold default, distinguish successful empty rewrites from compressor failures, and document legacy quota floors across coding-agent plugins.
Co-authored-by: TRAE CLI <noreply@bytedance.com>
---------
Co-authored-by: TRAE CLI <noreply@bytedance.com>
Co-authored-by: qin-ctx <qinhaojie.exe@bytedance.com>
Use ZCode rollout logs as the authoritative incremental source, advance capture state only for the acknowledged prefix, and persist host turn identity with the OpenViking turn_id contract.
Detach Stop writes, package ZCode in the TOS marketplace artifact, add end-to-end regressions, and move the integration docs under community plugins.
Co-authored-by: TRAE CLI <noreply@bytedance.com>
* feat(integrations): add ZCode memory plugin
Add examples/zcode-memory-plugin — a thin ZCode lifecycle adapter that reuses
the shared memory-plugin-shared runtime for recall, capture, commit, and MCP
proxy. No memory logic is duplicated.
Key design decisions (see docs/design/zcode-memory-plugin-design.md):
- Vendor shared runtime into scripts/shared/ via sync.mjs (self-contained plugin)
- 4 hook events only (SessionStart, UserPromptSubmit, PreToolUse, Stop) —
ZCode does not support PreCompact/SessionEnd/SubagentStart/SubagentStop
- Output schema: ZCode-canonical keys only (no Claude-Code 'decision: approve')
- Config-driven install: hooks + MCP merged into ~/.zcode/cli/config.json
- install.sh wiring: detection, TUI, validation, install, uninstall
Verified locally:
- 22/22 node:test cases pass (turns parser + hook output schema)
- sync.test.mjs passes
- install → uninstall cycle: hooks/MCP correctly written and cleaned
- URI guard denies viking:// paths with MCP redirect
- Capture writes to OV session with zc- prefix
Closes#3127
Related: #3442, #3544
* chore: remove non-essential files from PR, add .scratch to .gitignore
- Remove .scratch/ working notes (local ticket files, not codebase artifacts)
- Remove package.json and .gitignore from plugin dir (TRAE/Cursor don't have them)
- Add .scratch/ to root .gitignore
* fix(zcode): use verified ZCode field names + rollout fallback for capture
- Update zcode-turns.mjs to probe responseText/responsePreview (verified
from ZCode reverse-engineering in #3127 by @quinn-zenith) instead of
the TRAE-inferred last_assistant_message
- Add rollout file fallback: when stdin payload lacks user content (the
known ZCode limitation), read ~/.zcode/cli/rollout/model-io-sess-*.jsonl
to extract the last user+assistant pair from request.messages+response
- Fix concurrent session isolation: normalize sessionId→session_id in
zcode-hook.mjs before resolveNativeSessionId to prevent cwd-fallback
collision when two ZCode windows run in the same directory
- Add 2 new test cases for rollout fallback (14 turns tests total, 24 total)
- All 24 tests pass
* fix(zcode): address maintainer review blockers (config safety, MCP ownership, turnId)
Addresses 3 blockers from @huangruiteng's review (CHANGES_REQUESTED):
1. Config safety: distinguish ENOENT from parse errors — malformed
config.json now aborts instead of overwriting. Use backup+tmp+rename
for atomic writes.
2. MCP ownership: only replace/delete mcp.servers.openviking entries
tagged as openviking-memory. User-managed entries with the same name
are preserved on install and untouched on uninstall.
3. TurnId-based dedup: rollout entries carry monotonic turnId — now used
as the primary dedup key (capturedTurnIds set) instead of stableHash.
extractUnseenRolloutTurns scans ALL unseen entries since lastTurnId,
not just the last row — recovers missed turns after hook failure.
Fail-closed when no turns are found.
Also updates DESIGN.md to reflect verified field names (responseText/
responsePreview) and the turnId contract.
27/27 tests pass (was 24). Added 3 new rollout tests: incremental
capture with lastTurnId, multi-entry scan, turnId propagation.
* docs(zcode): update stale field name references in design spec
Update test case descriptions to match verified field names
(responseText/responsePreview instead of last_assistant_message)
and add rollout fallback + turnId test coverage descriptions.
* fix(zcode): dedup key includes role + first-capture returns all turns
Fix two bugs found in code review pass 2:
1. Assistant turns silently dropped: user and assistant from the same
rollout entry shared a turnId, so dedup via capturedTurnIds dropped
the assistant. Fix: dedup key is now ${turnId}:${role}, not turnId
alone. Regression test added.
2. First-capture data loss: when no lastKnownTurnId was set, only the
last rollout entry was returned, losing prior turns. Fix: first-time
capture now returns ALL entries.
Also: add backup step to config atomic write (copyFileSync before tmp+rename),
fix line width in zcode-turns.mjs, add 2 lifecycle tests (missed Stop
recovery, user+assistant same turnId).
29/29 tests pass (was 27).
* test(zcode): add concurrent session isolation tests
Two new test cases addressing maintainer criterion 4 (concurrent sessions):
1. Two sessions read their own rollout files — verifies session A cannot
see session B's content and vice versa (sentinel-based assertion)
2. Independent lastTurnId state per session — verifies incremental capture
progresses independently when one session has prior state and another
is fresh
31/31 tests pass (was 29).
* fix(zcode): correct rollout file path pattern (model-io-<sessionId>)
The rollout path used model-io-sess-${sessionId} but ZCode filenames are
model-io-<sessionId> where sessionId already includes the sess_ prefix.
This caused the rollout fallback to always miss the file and return empty,
defeating capture entirely in production.
Verified on live two-session ZCode setup:
- Session A (sess_8c6ce483): 2 messages, 2 commits
- Session B (sess_74759710): 2 messages, 2 commits
- No cross-contamination between sessions
31/31 tests pass. Updated all test rollout filename patterns.
* docs(zcode): fix stale rollout path in comments and DESIGN.md
Comments referenced model-io-sess-<sessionId> but actual pattern is
model-io-<sessionId> (fixed in code already, comments were stale).
---------
Co-authored-by: woshiguanxiaoliang <woshiguanxiaoliang@noreply.gitcode.com>
* fix(ragfs): preserve cache visibility on partial S3 deletes
Surface exact and per-object S3 deletion failures, while always invalidating the affected directory and stat cache scope after a recursive delete attempt.
Source-PR: #3407
Original-Commit: 8d6addf28e
* fix(session): preserve legacy policy and peer identity compatibility
Parse string false and other legacy boolean-like memory policy values without silently enabling extraction or breaking persisted configs. Encode mixed-script peers losslessly, while retaining their former lossy IDs as read-only retrieval and extraction aliases.
Source-PR: #3422
Original-Commit: 0dfd5a9ed9
* fix(memory): drain timer flush tasks during shutdown
Retain the shielded timer flush task and await it when close cancels the timer loop, so batch failures are observed and submitters are resolved without unhandled task exceptions.
Source-PR: #3438
Original-Commit: ca1d74e164
* fix(storage): preserve peer isolation and cache correctness
* fix(ingest): reserve encoded peer namespace
* ci: skip embedding-dependent resource test without secrets
* fix(ragfs): invalidate caches after partial remove
---------
Co-authored-by: zhiheng.liu <zhiheng.liu@bytedance.com>
Give with_openviking_context a deterministic lifecycle owner, reuse adapter clients without sharing invocation state, and preserve loop-scoped async behavior. Make component copies lifecycle-safe and reject post-close use before history access.
* fix(langchain): make async recording concurrency-safe
* fix(langchain): scope async state to each invocation
* fix(langchain): preserve cancellation progress on Python 3.10
* docs: fix broken links and anchors across READMEs and guides
Sweep findings: D-10, D-11, D-12, D-13, D-14, D-15. Restore valid documentation targets and stable cross-page anchors.
(cherry picked from commit e3504d633d)
* docs: correct contributor and release references
Reconstruct the factual parts of draft #3397 against current upstream: use the supported setup wizard, align the repository tree and workflow names with tracked files, document current release paths, and repair the bug-bounty link. Excludes install-policy and subjective content rewrites.
Based-on: b332e19e40
Based-on: c89afb17f2
Co-authored-by: zhiheng.liu <zhiheng.liu@bytedance.com>
* build: propagate recipe failures and align CMake minimum
Keep build failures visible, use isolated temporary extraction paths, and enforce the native build's CMake 3.15 floor across all contributor guides. CMake version parsing accepts prerelease and vendor suffixes.
Based-on: 8943a12285
Co-authored-by: zhiheng.liu <zhiheng.liu@bytedance.com>
* fix(scripts): surface backfill enumeration failures
Preserve the safety fix from draft #3415 while retaining legacy no-op arguments for existing operational scripts. Deprecated arguments now remain parse-compatible, advertise their status in help, and emit explicit warnings when used.
Based-on: 5516d96048
Co-authored-by: zhiheng.liu <zhiheng.liu@bytedance.com>
---------
Co-authored-by: zhiheng.liu <zhiheng.liu@bytedance.com>
* feat(plugins): align opencode and pi memory integrations
* fix(installer): tolerate missing optional harness CLIs
* fix(installer): install opencode file wrapper
* fix(opencode): import path for logger initialization
* fix(installer): register pi extension after copy
* feat(plugins): use MCP for opencode integration
* docs: move OpenCode and pi integrations to dedicated pages
Promote the OpenCode plugin and pi extension out of the community-plugins
page into their own numbered agent-integrations pages (10-opencode, 11-pi,
en + zh), update the overview routing table, and refresh the OpenCode image
cards to the hybrid MCP architecture (unified installer, openviking_* MCP
tools, ovcli.conf credentials).
* docs: bare TOS installer commands and reference more examples
Drop --harness from TOS-mirror install commands (image cards use the bare
installer URL, matching the claude-code/codex cards); add Open WebUI tool
server and an examples/ pointer to the community-plugins page (en + zh).
* docs: bare TOS installer commands across agent-integration pages
TOS-mirror install commands carry no flags anywhere; the installer wizard
asks for source, harnesses, language, and credentials.
* feat: add memory plugin mcp harness
* refactor: vendor shared memory plugin modules
* feat: add type quota recall api
* feat: commit codex memory by token threshold
* feat: capture codex tool calls as parts
* feat: add claude skill experience recall
* chore: fix lint in type quota recall server files
* feat: remote marketplace install with unified openviking naming
- Fix root .claude-plugin/marketplace.json git-subdir discriminator key
("type" -> "source"); claude plugin validate now passes.
- Unified installer gains --source remote|archive|dev: remote registers a
synthesized git-subdir marketplace for Claude Code and a git marketplace
for Codex (no repo clone); archive consumes the slim TOS marketplace zip;
dev registers the checkout's examples/ directory for both harnesses.
- One marketplace name (openviking) across all modes and harnesses, so the
plugin id is always openviking-memory@openviking; installer migrates old
openviking-plugins-local registrations and config.toml sections.
- Restore legacy Claude Code (<2.0) support: claude mcp add (stdio proxy)
plus node-based hooks merge into ~/.claude/settings.json.
- Restore optional statusline registration (fetches sources on opt-in).
- Checkbox TUI harness selection via /dev/tty with non-tty fallback.
- Add examples/.agents/plugins/marketplace.json so Codex directory installs
drop the synthetic symlink marketplace.
- Add shared setup wizard (scripts/setup.mjs) for pure-marketplace installs.
- release-tos.yml: upload memory-plugin-shared/install.sh and build/upload
the memory-plugin-marketplace zip; tos-install.sh prefers it and pins all
fetches to TOS via OPENVIKING_SHARED_INSTALL_URL.
- CI: bash -n on installer scripts; marketplace contract tests updated.
* fix(installer): register Claude remote marketplace as a directory
File-type marketplaces (bare marketplace.json path) make Claude Code derive
a wrong installLocation and 'marketplace update' fails with EISDIR. Write
the synthesized manifest to <dir>/.claude-plugin/marketplace.json and add
the directory instead; compare registered sources by exact match so the
old file registration migrates cleanly.
* feat(statusline): show model name and native-style context percentage
A custom statusLine replaces Claude Code's native line including its context
indicator, so reproduce it from the statusline stdin payload: 'Fable 5 ·
ctx 42%' right after the health segment, with native color thresholds
(<70% dim, 70-89% yellow, >=90% red). Falls back from used_percentage to
remaining_percentage to token counts, and stays visible in bypass mode
since it describes the CC conversation, not OV. Opt out with
OPENVIKING_STATUSLINE_CTX=off. Line cap raised 80 -> 100 visible chars.
* fix(installer): keep checkout progress off stdout in plugin_dir_on_disk
Callers capture the function's stdout, so ensure_checkout's info lines were
concatenated into the statusline command registered in settings.json.
* fix(installer): re-register codex git marketplace instead of upgrading
Codex doesn't expose which --ref a git marketplace was added with, and
'marketplace upgrade' refreshes the old ref — so a URL match must not skip
re-registration or a ref override installs the wrong snapshot. Also remove
the stale pre-unification plugin cache directory during migration.
* fix(installer): include .agents in codex sparse checkout
A plugin-dir-only sparse checkout omits the repo-root marketplace manifest
and fails with 'marketplace root does not contain a supported manifest'.
Adding --sparse .agents keeps the snapshot slim (~7.5M vs full repo).
* feat(installer): bilingual prompts, dist channel selection, and TOS git marketplace for codex
- Interactive language selection (English/中文, --lang, auto-detected from
locale); every user-facing prompt is bilingual.
- Download-source selection (--dist github|tos, prompted interactively):
github keeps the remote marketplaces; tos serves GitHub-blocked regions.
- Credentials step now always shows the current ovcli.conf values (masked
key) and offers keep-or-reconfigure instead of silently reusing them.
- Codex on TOS installs from a TOS-hosted git repo over dumb HTTP and keeps
remote updates (codex plugin marketplace upgrade); falls back to the
archive directory if the repo is unavailable. release-tos.yml builds and
uploads the single-commit bare repo (repack + update-server-info).
- Claude Code on TOS warns that directory marketplaces cannot auto-update.
- tos-install.sh bootstraps shrink to TOS_BASE + --dist tos.
- Docs (READMEs, agent-integrations pages, image cards, en+zh) now all use
the single shared installer and drop the deleted wrapper instructions.
* feat(installer): unify all choice prompts on an arrow-key TUI menu
Language, download source, connection mode, keep-or-reconfigure
credentials, statusline enable/replace, and legacy-mode confirmation all
render as the same single-select menu (arrow keys / digit shortcuts /
enter, radio-style highlight) instead of mixed numbered and y/N prompts.
Falls back to numbered input when /dev/tty can't be drawn on and to the
default choice when non-interactive. Free-text fields (URL, API key) stay
line inputs; the harness picker keeps its checkbox multi-select.
* fix(installer): stop piping plugin lists into grep -q under pipefail
grep -q exits on first match and SIGPIPEs the producer, so with pipefail
the 'codex plugin list | grep -q' check read as a miss every time (codex's
list is long; claude's short list masked the bug). Capture the output and
substring-match in bash instead — validation no longer false-warns.
Also: drop the stdio-proxy line from the Done summary; always offer the
install-source menu unless --dist/--source was given (with a checkout the
menu gains a dev option and defaults to it); surface the Claude-on-TOS
no-auto-update warning at source resolution instead of after install.
* fix: unignore examples/memory-plugin-shared/lib and commit the shared modules
The Python build-artifact 'lib/' gitignore rule silently swallowed the
shared plugin module source, so CI checkouts had only the vendored copies
and sync.test.mjs failed with ENOENT on the source directory.
* fix(recall): budget summary/uri fallbacks and sanitize non-finite scores
max_chars is the recall API's contract, but only full fragments counted
toward it — VikingBot's client-side heuristic, faithfully ported, lets
summary and uri fallbacks render far past the budget (repro: max_chars=100
rendered 548 chars). Every fragment now counts; oversized summaries degrade
to uri fragments and entries that can't even fit a uri line are dropped
(reported via stats.dropped). VikingBot itself is intentionally unchanged.
Also run _sanitize_floats over the /recall response like the neighboring
/find and /search routes, so inf/nan scores return 0.0 instead of a 500.
* feat(ingest): replay local agent-harness logs into OV sessions / 本地 agent harness 日志重放入库
Add openviking/ingest/: parse Claude Code / Codex / OpenCode / Hermes / OpenClaw conversation logs into normalized messages and replay them through OpenViking's existing session pipeline (create_session -> batch_add_messages -> commit -> async memory extraction), instead of a bespoke ETL.
Supports one-shot backfill ("存量") and cursor-driven incremental polling ("新增", WatchScheduler-style, no fs-event dependency), per-harness enable/mode/paths config, and meaningful peer_id on every turn (assistant = {harness}/{model}; user = git identity for single-user harnesses, original username for group-chat harnesses). Cursor IDE is a registered but deferred stub.
Read-position cursors persist under ~/.openviking/ingest/state.db for crash-safe, idempotent resume. New openviking-ingest CLI (backfill/watch/run/status/list-sources) and an "ingest" section on OpenVikingConfig. Verified end-to-end against a local server: 3-message fixture -> session commit -> 10 memories extracted -> idempotent re-run.
Inspired by / supersedes volcengine/OpenViking#2674.
Co-authored-by: baobaodae <2014596548@qq.com>
* docs(ingest): bilingual guide + ov.conf.example for openviking-ingest / 本地日志入库双语文档与配置示例
Add docs/{zh,en}/agent-integrations/09-log-ingestion.md (auto-registered in the VitePress sidebar) and an `ingest` section in examples/ov.conf.example (off by default).
* fix(ingest): address review — gating, crash-safe batch replay, commit recovery, single-instance lock / 修复评审问题
Fixes the merge-blockers from the adversarial review:
- master switch ingest.enabled now actually gates enabled_harnesses();
- idempotent per-batch append with a durable pending-intent reconciled against the server message count on restart (no duplicate imports after a mid-append crash);
- bounded reads (<=100 msgs/call) so huge sessions don't materialize at once;
- needs_commit flag + commit_if_needed so appended-but-uncommitted sessions still get extracted (commit even when no new source rows);
- poller keeps dirty sessions until a commit actually succeeds;
- OpenCode advances its SQLite cursor only past complete rows (late part text no longer skipped);
- single-instance file lock guards concurrent ingest processes;
- positive-value config validation (no poll busy-loop); malformed ov.conf surfaces instead of silently defaulting.
Adds 6 tests (config gating/validation, crash reconcile both ways, commit recovery).
* refactor(ingest): expose as 'openviking-server ingest' subcommand; English-only code/docs
- Route the ingest CLI through 'openviking-server ingest ...' (same dispatch as 'init'/'doctor') and drop the separate 'openviking-ingest' console_script.
- Remove mixed-in Chinese terms (存量/新增) from source docstrings, CLI help, and the English doc; the Chinese doc keeps them.
* style(ingest): ruff format + import sort (isort I)
Run ruff 0.15.16 (from the uv cache) with the repo config: fixes 5 I001 import-order errors in tests and reformats 9 files. 'ruff check' and 'ruff format --check' now pass on all added/edited files.
---------
Co-authored-by: baobaodae <2014596548@qq.com>
* Fix Codex memory hook recall noise and stop timeouts
* Tighten Codex recall compression output
* Add Codex archive resume and capture filtering
* Wrap Codex memory injection for capture filtering
* Detect Codex recall compressor profile
* Refresh Codex compressor profile on startup
* fix codex ov credential resolution
* [codex] resolve compressor profile via models_cache.json, not codex exec probe
SessionStart used to spawn 'codex exec' sequentially against each
candidate model to detect which one would respond — up to 3 probes ×
~15s timeout each, on every session start, even on resume. The
configured-on-startup default made this a guaranteed first-page-load
tax of several seconds.
Replace the probe with a lookup against codex's own model catalogue
(~/.codex/models_cache.json, refreshed by codex CLI's etag-backed
fetch). The first candidate whose slug is present wins. SessionStart
now goes cache-first: load the persisted profile if any, only resolve
on cache miss. The runtime compress path (auto-recall) deletes the
cached profile on any compress failure so the next SessionStart
re-resolves against the current catalogue.
- recall-compressor-profile.mjs:
* loadCodexModelsCache(env) reads ~/.codex/models_cache.json; missing
cache yields {present:false,slugs:Set()}.
* resolveRecallCompressorProfile picks the first available candidate
by slug; falls back optimistically to the first candidate when
the catalogue is missing.
* invalidateRecallCompressorProfileCache() rms the persisted file.
* detectRecallCompressorProfile is now cache-first and never spawns.
- auto-recall.mjs: runCodexCompressor invalidates the cache on spawn
error, timeout, non-zero exit, and read failure (best-effort,
no error surface to user).
- recall-compressor-profile.test.mjs: 11 unit tests covering catalogue
read, candidate selection (with/without configured first), missing
catalogue fallback, configured_off path, invalidate, cache-first
detect, and re-resolve after invalidate.
Notes:
- buildCodexExecArgs is still exported so auto-recall can spawn the
actual compress run; the change only removes the *probe* spawn, not
the compress spawn.
- recallCompressDetectTtlMs and recallCompressDetectTimeoutMs are
preserved in config for back-compat; the timeout no longer matters
but the TTL still bounds how stale a cached profile may be.
* [codex] omit X-OpenViking-Actor-Peer env_http_headers when no peer configured
syncMcpConfig used to unconditionally write all three OV header→env
mappings. The wrapper strips empty OPENVIKING_PEER_ID before exec'ing
codex, so an unset env var would silently flip the header to "" — the
OV side then has to disambiguate that from "no peer scope". Match the
bearer_token_env_var pattern: present only when there's something to
send. Also drops a stale X-OpenViking-Actor-Peer entry when the peer
is unset (e.g. after switching ovcli configs).
- Existing test 4 became two cases: with-peer keeps the mapping,
without-peer drops it (symmetric to bearer).
- New test asserts an in-place drop when the cached .mcp.json had a
stale peer mapping but the active config no longer has a peer.
* [codex] runtime_failed compressor marker stops same-session retry storms
Previous fix invalidated the profile cache on compress failure. Within a
single codex session that still bled `recallCompressTimeoutMs` of wall
time per UserPromptSubmit because the next hook reread cache (miss),
fell back to fallbackRecallCompressorProfile, and tried the same model.
Replace plain invalidate with a runtime_failed sentinel cached in the
profile slot. UserPromptSubmit's compressMemoryContext already short-
circuits on `profile.enabled === false`, so the marker stops further
spawns for the rest of the codex process. The next SessionStart cache-
first detect treats `source === 'runtime_failed'` as cache miss and
re-resolves against the current models_cache.json, so a transient
failure self-recovers across codex restarts without operator action.
detect_on_startup=false respects the marker (no auto-recover, matches
the "manual control" intent of that flag).
- recall-compressor-profile.mjs:
* markRecallCompressorRuntimeFailed(cfg, {failedModel}) writes the
disabled sentinel.
* detectRecallCompressorProfile branches on cached.source ===
'runtime_failed': cache hit otherwise, recover-via-resolve when
startup-detect on, respect marker when off.
- auto-recall.mjs::runCodexCompressor: swap invalidate-on-error with
markRecallCompressorRuntimeFailed(cfg, {failedModel: profile.model}).
- recall-compressor-profile.test.mjs: 4 new tests covering marker
write, cross-restart recovery picking a different slug, and the
detect_on_startup=false honor path. 20/20 pass.
invalidateRecallCompressorProfileCache is kept as a public API for
explicit operator use (e.g. a future `ov codex reset-compressor`
command), but is no longer called from the runtime path.
* ci: upload source zip and plugin installers to TOS on release
Add a standalone workflow (20. Release TOS Upload) that runs on release
publish (or manual dispatch with a tag for backfill) and uploads:
- the source archive to releases/<tag>/ and releases/latest/
- both memory-plugin install.sh scripts to versioned paths and to
stable root paths for a China-reachable one-liner URL
Reuses the existing TOS secrets (AK/SK/region/endpoint) with a new
TOS_RELEASE_BUCKET secret so release artifacts stay out of the docs
bucket. Missing secrets skip gracefully (fork-friendly); real upload
failures fail the workflow.
* ci: server-side copy for the latest source zip
* feat(plugins): GitHub-free TOS install path for memory plugins
Domestic users can't reach github.com / raw.githubusercontent.com, so the
existing one-liner installers stall at their step-3 `git clone`. Add a
GitHub-free path that sources everything from Volcengine TOS:
- Both install.sh learn OPENVIKING_REPO_ARCHIVE_URL: when set, fetch the
source from a zip (curl + unzip) instead of git clone. A
.openviking-archive-source marker makes re-runs idempotent and refuses
to clobber a git checkout or unrelated data at REPO_DIR.
- New setup-helper/tos-install.sh bootstrap per plugin: sets the TOS
archive URL, downloads the real install.sh from TOS to a temp file
(kept off the stdin pipe so prompts stay interactive), and delegates.
- release-tos.yml uploads both tos-install.sh alongside install.sh.
One-liner for users behind the GFW:
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/claude-code-memory-plugin/tos-install.sh)
The GitHub default path is unchanged; archive mode only activates when
OPENVIKING_REPO_ARCHIVE_URL is set.
* docs: document the TOS (GitHub-free) install path for memory plugins
Main agent-integration docs (zh/en, claude-code + codex) keep the GitHub
one-liner and add the TOS equivalent for regions where GitHub is hard to
reach. The CDN integration cards switch their install one-liner to the TOS
bootstrap only, since that gallery is served where GitHub raw is unreliable.
* docs: trim the TOS install note to one line
Adding a shell-alias name (e.g. `cc` from `alias cc=claude`) to
OPENVIKING_CC_WRAP_EXTRA / OPENVIKING_CODEX_WRAP_EXTRA broke the wrapper:
bash expands the alias mid-eval and clobbers the base `claude`/`codex`
function (so `command cc` ends up running the C compiler), while zsh
aborts with a parse error on every shell start. Guard the wrapper-defining
loop to skip names that are already shell aliases — an alias already
routes through the base wrapper once it expands, so it needs no function.
Also reject heads starting with `-`, which `alias`/`command` would
otherwise misparse as an option.
Also document the custom-launch-command feature and the alias guidance:
- 8 agent-integration docs (en/zh main + CDN cards): brief install note,
plus two troubleshooting rows (wrapper-not-sourced, alias gap)
- claude/codex plugin READMEs (+ README_CN, which was missing the section
entirely): wrap the real target command, never the alias name
* docs: refresh Claude Code & Codex memory plugin integration docs
- Fix dead anchor #1-wrap-claude-to-inject-env-from-ovcliconf -> #configuring-mcp
in the Claude Code manual setup (zh/en agent-integrations + CDN cards)
- Add the post-install wrapper activation step (source .../wrapper.sh) to the
Claude Code docs, and make Codex's activation shell-agnostic
(source ~/.zshrc -> source .../codex-memory-plugin/setup-helper/wrapper.sh)
- Rewrite Claude Code manual step 1 to the guarded `source wrapper.sh` form
- Convert Claude Code "How it works" into a lifecycle bullet list
- Language polish pass across all eight Claude Code / Codex docs
- Sync docs/images/agents/zh/index.json summaries with the refreshed intros
* docs: foolproof the verify step against an inactive wrapper
Add a guard note to the Verify section of every Claude Code / Codex doc:
if `type claude` / `type codex` prints a path instead of "shell function",
the wrapper isn't active, so re-source it (or open a new terminal) before
launching — otherwise Claude Code silently connects to 127.0.0.1 with no
auth, and Codex starts without OPENVIKING_API_KEY and reports
"MCP server is not logged in". For Claude Code, also state explicitly to
launch `claude` from the terminal where the wrapper is active.
Applies to all eight surfaces (zh/en, agent-integrations guides + CDN cards).
* docs: overhaul agent-integrations section for clarity and beginner-friendliness
Restructure the agent-integrations documentation (EN + ZH) to be concise,
beginner-friendly, and consistently structured across all runtimes.
* docs(mcp-clients): clarify OAuth flow for Claude Desktop / Claude.ai
* docs(mcp-clients): add public access guide link for OAuth section
* docs: address review — clarify dev-mode auth, add missing import
* docs(mcp-guide): update verified platforms, fix OAuth section scope
Use explicit clawhub: prefix across all install paths (README, INSTALL, INSTALL-ZH, INSTALL-AGENT, SKILL.md) since bare specs resolve to npm on current OpenClaw. Restructure ClawHub README with Quick Start first screen, How It Works, Tools table, Data Flow and Privacy section. Move engineering details into collapsible section. Demote ov-install to fallback. Fix ov-install params, OpenClaw min version, and parameter table. Allow images in ClawHub bundle.
Co-authored-by: Cursor <cursoragent@cursor.com>
Two related fixes to plugin tuning ergonomics:
1. `captureAssistantTurns` defaults to true (mirrors claude-code-memory-plugin).
A memory plugin that only captures the user side of every turn extracts
half the conversation and produces noticeably worse memories. Operators
who want the old user-only behavior can still set
`OPENVIKING_CAPTURE_ASSISTANT_TURNS=0` or `codex.captureAssistantTurns=false`.
2. README + agent-integrations docs (zh+en) now recommend `OPENVIKING_*`
environment variables in shell rc as the primary way to tune the plugin.
The previous docs claimed the tuning block lived in `ovcli.conf`, but
`scripts/config.mjs` only reads `codex.*` from `ov.conf` — and `ov.conf`
is server-scope, so per-machine plugin tuning doesn't belong there
anyway. The legacy `ov.conf` path is acknowledged and kept working for
backward compat, but de-emphasized.
* fix(plugin/codex): allow empty api_key (unauthenticated local OV)
Reported: with an ovcli.conf that has no `api_key` (typical local OV
without auth), the plugin would not start cleanly. Root cause: .mcp.json
ships with `bearer_token_env_var: "OPENVIKING_API_KEY"`, and when that
env var resolves to an empty string at codex launch (because ovcli.conf
has no key), Codex interprets it as "auth configured but not provided"
and falls back to its OAuth dance — which then fails against an OV that
doesn't speak OAuth.
Hook side is unaffected: scripts/config.mjs already gates the Bearer
header on `if (cfg.apiKey)`, so empty api_key → no Authorization header
sent → OV accepts in unauth mode. Verified end-to-end with auto-recall
against `http://127.0.0.1:1933` and an empty-key ovcli.conf.
Fix: at install time, detect whether ANY api_key is configured (env or
ovcli.conf) and conditionally render `.mcp.json` *with or without*
`bearer_token_env_var`:
- api_key present → keep `bearer_token_env_var: "OPENVIKING_API_KEY"`
- api_key absent → drop the field entirely (Codex will then just hit
OV without Authorization and treat 200 as success)
Implementation uses node (already required) to read/edit the cached
.mcp.json as proper JSON rather than sed, so we don't have to worry
about field-position-dependent regexes.
Installer footer now also reports the resolved auth mode so the user
sees `MCP auth: Bearer (OPENVIKING_API_KEY)` vs `MCP auth: none
(unauthenticated)` at the end of the run.
env_http_headers stays in both modes — identity headers
(X-OpenViking-Account / User / Agent) are independent of auth and OV
accepts empty values (defaults to "default").
* fix(plugin/codex): support runtime OPENVIKING_CLI_CONFIG_FILE swap
Reported: setting OPENVIKING_CLI_CONFIG_FILE=ovcli-local.conf (a config
without api_key, for benchmark-memory isolation) and running codex fails
with:
Environment variable OPENVIKING_API_KEY for MCP server 'openviking-memory'
is empty
Two issues stacked on top of each other:
1. Codex 0.130 hard-fails MCP startup when bearer_token_env_var resolves
to an EMPTY env var (confirmed empirically — not OAuth fallback, just
a startup error).
2. The previous codex() wrapper exported `OPENVIKING_API_KEY=""` via the
inline-prefix syntax `OPENVIKING_API_KEY="${...:-${...:-}}" codex`,
which sets the variable to an empty string when no key is resolvable.
So even my prior fix (don't render bearer_token_env_var when no key
at install time) didn't help users who install with one conf and run
with another via OPENVIKING_CLI_CONFIG_FILE.
Fix is two parts:
a) Build the env prefix dynamically into a bash array, skipping any
OPENVIKING_* whose resolved value is empty. So an empty api_key
produces no OPENVIKING_API_KEY at all in codex's env — neither
set-to-empty nor set-to-something.
b) Have the wrapper re-render the cached .mcp.json's bearer_token_env_var
on every codex launch based on the currently-active ovcli.conf. The
idempotent fast-path skips writing when the desired state already
matches. This makes swapping configs at runtime (typical benchmark
isolation workflow) work without re-running the installer.
The wrapper now uses `env "${_env_args[@]}" codex "$@"` instead of the
inline-prefix form for the same reason — proper handling of conditional
env-var presence.
Manual setup snippets in README + docs (en/zh) updated to the same
empty-aware pattern; the cache-rendering bit is left to the installer-
emitted wrapper since it's noisy and only needed when actually swapping
configs.
Validated with synthetic test:
ovcli-local.conf (no api_key)
→ env passed to codex: URL=..., ACCOUNT=..., USER=..., AGENT_ID=codex
(no OPENVIKING_API_KEY at all)
→ cache .mcp.json rewritten to drop bearer_token_env_var
ovcli.conf (with api_key)
→ env passed to codex: URL=..., API_KEY=..., ACCOUNT=..., USER=..., AGENT_ID=codex
→ cache .mcp.json rewritten to re-add bearer_token_env_var
Idempotent: re-render with same hasKey state does not bump file mtime.
* fix(plugin/codex): wrapper also re-renders cache .mcp.json URL
Previously the codex() wrapper only re-rendered bearer_token_env_var
based on the active ovcli.conf, but the cached .mcp.json URL stayed
whatever was baked at install time. Result: swapping
OPENVIKING_CLI_CONFIG_FILE to a config that points at a different OV
server (e.g. localhost) would still hit the install-time URL —
typically the remote production OV — and fail auth.
Reported in testing:
OPENVIKING_CLI_CONFIG_FILE=ovcli-local.conf codex
# ovcli-local.conf: { "url": "http://127.0.0.1:1933" }
# cache .mcp.json still says url=https://ov-dev.tosaki.top/mcp
# Codex hits remote ov-dev with no bearer → 401 → "Not logged in" OAuth dance
Fix: the rewrite block now also patches s.url from the conf-resolved
URL (`${_ov_url%/}/mcp`, or `$OPENVIKING_MCP_URL` if explicitly set).
Same idempotent fast-path — only writes when something actually changed.
Tested both directions:
ovcli-local.conf (no key, localhost)
→ cache .mcp.json: url=http://127.0.0.1:1933/mcp, no bearer field
→ env passed to codex: no OPENVIKING_API_KEY
→ /mcp: Auth: None, tools list populated
ovcli.conf (with key, remote)
→ cache .mcp.json: url=https://ov-dev.tosaki.top/mcp, bearer present
→ /mcp: Auth: Bearer token, tools list populated
* refactor(plugin/codex): switch MCP from local stdio server to OV /mcp (http)
Codex 0.130 supports streamable-HTTP MCP servers with bearer auth via
`bearer_token_env_var` in `.mcp.json` (and per-header env binding via
`env_http_headers`). OpenViking server has exposed `/mcp` natively since
1.27, so the local stdio MCP middleman (`src/memory-server.ts` +
`servers/memory-server.js` + the npm-ci runtime bootstrap) is dead weight:
the model now gets a strictly larger tool set (search, store, read, list,
grep, glob, forget, add_resource, health — vs the previous recall/store/
forget/health) by talking to OV directly, and the plugin loses its only
build/dependency surface.
What changed
- `.mcp.json`: switched to `url` + `bearer_token_env_var: "OPENVIKING_API_KEY"`
+ `env_http_headers` for the multi-tenant identity headers. URL is a
`__OPENVIKING_MCP_URL__` placeholder; installer renders it from ovcli.conf
/ `OPENVIKING_URL` at install time. API key never lands on disk in the
cached .mcp.json — it's pulled from process env at codex launch.
- `setup-helper/install.sh`: resolves the OV /mcp URL (OPENVIKING_MCP_URL >
OPENVIKING_URL/mcp > ovcli.conf.url/mcp > localhost), renders the
.mcp.json placeholder into the cached copy, and appends a `codex()` shell
function wrapper to the user's rc that promotes ovcli.conf fields into
env vars before exec'ing codex (mirrors the claude-code-memory-plugin
pattern; needed because Codex reads OPENVIKING_API_KEY from process env
at MCP launch, not from any file).
- Deleted: `src/memory-server.ts`, `servers/memory-server.js`, `tsconfig.json`,
`package.json`, `package-lock.json`, `scripts/bootstrap-runtime.mjs`,
`scripts/runtime-common.mjs`, `scripts/start-memory-server.mjs`. Net
~2400 lines removed. Hook scripts remain zero-dep .mjs running on
Codex's bundled Node 22.
- README + docs/{en,zh}/agent-integrations/04-codex.md: rewritten to
describe the new architecture. The MCP tools list and protocol details
are now referenced via a link to docs/{en,zh}/guides/06-mcp-integration.md
rather than duplicated in the plugin docs.
- Plugin version: 0.4.1 → 0.5.0.
Validation
Verified end-to-end on Codex 0.130 against `ov-dev.tosaki.top`:
/mcp
🔌 MCP Tools
• openviking-memory
• Auth: Bearer token
• Tools: add_resource, forget, glob, grep, health, list, read, search, store
`openviking-memory.health` returned `OpenViking is healthy ... storage: VikingFS`;
Stop hook reported `appended 2 turn(s) to OpenViking session <id>`.
Notes
- `.mcp.json` headers that don't have a corresponding env var (e.g. user
didn't set `OPENVIKING_USER`) are simply not sent — `env_http_headers`
silently omits missing vars per Codex's MCP runtime.
- Rotating the API key now just needs `codex` restart (env re-reads from
ovcli.conf via the wrapper). URL changes still need a re-install since
the URL is baked into the cached .mcp.json.
- The shell function wrapper has a marker-delimited block so re-running
the installer replaces it in place rather than appending duplicates.
* review(plugin/codex): address copilot feedback on installer + docs
1. Switch the codex() shell-function wrapper from jq to node. The installer
already hard-requires node 22+, while jq is not always present; the old
wrapper would silently fall through to `command codex` with no env
injection when jq was missing, which caused Codex to start with no
Bearer token, OV to return 401, and Codex to drop into its OAuth
fallback. Now there is a single tool dependency for both the installer
and the wrapper it emits.
2. Marker-replacement is now defensive: rewrite-in-place only triggers
when BOTH the BEGIN and END markers exist in the rc. If only BEGIN
is present (manual edit / corruption), warn and append a fresh block
instead of awk-dropping everything from BEGIN to EOF.
3. When no rc is detected, omit the `source $RC` line from the final
"Next:" hint and tell the user to paste the snippet manually instead
of printing `source ` with a trailing space.
4. Docs (README + 04-codex.md zh/en): use the full env var names
(OPENVIKING_API_KEY / OPENVIKING_ACCOUNT / OPENVIKING_USER /
OPENVIKING_AGENT_ID) instead of `_ACCOUNT` / `_USER` shorthand;
update the manual-setup snippets to the node-based wrapper.
The wrapper body is now defined once and reused for both the appended-to-rc
path and the manual-paste path, so the two cannot drift.
* docs(plugin/codex): add dedicated agent-integrations page + fix MCP startup
Follow-up to #1957. Lifts Codex out of `04-other-plugins.md` into its own
`04-codex.md` (en + zh) with full install steps, configuration, hook
behavior, and troubleshooting — mirrors the shape of `02-claude-code.md`.
Renumbers `04-other-plugins.md` → `05-` and `05-langchain-langgraph.md`
→ `06-`. Overview tables in both locales updated; cross-refs fixed.
Also fixes two install/runtime bugs surfaced while validating the fresh
installer flow against the merged PR:
1. **Stale repo clone**: `setup-helper/install.sh` previously skipped the
clone if `~/.openviking/openviking-repo` already existed, so a user
who installed before #1957 merged ended up with a pre-PR plugin
checkout (no `scripts/`, no `servers/memory-server.js`). The installer
now `git fetch + reset --hard` an existing checkout to `$REPO_REF`
(default `main`), matching the claude-code installer pattern.
2. **`${CODEX_PLUGIN_ROOT}` not expanded in `.mcp.json`**: Codex 0.130
does not substitute env vars in `.mcp.json` `args`/`env` and does not
always inject `CODEX_PLUGIN_ROOT` into MCP child env. The literal
string `${CODEX_PLUGIN_ROOT}` was being passed to node, which then
tried to resolve `${CODEX_PLUGIN_ROOT}/scripts/start-memory-server.mjs`
against codex's cwd and failed with `MODULE_NOT_FOUND`. Fix:
- `.mcp.json`: `args: ["scripts/start-memory-server.mjs"]` + `cwd: "."`
(matches the syntax 0.1.0 used, which Codex does honor)
- `scripts/runtime-common.mjs`: derive plugin root from
`import.meta.url` as a fallback so the launcher works regardless of
whether `CODEX_PLUGIN_ROOT` is set in the spawn env
Bumps plugin to 0.4.1 (package.json + plugin.json + lockfile) since the
runtime-common.mjs change invalidates the install-state hash and forces
a re-install of node_modules into the per-user runtime data root.
* fix(plugin/codex): hooks.json must use relative paths, not ${CODEX_PLUGIN_ROOT}
Same root cause as the .mcp.json fix in the previous commit: Codex 0.130
does not expand ${CODEX_PLUGIN_ROOT} in hooks.json `command` strings. The
shell that runs the hook sees the literal ${CODEX_PLUGIN_ROOT} and expands
it to "" (or leaves it literal), so node tries to load `/scripts/...mjs`
and exits 1.
Symptom in the chat UI:
• SessionStart hook (failed) error: hook exited with code 1
• UserPromptSubmit hook (failed)
• Stop hook (failed)
Fix: use `./scripts/<name>.mjs` paths, matching the pattern Codex's own
bundled plugins (e.g. figma) use. Codex's hook dispatcher resolves these
relative to the plugin root (where hooks.json lives).
The MCP launcher fix from the prior commit already handles the same class
of bug for .mcp.json; this catches the hooks path.
* fix(plugin/codex): hooks.json needs absolute paths rendered at install time
Previous fix (relative ./scripts/...) was based on the figma example but
empirically does not work on Codex 0.130: the hook subprocess runs with
cwd = user's cwd (not plugin root) and CODEX_PLUGIN_ROOT is NOT injected
into the env. So both ${CODEX_PLUGIN_ROOT}/scripts/foo.mjs and
./scripts/foo.mjs resolve to the wrong absolute path and node exits 1.
Verified with a probe shell script wired into hooks.json:
argv: /tmp/codex-hook-probe.sh SessionStart
cwd: /Users/<user>
CODEX_PLUGIN_ROOT: <unset>
CODEX_PLUGIN_DATA: <unset>
(The "Under-development features are incomplete" banner Codex prints when
plugin_hooks is enabled is real - the hook env wiring is unfinished in
0.130.)
Fix: keep the source hooks.json as a template (uses __OPENVIKING_PLUGIN_ROOT__
placeholder) and have install.sh sed-render the cache copy with the
absolute $CACHE_DIR path on every install. The cached hooks.json is now
fully self-contained absolute-path commands; the repo's checked-in copy
stays portable.
.mcp.json is unaffected: Codex 0.130 does honor the `cwd: "."` field for
MCP servers, so relative args resolve against plugin root there.
* fix(plugin/codex): bump UserPromptSubmit timeout to 15s
Empirically the auto-recall hook can take 0.8s–4s end-to-end (depending on
result count and remote OV latency), and Codex 0.130 sometimes adds 4-5s
of spawn overhead before our script even starts. The original 8s budget
was borderline and produced spurious "hook timed out after 8s" UI errors
on slow paths even when the recall would have succeeded.
15s matches the auto-recall internal timeoutMs default (config.mjs:186)
and gives enough headroom for spawn-time variance without holding the
user's input noticeably longer in the worst case.
* fix(plugin/codex): installer accepts OPENVIKING_REPO_BRANCH as alias
Per review feedback: the claude-code installer uses OPENVIKING_REPO_BRANCH
for the same purpose. Aliasing both names lets users reuse one env var
across installers without remembering which plugin uses which name.
Precedence: OPENVIKING_REPO_REF > OPENVIKING_REPO_BRANCH > "main".
