Nexus Docs

MCP, Hosted API, and AMCP Surface

Nexus is the AMCP-compatible Agent Memory MCP/admin surface powered by Nunchi AI. This page covers hosted setup, personal local mode, MCP install, AMCP endpoints, export/import, and runtime verification.

Hosted API Base

https://nexus-api-production-4177.up.railway.app

MCP Server Package

@nunchiai/nexus-mcp

Install Coverage

16 clients (14 auto + 2 manual)

On this page

1) What ships today 2) Before you start 3) Choose your mode 4) AMCP API surface 5) MCP workflow 6) Core use cases 8) Session handoff 15) Hosted API examples 16) Reference agent CLI 19) Error semantics

1) What Nexus ships today

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.

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.

2) Before you start

1. Hosted Nexus always starts with API-key issuance at /settings/api-keys.
2. Use Node.js 18+ (npx required).
3. Fully quit all running agent apps before setup, including Codex, Claude, Cursor, Windsurf, VS Code, Zed, and similar clients.
4. Reopen the agent only after setup completes.
5. Trial Cloud, Nexus Free, and Nexus Pro currently allow only one active API key under the current rollout policy. Revoke or delete the old key before issuing a new one.

3) Choose your mode

Use hosted mode when you want cloud memory with an issued API key. Use Nexus Free when you want free local SQLite memory with one-time device activation.

recommended Local Lite flow

# local sqlite memory
npx -y @nunchiai/nexus-mcp init --all --local --yes
npx -y @nunchiai/nexus-mcp activate --key sk_write_your_key --gateway-url https://gateway.nunchiai.com

Local Lite keeps memory on local SQLite and uses the issued key once to fetch a signed license.

New Local Lite activations are bound to the first device that runs activate --key. The same API key cannot activate an additional device.

For Trial Cloud, Nexus Pro, or Nunchi Team, use regular init with --key instead of --local.

recommended hosted flow

# hosted memory
npx -y @nunchiai/nexus-mcp init --client codex,gemini-cli --key sk_write_your_key --gateway-url https://gateway.nunchiai.com --yes
npx -y @nunchiai/nexus-mcp init --list

Codex uses Nexus through MCP. Do not set OPENAI_BASE_URL for Codex.

4) AMCP API surface

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.

