Skip to content

Agent Host Compatibility

Nuzo should stay host-neutral.

The product is a local-first memory layer for AI agents. Codex and Claude Code are the first priority hosts because they are strong CLI-based agent environments and both support MCP-based extension paths.

Design Position

Nuzo should not depend on one agent runtime.

Nuzo core
  -> CLI for direct user control
  -> MCP server as the universal agent contract
  -> host packages for Codex, Claude Code, and future agent CLIs

Host packages may differ, but they must call the same MCP tools and core use cases.

All hosts also share the same recall trust boundary. Stored content is attributed memory data, not a host instruction, regardless of which host wrote or imported it. See Memory Trust Boundary.

When a host can identify a project, workspace, or profile boundary, its Nuzo MCP configuration should prefer an explicit authorized scope set. A shared administrator store remains possible for local CLI workflows, but repository-controlled agents should not receive unscoped access to unrelated memory by default.

Compatibility Principle

MCP is the stable center.

Every host integration should be judged by whether it can expose the existing Nuzo MCP server without changing memory behavior.

The public memory contract remains:

  • memory.remember
  • memory.recall
  • memory.recall_hook
  • memory.suggest_capture
  • memory.confirm_capture
  • memory.list
  • memory.show
  • memory.challenge
  • memory.relate
  • memory.relations
  • memory.unrelate
  • memory.update
  • memory.history
  • memory.audit
  • memory.forget
  • memory.forget_many
  • memory.export
  • memory.import
  • memory.doctor

Host-specific plugin systems are distribution wrappers, not memory engines.

Portable Memory Flow

Nuzo export/import belongs to Nuzo, not to a specific host.

Host plugins make the Nuzo tools available inside Codex, Claude Code, or another agent environment. The data format stays the Nuzo export format.

Codex + Nuzo plugin
  -> memory.export
  -> nuzo-memory-export JSON
  -> memory.import
  -> Claude Code + Nuzo plugin

The reverse flow should work the same way:

Claude Code + Nuzo plugin
  -> memory.export
  -> nuzo-memory-export JSON
  -> memory.import
  -> Codex + Nuzo plugin

When both hosts run on the same machine and point to the same store, export/import may not be needed. Both hosts can use the same Nuzo MCP server and local store directly:

Codex        \
              -> Nuzo MCP server -> ~/.nuzo/memory/memories.sqlite
Claude Code  /

For different machines, profiles, workspaces, or isolated stores, JSON export/import is the portability path.

Nuzo should not promise migration from private native memory stores unless the host exposes an official API or documented export format. The portable guarantee applies to memories created and managed through Nuzo.

Host Matrix

nuzo hosts exposes this support model from the CLI. It is read-only and separates managed setup from generic MCP compatibility and future validation candidates.

Support levels:

  • managed: nuzo setup can configure the host today.
  • manual-mcp: the host can use Nuzo when the user manually configures the stdio MCP server.
  • research: candidate for future validation; not a supported managed setup target yet.
Host Support level Current fit Extension path Nuzo package direction Notes
Codex managed Supported plugin target. Codex plugins bundle the Nuzo MCP server, skill, and command hooks for SessionStart and UserPromptSubmit. packages/codex-plugin Users must review and trust new or changed plugin hooks.
Claude Code managed Supported plugin target. Claude Code plugins bundle the same MCP server, skill, and lifecycle events. packages/claude-code-plugin Plugin enablement and hook state remain controlled by Claude Code.
Generic MCP host manual-mcp Compatible when the host can launch a local stdio MCP server. User-managed MCP configuration. packages/mcp-server Use nuzo-mcp-server; Nuzo should not mutate unknown host config.
OpenCode research Candidate for future validation. Start with manual MCP; add managed setup only after host config, permission, and lifecycle behavior are tested. No package until validated. Do not claim managed support yet.
Gemini CLI research Candidate for future validation. Start with manual MCP; add managed setup only after host config, permission, and lifecycle behavior are tested. No package until validated. Do not claim managed support yet.
Cursor research Candidate for future validation. Start with manual MCP; add managed setup only after host config, permission, and lifecycle behavior are tested. No package until validated. Do not claim managed support yet.
Windsurf research Candidate for future validation. Start with manual MCP; add managed setup only after host config, permission, and lifecycle behavior are tested. No package until validated. Do not claim managed support yet.
VS Code Copilot research Candidate for future validation. Start with manual MCP; add managed setup only after host config, permission, and lifecycle behavior are tested. No package until validated. Do not claim managed support yet.

Codex Notes

