@nexus-catalyst/cc-plugin

Automatic memory for Claude Code. Nexus-Catalyst recalls relevant context before every prompt and stores each turn — no manual tool calls, no CLAUDE.md instructions required.

How it works

The plugin registers two hooks in ~/.claude/settings.json:

| Hook | Trigger | What it does | |------|---------|--------------| | UserPromptSubmit | Before the model sees your prompt | Queries NC for relevant memories, injects a <nc-context> block into the model's context | | Stop | After each turn completes | Sends the last user prompt + assistant response to NC for storage |

Memory flows automatically every turn. Your existing hooks are never touched.

Prerequisites

• Node.js 18+
• A Nexus-Catalyst account — sign up at nexus-catalyst.com
• A Plugin API key from app.nexus-catalyst.com → Account → API Keys

Install

npm install -g @nexus-catalyst/cc-plugin
nc-cc install
nc-cc set-key "nc_pk_live_..."

Verify:

nc-cc status

That's it. Start a Claude Code session — memory is now automatic.

The key is saved to ~/.nexus-catalyst/config.json (shared across all NC tool plugins) and mirrored into ~/.claude/settings.json so Claude Code passes it to hook processes automatically. No shell export needed. One key works across all NC tool plugins (cc, Cursor, Codex, Gemini) — set it once, all plugins read from the same place.

Commands

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

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | NC_PLUGIN_API_KEY | Yes | — | Your NC plugin key (nc_pk_live_...). Set via nc-cc set-key. | | NC_API_BASE_URL | No | https://mcp.nexus-catalyst.com | Overrides the NC endpoint. Leave unset. | | NC_MAX_RESULTS | No | 5 | Max memories injected per turn | | NC_HOOK_DEBUG | No | — | Set to any value to enable debug logging to /tmp/nc-hook-debug.log | | NC_HOOK_DISABLE | No | — | Set to 1, true, yes, or on to disable all hooks (no recall, no persona, no store) | | NC_HOOK_SUPPRESS_PERSONA | No | — | Set to 1, true, yes, or on to recall and inject memories but omit the persona/role line |

What the injected context looks like

When relevant memories exist, the UserPromptSubmit hook prepends this block before the model processes your prompt:

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

Relevant memories from prior sessions:

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

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

The model sees this before it processes your prompt — no extra steps on your end.

Behavior details

• Short prompts skipped: Prompts under 75 characters skip recall (avoids noise from "yes", "looks good", etc.)
• Silent on missing key: If NC_PLUGIN_API_KEY is not set, both hooks exit immediately without error — nothing breaks
• Settings backup: Before every write to settings.json, a backup is created at settings.json.nc-backup
• Uninstall is surgical: nc-cc uninstall removes only NC-owned entries, identified by an internal __nc_plugin__ marker

Debug mode

NC_HOOK_DEBUG=1 nc-cc status

With NC_HOOK_DEBUG set, hook scripts append timestamped logs to /tmp/nc-hook-debug.log. Useful for verifying recall results and timing without starting a full session.

To test hooks directly without Claude Code:

# Test recall
echo '{"prompt":"how do I add a new route?","cwd":"/your/project"}' \
  | NC_PLUGIN_API_KEY="your-key" node $(npm root -g)/@nexus-catalyst/cc-plugin/dist/hooks/user-prompt-submit.js

# Test store
echo '{"cwd":"/your/project","transcript":[{"role":"user","content":"test prompt"},{"role":"assistant","content":"test response"}]}' \
  | NC_PLUGIN_API_KEY="your-key" node $(npm root -g)/@nexus-catalyst/cc-plugin/dist/hooks/stop.js

Uninstall

nc-cc uninstall

Removes the two NC hook entries from ~/.claude/settings.json. All other hooks remain untouched. You can also remove the npm package:

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

Source

Part of the Nexus-Catalyst/cli-hooks monorepo. The hook scripts are open source (MIT — see LICENSE). The memory service requires an NC account.