feat(memory): bundle Mem0 with the main CLI - #12891

Verification report — controlled providers

The local implementation passed the checks below. The checked working-tree source is now committed as 46d1101f5f70. These results are from macOS, not a full CI matrix or live PolarDB acceptance.

Reproduction commands

npm run build -- --cli-only
DEV=true npm run bundle
npm --prefix integrations/external-context run typecheck
npm --prefix packages/cli run typecheck
npm run typecheck:integration

# Run unit tests from their package directories:
cd integrations/external-context
npx vitest run src/config.test.ts src/providers.test.ts src/mcp.test.ts src/write-confirmation.test.ts
cd ../../packages/cli
npx vitest run src/config/mem0-settings.test.ts src/config/config.test.ts src/config/settings.test.ts src/config/hook-settings.test.ts src/ui/commands/hooksCommand.test.ts
cd ../..

# These installer fixtures temporarily replace dist: do not run them alongside bundling.
npx vitest run scripts/tests/package-assets.test.js
npx vitest run scripts/tests/install-script.test.js --testTimeout=15000
DEV=true npm run bundle
QWEN_SANDBOX=false npx vitest run --root ./integration-tests interactive/external-context-mem0-write.test.ts --retry=0

Observed user-visible behavior

The five existing Platform V3 scenarios still passed. The three OSS scenarios use user memory.mem0 settings rather than a manual MCP or Hook configuration: default approval requires the ordinary MCP permission followed by exact-content confirmation; cancellation sends no HTTP write; YOLO still asks for exact-content confirmation. Successful OSS writes hit /memories, use X-API-Key, bind user_id, send infer: false, preserve the approved content and render stored with an ID.

An independent stdio run selected default V2, sent POST /v2/memories/search with Authorization: Token and limit: 5 (no top_k), filtered invalid responses, retained at most five items and preserved the independently calculated default scope after restart from a Git subdirectory. Default tool discovery exposed only search. Explicit write enablement sent exact content to /v1/memories with infer: false.

Copying only the runtime and confirmation executable outside the repository (plus a module-type package marker) still passed initialize/list/search/Hook invocation without child node_modules or NODE_PATH. This verifies that a separate external-context npm installation is not required.

Limits and initial failures

The first Hook-command run exposed a missing getMcpServers test mock; the corrected fixture passed on rerun. The first installer run raced concurrent bundling because its fixture replaces root dist; the serial rerun passed, and the final bundle was created after fixture restoration. Actual package preparation warned about an absent optional native audio prebuild; audio capture was not tested.

No real model was used: the real CLI ran against a controlled OpenAI server. No current endpoint/credential pair was available for the real memory instance, so live authentication, slash behavior, limit handling, persistence, restart retrieval and targeted cleanup remain unverified. No real memory was read, changed or deleted. Windows/Linux native execution and the remote-aligned review gate were not run. CI state is separate from these local results.

Verification update — settings-defined credentials

Committed in 68fbb0a3d7bd. The checks below used the same source in the local working tree before commit; no product source changed afterward.

The Mem0 settings path now follows model-provider configuration: memory.mem0.envKey selects a variable name and the top-level user env object can define its value. A shell export is not required. credentialEnv remains a compatible alias; conflicting references fail explicitly. This reuses the existing environment loader rather than adding another credential store.

Focused checks

The OSS run removes both the custom variable and default MEM0_API_KEY from the launching environment. Only the isolated user settings define the controlled credential, with no manual MCP or user Hook. Approving sends one correctly authenticated /memories request with exact content and infer: false; cancellation sends zero provider requests; YOLO still confirms exact content. Successful writes reach the model as stored with an ID and the completion marker appears in the rendered transcript. The actual CLI PTY stream and machine-readable results were retained locally.

The first name filter selected zero tests because Vitest truncated generated parameterized names; that skipped run was not counted as verification. The corrected prefix filter executed the intended three cases successfully.

Commands

# CLI package
npx vitest run src/config/mem0-settings.test.ts
npm run build

# Worktree root
npm run typecheck:integration
DEV=true npm run bundle

# integration-tests directory, with isolated QWEN_HOME and controlled credentials
QWEN_SANDBOX=false QWEN_E2E_RENDERER=ink npx vitest run interactive/external-context-mem0-write.test.ts -t 'uses two confirmations for the OSS|does not write to the OSS|still asks for content confirmation f' --retry=0

