Claude Code Setup

Connect Claude Code to Nexus-Catalyst for persistent memory across every coding session. There are two integration methods — use both for the best experience, or start with the plugin for zero-configuration setup.

Method	How it works	Best for
Hook Plugin (recommended)	Automatic — fires on every prompt/turn	Always-on memory with no manual steps
MCP Server	Manual — model calls NC tools when needed	In-session tool access, persona switching, memory search

---

Method 1: Hook Plugin (Automatic Memory)

The @nexus-catalyst/cc-plugin registers two hooks in your Claude Code settings. Memory recall and storage happen automatically every turn — no instructions to the model, no CLAUDE.md entries required.

Prerequisites

• Node.js 18+
• Nexus-Catalyst account — start a 14-day trial, or use your invitation if you have one
• Plugin API key — generate one in the app under Account → API Keys (app.nexus-catalyst.com/dashboard/account)

Install

# Terminal — install the hook plugin
npm install -g @nexus-catalyst/cc-plugin
nc-cc install

Add your key to your shell profile (~/.zshrc, ~/.bashrc, etc.):

# ~/.zshrc or ~/.bashrc
export NC_PLUGIN_API_KEY="your-plugin-key"

Verify the installation:

nc-cc status
# ✓ Installed — UserPromptSubmit (recall) and Stop (store) hooks active
# NC_PLUGIN_API_KEY: (set)

That’s it. Start a Claude Code session and memory flows automatically.

What happens each turn

Before your prompt reaches the model, the recall hook fires:

1. Sends your prompt text and working directory to NC
2. NC returns the most relevant memories from your prior sessions
3. The model receives your prompt with a <nc-context> block prepended:

<nc-context>
→ Call get_persona_definition('jack') for backend architecture and systems design

Relevant memories from prior sessions:

- [a1b2c3d4] Switched auth to JWT RS256 after the HS256 incident in March
- [e5f6g7h8] Rate limiter is in src/middleware/rate-limit.ts, uses Redis sliding window

→ call get_memory_detail('<id>') for full context on any memory above
</nc-context>

After each turn completes, the store hook fires and saves the exchange to NC automatically.

Plugin commands

nc-cc install      # Register hooks in ~/.claude/settings.json
nc-cc uninstall    # Remove NC hooks (leaves all other hooks intact)
nc-cc status       # Check installation state and API key

Environment variables

Variable	Required	Default	Description
NC_PLUGIN_API_KEY	Yes	—	Your NC plugin key. Missing = hooks skip silently.
NC_API_BASE_URL	No	https://mcp.nexus-catalyst.com	Override for staging
NC_MAX_RESULTS	No	5	Max memories injected per turn
NC_HOOK_DEBUG	No	—	Enable debug log at /tmp/nc-hook-debug.log

Uninstall

nc-cc uninstall
npm uninstall -g @nexus-catalyst/cc-plugin

---

Method 2: MCP Server (In-Model Tool Access)

The MCP integration gives the Claude Code model direct access to NC tools — recall_context, store_context, get_memory_detail, get_persona_definition, and more. Use this alongside the hook plugin for full control, or on its own if you prefer explicit memory management.

Configure the MCP server

The NC MCP server uses OAuth — you sign in with your Nexus-Catalyst account in the browser. There is no API key to copy.

Add the server via the CLI:

claude mcp add --transport http nexus-catalyst https://mcp.nexus-catalyst.com

Then authenticate inside a Claude Code session:

/mcp
# Select nexus-catalyst → Authenticate
# Your browser opens — sign in with your NC account and approve access

Verify the connection

claude mcp list
# nexus-catalyst: https://mcp.nexus-catalyst.com (HTTP) - ✓ Connected

If it shows “needs authentication”, run /mcp in a session and complete the browser sign-in.

Available tools

Once connected, the model can call these tools:

Tool	What it does
recall_context	Search your memories by query and workspace
store_context	Save a memory manually
get_memory_detail	Fetch full content of a memory by ID
get_persona_definition	Load a named persona (Jack, Betty, Nora, etc.)
search_memories	Full-text search across all your memories

See the MCP Tools Reference for full parameter docs.

---

Note

Connect Claude Code to tools via MCP covers the client side of MCP in more depth than this page does.

Using both methods together

The hook plugin and MCP server complement each other:

• Plugin: Handles automatic recall and storage on every turn — you never think about it
• MCP: Lets the model go deeper when needed — drill into a specific memory, switch personas mid-session, or manually store something important

There’s no conflict. The plugin fires at the OS level before the model processes anything; MCP tools are called by the model during its reasoning loop.

---

Troubleshooting

Hooks not firing

1. Run nc-cc status — check both hooks are listed as active
2. Verify NC_PLUGIN_API_KEY is set in your shell: echo $NC_PLUGIN_API_KEY
3. Enable debug logging: NC_HOOK_DEBUG=1 and check /tmp/nc-hook-debug.log

No memories appearing

• Very short prompts (under 10 characters) and short continuation replies like “yes, do that” (under 75 characters) skip recall by design — use a longer, specific query to test
• Check that memories exist in your NC dashboard
• Verify your workspace path is not toggled off in dashboard project settings

MCP connection or 401 errors

# Confirm the server is reachable (returns OAuth metadata)
curl https://mcp.nexus-catalyst.com/.well-known/oauth-protected-resource

If tools fail with 401, your OAuth session has expired — run /mcp in Claude Code and re-authenticate.

---

Need help? Common Issues · support@nexus-catalyst.com

Next: tell Claude Code to use it

Installing the hooks exposes the tools; it does not make the model call them. Put the MCP Instructions in your CLAUDE.md so recall and storage happen on their own.