Codex plugins can bundle skills, app integrations, MCP servers, and lifecycle hooks. Nuzo uses MCP for agent tools and command hooks for deterministic context injection.

Codex MCP support includes:

  • stdio servers;
  • streamable HTTP servers;
  • server instructions;
  • user and project configuration through config.toml;
  • plugin-provided MCP servers.
  • plugin-provided SessionStart and UserPromptSubmit command hooks with additionalContext output.

Implications for Nuzo:

  • Codex plugin packaging should point to the Nuzo MCP server.
  • Plugin hooks should call the shared nuzo-memory-hook runner and remain read-only and fail-open.
  • Business logic must stay out of packages/codex-plugin.
  • Codex marketplace or sharing metadata should be added only after the plugin package is stable.
  • Local marketplace helpers are development convenience, not the primary product path.

Claude Code Notes

Claude Code supports plugins for reusable functionality across projects and teams. Plugins can include skills, agents, hooks, MCP servers, LSP servers, background monitors, binaries, and default settings.

Claude Code MCP support includes:

  • remote HTTP servers;
  • remote SSE servers, marked as deprecated in favor of HTTP where available;
  • local stdio servers;
  • remote WebSocket servers;
  • .mcp.json project configuration;
  • user and local MCP scopes;
  • plugin-provided MCP servers;
  • environment variables such as ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, and ${CLAUDE_PROJECT_DIR} inside plugin MCP config.

Implications for Nuzo:

  • A Claude Code package should use the same Nuzo MCP server.
  • The package is a thin plugin with .claude-plugin/plugin.json, .mcp.json, lifecycle hooks, and a host-specific skill.
  • Claude Code's direct claude mcp add path can remain documented as a manual setup path, but the primary direction is the supported plugin workflow.
  • Do not add Claude-specific memory behavior to core or MCP handlers.

Packaging Rules

Host packages may contain:

  • plugin manifests;
  • host-specific MCP config;
  • host-specific setup docs;
  • host-specific skill or instruction files when they improve discovery or usage;
  • lifecycle configuration that calls a shared Nuzo runtime entrypoint;
  • validation scripts for the host manifest.

Host packages must not contain:

  • memory storage logic;
  • recall ranking logic;
  • policy checks;
  • secret scanning;
  • import/export implementation;
  • host-specific versions of the MCP tool contract.

Host packages should expose Nuzo import/export actions when the host supports invoking MCP tools from the plugin. They should not create separate Codex or Claude export formats.

Runtime Distribution

Development plugin configs may resolve the built MCP server from the monorepo. Release artifacts must not.

For the MVP, generated Codex and Claude Code artifacts run a version-pinned @nuzo/memory package through npm exec. This avoids global installation and avoids shipping a platform-specific copy of the native SQLite dependency.

The authoritative decision is docs/adr/0006-host-plugin-runtime-distribution.md.

Naming Rules

Use neutral public language:

  • "AI agents";
  • "agent CLIs";
  • "Codex and Claude Code";
  • "MCP-compatible agents";
  • "host integrations".

Avoid positioning Nuzo as:

  • only a Codex plugin;
  • only a Claude plugin;
  • a replacement for built-in assistant memory;
  • a sync service by default.

Future Host Checklist

Before adding a new host package:

  1. Confirm the host supports MCP or a compatible tool protocol.
  2. Confirm whether the host has an official plugin/package mechanism.
  3. Confirm how local processes are launched and how environment variables are passed.
  4. Confirm where user-owned state should live.
  5. Confirm how the host handles permissions, approvals, and tool visibility.
  6. Confirm whether the host has lifecycle hooks or only direct MCP tool access.
  7. Confirm whether it can receive read-only session-start context without creating a silent write path.
  8. Add a dry-run setup plan and fixture tests before any host config mutation.
  9. Add docs that clearly distinguish managed setup from manual MCP usage.
  10. Keep the host package thin and route all memory behavior through MCP/core.

Source References

  • Codex manual, Model Context Protocol: Codex supports MCP servers in CLI and IDE extension.
  • Codex manual, Plugins: Codex plugins can bundle MCP servers.
  • Codex manual, Memories: Codex memories are built-in generated state under Codex home, which is separate from Nuzo's user-controlled local memory store.
  • Claude Code docs, Create plugins: plugins can extend Claude Code with skills, agents, hooks, and MCP servers.
  • Claude Code docs, MCP: plugin-provided MCP servers start with the plugin and can be defined in .mcp.json or inline in plugin.json.
  • Claude Code docs, MCP: direct MCP setup supports HTTP, stdio, WebSocket, scoped configuration, and project .mcp.json.