Actual tmux UI check

An additional bounded real CLI session in tmux passed with the Ink renderer and a custom credential defined only in isolated user settings. The screen showed successful context_search and its untrusted result envelope, followed by the ordinary MCP permission and exact-content confirmation. Esc cancelled the proposed write and returned to the input prompt. The controlled service received exactly one authenticated /search request (top_k: 5, fixed user scope), zero /memories writes, and the model received two requests.

Actual terminal excerpts:

✓ context_search (external-context MCP Server) {"query":"settings-only UI memory search"}
◆︎ SEARCH_UI_DONE. Retrieved memory: QWEN_MEM0_UI_SEARCH_VISIBLE: settings-only memory result

Save this exact content to the bound Mem0 repository memory?
"QWEN_MEM0_UI_EXACT [visible](https://controlled.invalid/target) **literal**\nKeep this exact repository policy."

# After Esc: returned to the rendered input prompt
Type your message or @path/to/file

The first tmux fixture incorrectly routed model responses by request index across two prompts; search rendered successfully but the fixture returned an unexpected continuation instead of proposing a write. That failed attempt was retained, not counted as a pass. Updating only the ignored controlled-model script to route from the actual search tool result allowed one bounded rerun to pass; no source or bundle change was required.

These are local macOS results with the real bundled CLI and controlled model/memory HTTP services. The prior CI results belong to the original head, not to the new commit's CI. Live PolarDB authentication, limit/slash behavior, persistence and restart retrieval, and native Windows/Linux CLI execution remain unverified. Ready for review does not mean approval, release, or live-provider acceptance.

Merged main through #12900 in dd12698 to address the SDK Java failures. Both failed jobs in the old run reported Found more than one migration with version 16: the upstream runtime-loss and Session lifecycle changes both introduced V16. This PR's Mem0 commits do not change SDK Java migrations.

Verification: the merged tree has 16 SQL migrations with 16 distinct versions; lifecycle now uses V17. One focused CLI configuration test pass exited 0: 20 passed, 482 filtered/skipped, no retries. Both affected Java jobs passed on #12900's exact head 1f1136066e26f7dbb8de54e057d6e03b8591af84 in its SDK Java run. Java/Maven are unavailable locally, so that is upstream CI evidence, not a local Java/MySQL test.

The branch was pushed normally without rewriting history or changing the Mem0 implementation. New SDK Java CI is pending; this is not a claim that the new PR head is fully green.

中文：已合入主分支 #12900 的修复并正常推送。原先两个 Java job 失败是上游两项变更都使用了 Flyway V16，并非 Mem0 改动引起；合并后生命周期迁移使用 V17，16 个 SQL 迁移版本无重复。一次聚焦配置验证通过 20 个用例，其余 482 个被过滤跳过，无重试。上游修复的对应 Java job 已通过，但本机没有 Java/Maven，没有执行本地 Java/MySQL 验证。当前 PR 新一轮 CI 仍待完成，未宣称全绿，也未重跑 UI 或真实 PolarDB 验收。

Round 4 closeout: pushed c84059b and c9a801e to the existing PR branch. Operator Mem0 config is now selected as a whole, explicit null disables it, and a workspace MCP entry cannot hide an operator collision. The historical PolarDB preset keeps raw search content; only mem0-v2 unwraps verified direct-import text. Reserved config environment aliases and the Windows package-asset assertion are fixed. Six-preset documentation now includes linked complete English and Chinese designs.

Verification: build, typecheck, focused ESLint/Prettier, 745 CLI config tests, 51 adapter tests, and 51 package-asset tests passed. Replacing the Windows-safe needle with win32.join made both new Windows regressions fail; restoring it passed all 51 tests. Native Windows and live Mem0 were not rerun in this round. The prior private-tunnel PolarDB acceptance report remains the live evidence: #12891 (comment) . CI for c9a801e is pending; no success is claimed for unfinished jobs.

Scope: original goal remains opt-in Mem0 in the main CLI without a separate npm release. This fourth review round only addressed verified correctness/compatibility defects and their minimal regressions; no dependency, protocol family or generic MCP framework was added. Broader test matrices, Hologres/universal versions, automatic recall and generic MCP precedence redesign remain deferred. Other reviewer suggestions are not bulk-resolved.