POST /v1/amcp/remember
POST /v1/amcp/recall
GET /v1/amcp/sessions
POST /v1/amcp/export
POST /v1/amcp/import
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/*.

5) MCP workflow

This is the fastest way to keep coding conventions aligned across clients while using Nexus as the shared memory layer.

sync curated rule files into Nexus

# push local rule files (.cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/*, ...)
npx -y @nunchiai/nexus-mcp sync

# preview only (no write)
npx -y @nunchiai/nexus-mcp sync --dry-run

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

6) Core use cases

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.

Save decisions explicitly

After a product, billing, architecture, or infra decision, tell the agent to save it to Nexus so the same choice does not need to be rediscovered later.

example prompt

Save this in Nexus as a decision:
"Codex now follows the 0.4.8 setup path. Gateway passthrough is still not the default."

Save bug causes and fixes

When a root cause is found, store it once as an error memory so future sessions can recall it instead of repeating the investigation.

example prompt

Save this in Nexus as an error:
"Public plan login 404 came from /en/en/login. Locale was being prefixed twice."

Recall project context at session start

At the start of a new agent session, ask for recent decisions, constraints, or conventions before continuing work.

example prompt

Recall the recent Nexus context for billing and deployment before you continue.

Store reusable rules and conventions

Use sync for file-based rules, then ask the agent to remember small conventions that are not already documented in files.

example prompt

Save this in Nexus as a convention:
"Use Current Plan for the active plan card and Choose Plan for non-active paid tiers."

7) How to tell the agent to save

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:

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

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

8) Session handoff pattern

Before ending a session

Ask the agent to save the outcome, the key decision, and the main unresolved risk. This gives the next session a clean checkpoint.

end-of-session prompt

Before you finish, save the final fix, the reason behind it, and any remaining risk in Nexus.

At the next session start

Ask the next agent to recall the recent Nexus context first. This works whether you switched from Codex to Cursor, from Claude Code to Gemini CLI, or simply started a fresh session.

start-of-session prompt

Recall the recent Nexus context for this project before you continue. Focus on decisions, errors, and unresolved items.

9) Non-interactive commands

non-interactive commands

# local_lite: configure all detected clients for local SQLite
npx -y @nunchiai/nexus-mcp init --all --local --yes
npx -y @nunchiai/nexus-mcp activate --key sk_write_your_key --gateway-url https://gateway.nunchiai.com

# cloud tiers (trial_cloud / cloud_pro / team): configure selected clients only
npx -y @nunchiai/nexus-mcp init --client codex,cursor,gemini-cli --key sk_write_your_key --gateway-url https://gateway.nunchiai.com --yes

# inspect detection only
npx -y @nunchiai/nexus-mcp init --list

# preview changes without writing files
npx -y @nunchiai/nexus-mcp init --all --local --dry-run

# remove nexus-mcp config from all clients
npx -y @nunchiai/nexus-mcp init --remove --all --yes

10) API key vs local activation

Local Lite (free single-device mode): run npx -y @nunchiai/nexus-mcp init --all --local --yes, then npx -y @nunchiai/nexus-mcp 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, Nexus Free, and Nexus 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.

11) Supported agents

Client	Setup	Notes
Claude Code	Auto	claude mcp add/remove command
Claude Desktop	Auto	mcpServers JSON
Cursor	Auto	mcpServers JSON
Windsurf	Auto	mcpServers JSON
Cline	Auto	mcpServers JSON
Roo Code	Auto	mcpServers JSON
Kilo Code (IDE)	Auto	mcpServers JSON
Kilo Code (CLI)	Auto	mcp JSON key format
OpenCode	Auto	mcp JSON key format
Gemini CLI	Auto	.gemini/settings.json or ~/.gemini/settings.json
Codex	Auto	TOML mcp_servers format
VS Code + Copilot	Auto	mcp.servers JSON format
Amazon Q CLI	Auto	mcpServers JSON
Zed	Auto	context_servers JSON format
Antigravity	Manual	User/mcp.json; current desktop builds may emit MCP_SERVER_INIT_ERROR
JetBrains IDEs	Manual	Import from Claude in settings

12) Runtime verification status

Setup support and runtime verification are different. The table below reflects current tested reality.

Client	Config support	MCP runtime	Gateway passthrough
Codex	Auto	MCP verified	Not verified
Claude Code	Auto	MCP verified	Not verified
Cursor	Auto	MCP verified	Not verified
Claude Desktop	Auto	Connected log verified	Not verified
Windsurf	Auto	Connected log verified	Not verified
Kilo Code (CLI)	Auto	MCP verified	Not verified
OpenCode	Auto	MCP verified	Not verified
Gemini CLI	Auto	MCP connected; local extensions/hooks may interfere	Not verified
Kilo Code (IDE)	Auto	Config written; runtime not verified	Not verified
VS Code + Copilot	Auto	Config written; runtime not verified	Not verified
Zed	Auto	Config written; runtime not verified	Not verified
Antigravity	Manual	Init error observed in current desktop build	Not supported
JetBrains IDEs	Manual	Import flow only; runtime not verified	Not verified

13) Manual setup (Antigravity, JetBrains)

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 Code setup is completed first (~/.claude.json has nexus-mcp).
2. In JetBrains: Settings > Tools > MCP Server > Import from Claude.
3. Restart the IDE and verify Nexus tools are visible.

14) Codex fallback (manual TOML)

Use this only when automatic init is unavailable.

codex fallback (Local Lite)

[mcp_servers.nexus-mcp]
command = "npx"
args = ["-y", "@nunchiai/nexus-mcp"]

[mcp_servers.nexus-mcp.env]
NEXUS_STORAGE = "local"
NEXUS_AGENT_NAME = "codex"

15) Hosted API examples

remember

curl -X POST https://gateway.nunchiai.com/v1/amcp/remember \
  -H "Authorization: Bearer sk_write_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "Auth flow uses PKCE",
        "type": "decision",
        "scope": { "kind": "project", "id": "acme-web" }
      }
    ]
  }'

recall

curl -X POST https://gateway.nunchiai.com/v1/amcp/recall \
  -H "Authorization: Bearer sk_write_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "auth decisions",
    "scope": { "kind": "project", "id": "acme-web" },
    "token_budget": 2000,
    "depth": "deep"
  }'

export / import / delete

POST /v1/amcp/export
{
  "scope": { "kind": "project", "id": "acme-web" },
  "format": "json"
}

POST /v1/amcp/import
{
  "items": [ ... ]
}

DELETE /v1/amcp/memories/:id?scope[kind]=project&scope[id]=acme-web

native routes still available

POST /v1/memory/ingest
POST /v1/memory/hydrate
GET  /v1/memory/sessions
GET  /v1/memory/stats

16) Reference agent CLI

Nexus now publishes a thin AMCP reference client package. Use it when you want to verify the hosted memory lifecycle with a real CLI instead of wiring your own client first.

published package

npx -y -p @nunchiai/reference-agent@latest amcp-agent --help

export NEXUS_URL=https://gateway.nunchiai.com
export NEXUS_API_KEY=sk_write_your_key
export OPENAI_API_KEY=your_model_key

npx -y -p @nunchiai/reference-agent@latest \
  amcp-agent task "Inspect this repo and summarize the auth flow." --amcp-trace

published compliance check

export NEXUS_URL=https://gateway.nunchiai.com
export NEXUS_API_KEY=sk_write_your_key
export NEXUS_READ_ONLY_API_KEY=sk_read_your_key

npx -y -p @nunchiai/reference-agent@latest amcp-agent compliance

successful output shape

[AMCP] session     start ...
[tool] read_file  ...
[AMCP] remember    scope=project  "Session summary: ..."
[AMCP] session     close ... transient_deleted=1
<final natural-language summary>

PASS remember
PASS recall
PASS delete_denied
PASS soft_delete
PASS export_import_roundtrip
AMCP_COMPLIANCE_OK
AMP_COMPLIANCE_OK   # compatibility alias marker

common failure output

LLM_API_KEY looks like a Nexus API key. Set a real OpenAI-compatible model key in OPENAI_API_KEY or LLM_API_KEY.

FAIL delete_denied: NEXUS_READ_ONLY_API_KEY is required for delete_denied compliance.

17) Export / import and delete semantics

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.

18) Tool execution semantics (important)

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.

19) Error semantics

Code	Meaning	Action
401	Invalid or revoked key	Rotate key and re-run init
402	Plan or usage limit reached	Upgrade or wait next cycle
422	Invalid schema	Fix payload
5xx	Service issue	Retry with backoff and alert ops