MCP, Hosted API, and AMCP Surface

Hosted memory API: remember, recall, sessions, export/import, and delete are available on the current AMCP surface.

MCP server: one-command setup is available for supported clients, with Local Lite and hosted modes separated clearly.

Lifecycle hooks: the current validated release (v0.4.12) installs a shared auto-save hook script plus client-specific hook config for supported targets unless you pass --no-hooks.

Reference implementation: Nexus is positioned as a memory layer and reference server, not as a general-purpose agent product.

Verification: client config support, MCP runtime verification, and hosted gateway/API verification are tracked separately.

Support boundary: the official baseline is CLI-first. Desktop and IDE variants may be config-compatible, but they are not presented as equally verified unless runtime checks were completed.

Nexus setup guidance lives on this page, but the protocol itself now has a separate public page. Use it when you want the canonical public draft for AMCP without the rest of the MCP and product-install material.

It covers the protocol purpose, canonical record shape, current HTTP surface, auth scopes, delete semantics, portability, and reference implementation status.

Nexus uses a two-layer auto-save architecture:

• Layer 1 — Lifecycle Hooks: deterministic shell-script hooks that fire on agent stop/response events, sending final-response text to /v1/memory/ingest as context memory.
• Layer 2 — MCP Tools: agent-driven structured saves via nexus_remember for decision, task, error, and other typed memory.

init installs a shared hook script at ~/.nexus/hooks/nexus-autosave.sh and wires client-specific hook config for supported targets.

Verified hook targets: claude-code (Stop), cursor (stop), windsurf (post_cascade_response), codex (notify), gemini-cli (AfterAgent), vscode-copilot (Stop).

opencode and kilo-cli do not support hooks in their current config schema.

The current public direction is an AMCP surface layered over the existing Nexus memory system. You can use MCP through supported clients or call the hosted API directly.

• 1. POST /v1/amcp/remember
• 2. POST /v1/amcp/recall
• 3. GET /v1/amcp/sessions
• 4. POST /v1/amcp/export
• 5. POST /v1/amcp/import
• 6. DELETE /v1/amcp/memories/:id

Native /v1/memory/* routes still exist underneath. Legacy /v1/amp/* routes remain available only as compatibility aliases. The canonical public protocol surface is /v1/amcp/*.

Sync stores each rule file as convention memory atoms. After sync, recall/generate can apply those conventions in any connected agent.

Nexus becomes most useful when your session changes, your agent changes, or you come back to the same project later. Instead of re-explaining the same decisions, failures, and conventions, you can tell the next agent to recall them first.

Typical moments where this pays off:

• 1. You close Codex today and continue tomorrow in Claude Code.
• 2. You debug a billing issue in one agent, then continue implementation in another.
• 3. A long thread ends and a new session starts with less context.
• 4. You want the next agent to inherit project-specific conventions without repeating them manually.

The simplest pattern is to tell the agent directly to save something in Nexus. Do not type the raw MCP function syntax unless your client specifically exposes it.

This is especially useful right before ending a session, switching to another agent, or handing work off to a teammate.

Good examples:

• 1. Save this in Nexus as a decision.
• 2. Remember this bug cause in Nexus.
• 3. Store this as project context in Nexus.
• 4. Before you finish, save the final fix in Nexus.

If the agent is correctly connected, it should execute nexus_remember for you.

Local Lite (recommended for solo use): run npx -y @nunchiai/nexus-mcp@latest init --all --local --yes, then npx -y @nunchiai/nexus-mcp@latest activate --key sk_write_... --gateway-url https://nexus-api-production-4177.up.railway.app.

Cloud tiers: pass --key sk_write_... to init for connected MCP clients, including Codex.

Trial Cloud, Local Lite, and Cloud Pro currently allow only one active API key under the current rollout policy. Revoke or delete the current key before reissuing.

Local Lite stores its signed license in ~/.nexus/license.json. Cloud init stores reusable values in ~/.nexus.env.

Local Lite binds that signed license to the first activated device fingerprint. To move devices, delete the old key in /settings/api-keys, issue a new key, and activate again on the new device.

Search engine in Local Lite: Local Lite does not run a local embedding model. It uses local SQLite FTS search plus lightweight scoring. Cloud memory is the mode that provides server-side embedding and vector retrieval.

Antigravity

Add Nexus MCP manually. The persisted config path is ~/Library/Application Support/Antigravity/User/mcp.json.

• 1. command: npx
• 2. args: -y @nunchiai/nexus-mcp
• 3. Local Lite: NEXUS_STORAGE=local
• 4. Cloud mode only: NEXUS_API_URL=https://nexus-api-production-4177.up.railway.app and NEXUS_API_KEY=your issued key
• 5. NEXUS_AGENT_NAME: antigravity

Current desktop builds may still fail third-party MCP init with MCP_SERVER_INIT_ERROR. Verify tool visibility before relying on it.

JetBrains IDEs

• 1. Make sure Claude setup is completed first (~/.claude/settings.json has nexus-mcp).
• 2. In JetBrains: Settings > Tools > MCP Server > Import from Claude.
• 3. Restart the IDE and verify Nexus tools are visible.

Export/import is part of the portability story. Current delete behavior is soft delete, which excludes deleted memory from normal recall without claiming immediate hard purge semantics.

This matters when moving memory between systems, replaying context into another environment, or building reference-agent handoff flows.

Typing nexus_remember as plain text does not store memory. Memory is stored only when your agent executes the MCP tool call.

Verify by running nexus_stats, nexus_sessions, or nexus_recall after remember.