中文：本轮已推送两条修复提交；解决配置跨层拼接与 null 禁用、工作区遮蔽操作者 MCP 冲突、旧预设返回值、Windows 环境变量别名和打包断言，并补齐双语预设设计。定向验证 847 项通过；Windows 原生和真实服务本轮未重跑，最新 CI 尚未完成。普通用户只需等待包含此 PR 的主 CLI 发版，不需要单独发布 Mem0 npm 包。

Disposition update: all 26 previously unresolved Suggestion threads received a current-head decision and are now resolved. Three were already covered by documentation, one Hologres request is outside this bounded protocol, and 22 test-only proposals are explicitly recorded for a later focused PR in the linked comment. This did not change code or increment the substantive round count. The old bot CHANGES_REQUESTED review still awaits re-review/dismissal; CI remains pending, not claimed green.

Round 5 critical closeout: pushed 8bfd4aa. A temporary MCP allow-list filter can no longer delete Mem0's interactive write-confirmation hook during /hooks reload; operator memory.enableManagedAutoMemory=false and enableManagedAutoDream=false survive a trusted workspace memory:null alongside Mem0. Both defects were reproduced before the fix and verified afterward with the built CLI and real bundled runtime (no live provider call). Full build, bundle, typecheck, focused lint/format, and 238 CLI tests passed. Post-push CI snapshot had no failures and several checks queued. The old bot CHANGES_REQUESTED review is against ed45308, not this head.

Verified the bundled Mem0 path with the configured real kimi-k3 model and a live PolarDB-hosted Mem0 instance, using actual interactive CLI sessions and tmux captures.

• Settings-only startup connected external-context; the Mem0 credential came from settings.env through a custom envKey, not a shell export or separate npm package.
• The CLI displayed the full two-line write content for approval. One approved infer:false write returned HTTP 200 and ID 66d6b5e2-94e8-4bdd-ab1e-92bb9833affa. A fresh CLI retrieved the same ID and complete content. A prior model call omitted the second line; it was not approved and sent zero writes.
• Live testing exposed a response difference: PolarDB returns direct-import memory as a serialized single-user message array. 0edc8f5c2e40 restores the exact text only for the verified PolarDB presets, only when infer:false and the wrapper matches. Other protocols and unmatched/plain content remain unchanged. Post-fix read-only verification checked both the actual TUI result and the actual tool-result payload sent to the real model. A final user-ready session also retrieved the record with the model endpoint configured directly, without a model/evidence relay.
• Preserved the concurrent fixes by merging, not rewriting history. cc0b66000fd3 corrects the Hook reload test's control fixture to use the actual bundled binding instead of an arbitrary fake runtime path.

Focused verification: provider tests 51 passed, affected CLI Mem0 checks 38 passed, Hook command tests 19 passed, external-context typecheck passed, and the bundle rebuilt successfully. The original live harness exits are retained: one caught a missing model argument before approval; one assumed the raw provider response was plain text; the post-fix capture harness had a regex error, with a separate read-only evidence audit passing. This is observed real-provider acceptance, not a claim that every E2E automation run was green.

Network boundary: the live instance was reached through the previously configured restricted SSH tunnel to its private endpoint. Public-direct access still timed out, so this does not claim public connectivity is fixed. Only one synthetic record was created in a dedicated test scope; it remains available for debugging. Existing memories were not changed. The ineffective temporary whitelist group was removed, existing whitelist groups were retained, and global user settings were not modified. No standalone Mem0 package publication was required; installed-package availability still depends on a main CLI release containing this PR.

中文验收摘要：已经用真实模型、真实 PolarDB 实例和实际 tmux CLI 验证 settings-only 连接、完整内容确认、一次批准写入、返回 ID、重启检索同一记录。发现并修复了 PolarDB direct import 返回消息数组 JSON 的兼容差异，修复后界面和模型收到的工具结果都是完整原文；保留给用户的直连模型调试窗口也已成功检索。51 个 provider 测试、38 个相关 CLI 检查、19 个 Hook 测试和相关 typecheck/bundle 通过。原始自动化失败证据未覆盖，不冒充全绿。当前可用链路是专用 SSH 私网隧道，公网直连问题仍未解决；没有发布独立 npm 包，也没有改全局 settings 或其他用户记忆。

