Claude Code Nucleus

A Claude Code Nucleus gives Claude Code durable, task-relevant repository memory through Neutron AI. It recalls a compact context capsule before work starts and stores only reviewed, reusable outcomes after verification.

Claude Code's CLAUDE.md, project rules, and local auto memory remain useful instruction layers. Neutron complements them with shared, scoped memory that can cross sessions, machines, and authorised agent hosts without copying an entire codebase into every prompt.

Recommended topology

Reuse one Code Nucleus for the repository unless policy requires hard isolation. Keep shared codebase facts separate from Claude-specific task outcomes.

The same repository Nucleus can also serve Codex, Google Gemini, GitHub Copilot, Cursor, and Windsurf. Use each provider's dedicated guide rather than applying Claude Code configuration to another host.

Step 1: Create or reuse a Code Nucleus

Create one Nucleus named after the repository, or reuse the Nucleus already serving another coding agent. Generate a Nucleus access token for day-to-day agent access rather than using a workspace key.

export NEUTRON_API_URL="https://neutronai.dev/api"
export NEUTRON_API_TOKEN="<nucleus-access-token>"
export NEUTRON_NUCLEUS_ID="<nucleus-id>"

Store these values in your shell profile, secret manager, CI secret store, or agent host. Never commit the token or place it in CLAUDE.md, .mcp.json, logs, screenshots, or issues.

Step 2: Add Claude Code instructions

Add a short, public-safe block to the repository's CLAUDE.md. If the repository already uses AGENTS.md, Claude Code can import it instead of duplicating shared instructions.

@AGENTS.md

## Neutron AI Code Nucleus

Before editing, request Neutron context for the smallest relevant repo, package,
service, infrastructure, test, and `agent:claude-code` scope set.

- Treat returned context as supporting context, not a replacement for reading files.
- Never send secrets, credentials, customer data, hidden prompts, or private reasoning.
- Run the required checks for every changed surface.
- After verification, remember only safe outcomes and reusable lessons in
  `agent:claude-code`.

Omit @AGENTS.md when the repository does not have that file. Keep hard security boundaries in permissions and policy; instruction files guide behaviour but do not enforce authorisation.

Step 3: Connect the Neutron MCP server

Claude Code supports project-scoped remote HTTP MCP servers through .mcp.json. Commit the endpoint configuration with an environment-variable reference, never a literal token:

{
  "mcpServers": {
    "neutron-memory": {
      "type": "http",
      "url": "https://mcp.neutronai.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${NEUTRON_API_TOKEN}"
      }
    }
  }
}

Claude Code asks users to approve project-scoped MCP servers. Review the endpoint before approving it, then verify the connection:

claude mcp list

Inside Claude Code, run /mcp and confirm neutron-memory is connected. Start with read tools:

• memory_agent_context
• memory_recall

Enable memory_remember or memory_reflect only for trusted hosts with a reviewed write-back policy. Keep forget, compaction, invalidation, and Nucleus control-plane tools disabled or approval-gated unless the workflow explicitly requires them.

Step 4: Request context before editing

Ask Claude Code to call memory_agent_context with the current Nucleus, a bounded task, and only the relevant scopes.

{
  "nucleusId": "neutron-code",
  "scopeIds": [
    "repo:root",
    "service:edge-api",
    "tests:edge-api",
    "agent:claude-code"
  ],
  "agentId": "agent:claude-code",
  "task": "Plan a safe change to Nucleus authentication.",
  "tokenBudget": 1200
}

The context capsule should narrow the files, tests, architecture notes, and safety constraints to inspect. Claude must still read every file it edits and verify current code rather than trusting stale memory.

If MCP is not available in the current host, use the equivalent REST request:

curl "$NEUTRON_API_URL/v1/memory/agent-context" \
  -H "authorization: Bearer $NEUTRON_API_TOKEN" \
  -H "content-type: application/json" \
  -d "{\
    \"nucleusId\": \"$NEUTRON_NUCLEUS_ID\",\
    \"scopeIds\": [\"repo:root\", \"agent:claude-code\"],\
    \"agentId\": \"agent:claude-code\",\
    \"task\": \"Map the files and tests for this change.\",\
    \"tokenBudget\": 1200\
  }"

Step 5: Write back reviewed outcomes

After tests pass, store a short outcome in agent:claude-code.

neutron remember \
  --scope agent:claude-code \
  --type tool_lesson \
  --text "Authentication route changes require targeted route tests, token-scope checks, and a production health request after deployment."

Good outcomes include files changed, checks run, failures corrected, deployment notes, and reusable architecture or security lessons. Do not store raw prompts, model scratchpads, chain-of-thought, access tokens, session cookies, customer payloads, or unreviewed sensitive reflections.

Keep context fresh

Refresh repository memory when the commit SHA, instruction files, package manifests, routes, runtime configuration, infrastructure, tests, or security policies change. Tombstone deleted memories and never allow an archive, queue, or compaction job to restore them.

Claude Code references

• How Claude remembers your project
• Connect Claude Code to tools through MCP

The operating loop stays simple: recall before edits, inspect the source, verify the change, then remember only what will safely help a future task.