Reference Agent

What this is

@nunchiai/reference-agent is the AMCP reference client for Nexus.

This is not a general-purpose coding agent. It is a thin, inspectable CLI that demonstrates how an AMCP-native client should:

• recall relevant memory before a task
• remember durable outcomes after a task
• soft-delete transient working memory
• export and import portable memory
• expose every memory action through --amcp-trace

What it demonstrates

• two-pass recall
• policy-driven remember
• soft delete of transient working memory
• export/import portability
• session lifecycle visibility
• --amcp-trace observability
• OpenAI-compatible BYOK operation

Quick Start

Published package:

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

Global install:

npm install -g @nunchiai/reference-agent
amcp-agent --help

Monorepo workspace:

npm run build -w packages/reference-agent
npm exec --workspace packages/reference-agent -- amcp-agent --help

For a real task run:

export NEXUS_URL=https://nexus-api-production-4177.up.railway.app
export NEXUS_API_KEY=...
export OPENAI_API_KEY=...
npx -y -p @nunchiai/reference-agent@latest \
  amcp-agent task "Inspect packages/reference-agent/README.md and summarize it." --amcp-trace

Successful task output looks like:

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

Common task 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.

Commands

amcp-agent task "inspect auth flow"
amcp-agent memory ls
amcp-agent memory rm <id> --project-id <project-id>
amcp-agent memory export --out memories.json
amcp-agent memory import memories.json
amcp-agent session close
amcp-agent compliance

Environment

Copy .env.example and provide:

• OPENAI_API_KEY or LLM_API_KEY
• LLM_MODEL
• NEXUS_URL
• NEXUS_API_KEY

Optional:

• LLM_BASE_URL
• NEXUS_READ_ONLY_API_KEY
• AMCP_TRACE=true
• AMCP_USER_SCOPE_ID

OpenAI-compatible providers can be used by setting:

• LLM_BASE_URL
• OPENAI_API_KEY or LLM_API_KEY
• LLM_MODEL

task requires a real OpenAI-compatible model key. compliance does not require a model key.

AMCP Compliance

Run from the monorepo root:

npm exec --workspace packages/reference-agent -- amcp-agent compliance

or:

npm run compliance -w packages/reference-agent

Published package:

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

Required env for compliance:

• NEXUS_URL
• NEXUS_API_KEY
• NEXUS_READ_ONLY_API_KEY

Expected success output:

PASS remember
PASS recall
PASS delete_denied
PASS soft_delete
PASS export_import_roundtrip
AMCP_COMPLIANCE_OK
AMP_COMPLIANCE_OK

Common compliance failure output before NEXUS_READ_ONLY_API_KEY is set correctly:

FAIL delete_denied: NEXUS_READ_ONLY_API_KEY is required for delete_denied compliance.

Current Notes

• Session continuity is represented with origin.session_id.
• The current live AMCP server may not expose every client-managed session as a server session record, so the session recall pass safely falls back to an empty result when needed.
• memory ls is recall-based in the first slice. It does not use a separate list endpoint.
• Compatibility aliases remain available:
  • amp-agent
  • --amp-trace
  • AMP_TRACE
  • AMP_USER_SCOPE_ID