CI attribution for the red Test (ubuntu-latest, Node 22.x) on head 21eb353075 (run 36530420031) — not caused by this PR.

37059 tests pass. The only failures are 7 cases in packages/core/src/agents/background-agent-resume.test.ts:

× BackgroundAgentResumeService > matches the launch-time skill listing when the definition inherits every tool
× ... declares an empty tools list
× ... declares a null tools value
× ... declares a wildcard tools string
× ... declares an empty tools string
× ... declares a non-array disallowedTools value
× ... names exec without skill under CodeModeOnly
  → expected false to be true // Object.is equality   (each, retry x2)

Evidence that these come from main:

• All 7 are expansions of one parameterized title added by fix(core): withhold the SkillManager from subagents whose tool policy has no Skill tool #12545 (d5a157c45e, merged to main 2026-09-29T05:55:15Z). Its patch adds + 'matches the launch-time skill listing when the definition %s', and modifies both background-agent-resume.ts and background-agent-resume.test.ts.
• This head is Merge origin/main into codex/12596-bundled-mem0 at 06:15:56Z — 20 minutes after d5a157c45e landed — so the failure is inherited from the base, not introduced here.
• This PR's diff is 32 files with zero matches for background-agent-resume, src/agents/, or skill. Bundling Mem0 does not touch the failing area.
• The identical 7 failures with the identical assertion also appear on fix(cli): pin fast model to the selected provider endpoint #12773 at head 53c902ad02 (run 36534233486), an unrelated PR (fast-model endpoint disambiguation, 19 files, also zero matches on that area) whose head merged main at 07:01:32Z. Two unrelated branches failing the same 7 cases the same way points at the shared base.

This is a main-side breakage from #12545 that will red-flag every PR syncing main after 05:55Z, so it needs a fix on main rather than a workaround inside this PR. Not patching around it here.

Note this PR is also over the patrol's +1500-line scope fuse at +1657, so this round made no code changes to it; the 4 findings verified real-and-unfixed in the previous round remain open with their evidence replies.

Update — this is already tracked upstream: issue #12991 (Main CI failed: Qwen Code CI — src/agents/background-agent-resume.test.ts > … > matches the launch-time skill listing when the definition in… (+6 more), opened 2026-09-29T06:44:52Z by qwen-code-dev-bot) reports the identical 7 failures on main itself. That confirms the base is red independently of this PR, so the fix belongs there.

Review disposition at c9a801e: the five correctness/compatibility findings from the last round are fixed and their threads are resolved. I checked the remaining suggestions against the current head; none reports a new production failure.

Already addressed in this PR: R1-35 (user/system/system-defaults are named in both designs), R1-11 (the user guide now distinguishes operator conflicts from workspace/project overrides and warns about extension shadowing), and R1-31 (both designs and the user guide explain worktree scope changes). These threads can be closed without more code.

Outside this bounded contract: R1-8 would require a separately verified Hologres wire preset. The default mem0-v2 ID is explicitly PolarDB-style, not a promise of universal V2 compatibility. I am leaving Hologres protocol work outside this PR.

Non-blocking regression coverage deferred to a focused follow-up PR after merge, not silently treated as implemented:

• Child/startup: R1-14 (child entry point), R1-15 (activation gates), R1-44 (hooks-off write gate), R1-45 (tier explanation), R1-17 (runtime fallback), R1-3 at both boot and hooks-reload call sites.
• Config and protocol: R1-4 (base URL character check), R1-5 (unsafe URL inputs), R1-22 (loopback HTTP), R2-6 (non-HTTP scheme), R1-25 (protocol aliases), R1-39 (binding envelope).
• Hooks and provenance: R1-24 (scope pass-through), R1-47 (same-matcher user hook), R1-21 (PowerShell payload), R2-2 at both identity-guard test locations.
• Scope/package/result: R1-16 (home hash input), R1-48 (symlink canonicalization), R1-18 (standalone archive), R2-3 (multi-message direct import).

This is a late review round, so I am not expanding #12891 with another test matrix. The implementation guards remain present; build, typecheck and 847 focused tests passed on the pushed head. Native Windows remains unrun here, though both Windows-shaped artifact regressions were mutation-proven locally. The current CI snapshot has no failure, with core jobs still running; I will treat any PR-caused failure as actionable rather than calling pending checks green.

@qwen-code /triage