npm package: @nunchiai/reference-agent
Description: AMCP reference client implementation for Nexus
Latest version: 0.2.1

# 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:

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

Global install:

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

Monorepo workspace:

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

For a real task run:

```bash
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:

```text
[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:

```text
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

```bash
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:

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

or:

```bash
npm run compliance -w packages/reference-agent
```

Published package:

```bash
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:

```text
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:

```text
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`