MCP Quickstart

MCP is Zaxy's primary framework-neutral interface. Start with the default local path in the repository where you want memory captured:

zaxy init
zaxy memory bootstrap --eventloom-path .eventloom

zaxy init chooses the embedded local runtime by default. It writes local profile and capture files, checks the repo-local graph projection posture, and prints the exact client install command or config path. For Codex, the default zaxy init --codex-mcp-install auto path writes or reuses user-level MCP config when it can do so non-destructively, and falls back to the copyable codex mcp add command when it cannot. No Neo4j, Postgres, Docker, Bolt URI, graph password, or hosted service is required for the local MCP path. The durable data source remains .eventloom/; the embedded graph is a rebuildable projection of that log. Human output is compact by default; run zaxy init --verbose to show every setup step, optional check, fallback command, resume command, and note when debugging an install.

Client Setup

Use one local route per client. These commands keep the default embedded graph runtime and .eventloom/ source log; no sidecar service is required.

Codex

For Codex, the fastest route is the default init path:

zaxy init

That expands to:

zaxy init --codex-mcp-install auto

Auto mode writes or reuses user-level Codex MCP config when that is safe. If an existing mcp_servers.zaxy entry is different, it asks you to review that config before replacing it. If no safe config target exists, it prints the copyable codex mcp add command.

To force a direct user-level config merge, run:

zaxy init --codex-mcp-install user

This writes user-level Codex MCP config and keeps the MCP server workspace-neutral while resolving the current workspace at runtime. Restart Codex after init so it reloads the server list.

If you prefer not to let init write Codex config, force command mode and copy or run the printed command. The command shape is:

zaxy init --codex-mcp-install command
codex mcp add zaxy -- zaxy serve

If you need Zaxy to print the exact command with resolved executable and environment values:

zaxy ide-config codex --install --eventloom-path .eventloom

Claude Code

For Claude Code, install the project-local MCP config:

zaxy ide-config claude-code --install --workspace . --eventloom-path .eventloom

This writes .mcp.json in the current workspace. Use this route for trusted projects where the MCP server should travel with the repo.

Claude Desktop

For Claude Desktop, print the app-level JSON fragment and paste it into the Claude Desktop MCP config:

zaxy ide-config claude-desktop --eventloom-path .eventloom

Cursor

For Cursor, install the project-local MCP config:

zaxy ide-config cursor --install --workspace . --eventloom-path .eventloom

This writes .cursor/mcp.json in the current workspace.

Generic MCP

For a generic MCP client, configure a stdio server command:

zaxy serve --transport stdio

After installing the client config, start a fresh model session and ask the client to list available MCP tools. You should see memory_bootstrap, memory_checkout, memory_feedback, and the Coordinate tools. If the client does not show them, run zaxy doctor --eventloom-path .eventloom and inspect the generated MCP config before changing memory code.

Model Call Rhythm

memory_checkout is the front door: call it first, with the current task, before substantial work. At session start, call memory_bootstrap for awareness, then checkout. After using projected context, call memory_feedback so Zaxy can reinforce useful memory. Everything else is plumbing or power use; memory_capabilities is the discovery surface for the rest of the tool set. The experimental memory_feeling_of_knowing offers a ~1 ms pre-check of whether checkout would likely return anything for a query — a cheap hint before checkout, never a memory answer.

For roadmap, release, review, implementation, resume, and high-context questions, treat checkout as required before answering. Bootstrap is awareness; checkout is the current cited prompt state. When checkout returns warnings, unsupported context, stale state, or a required action, follow that guidance instead of treating old model context as authoritative.

The server lists the core profile by default (since 2.1.0): only the front-door verbs (memory_checkout, memory_append, memory_query, context_assemble, memory_feedback, memory_invalidate, memory_capabilities, memory_feeling_of_knowing) appear in the listing; every other tool stays callable by name, and memory_capabilities reports the available-but-unlisted set. To restore the full listing, serve with zaxy serve --profile full or set MCP_TOOL_PROFILE=full.

For multi-agent missions, use the coordination_* tools rather than plain append calls when recording worker findings. coordination_report_finding captures worker-local claims and evidence. coordination_review_finding, coordination_promote, and coordination_checkout keep accepted parent state separate from pending or conflicted worker-local findings.

Related references: README.md, MCP interface, MCP install targets, and Coordinate Quickstart.