Codex Code Nucleus

A Code Nucleus is a repository memory bank for coding agents. It stores stable, scoped context about a codebase so Codex can inspect less, reason with better project context, and write back safe lessons after each task.

Use it for repo maps, package summaries, service contracts, test maps, deployment flows, coding standards, security rules, known bugs, migrations, and agent task outcomes.

What to create

Create one Nucleus per important repository or monorepo.

Recommended scopes:

Recommended memory types:

Step 1: Create the Nucleus

Open the Neutron AI platform and create a Nucleus named after the repository, for example neutron-code.

Choose placement based on your plan and data policy:

Copy the Nucleus ID and access token. Store the token as a local secret; do not commit it.

You can also create a Nucleus programmatically with a workspace API key:

curl "$NEUTRON_API_URL/v1/nuclei" \
  -H "authorization: Bearer $NEUTRON_WORKSPACE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "nucleusId": "neutron-code",
    "name": "neutron-code",
    "placement": { "mode": "global", "guarantee": "none", "notes": [] }
  }'

Workspace keys are for setup and can access Nuclei linked to the workspace. For day-to-day Codex, CLI, SDK, or MCP usage, rotate or copy a Nucleus access token and store it as a local secret.

Step 2: Configure the environment

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

For Codex, keep the token in your local shell profile, secret manager, or CI secret store. Do not put it in AGENTS.md, source code, screenshots, logs, or public issues.

If the repo uses the Codex plugin or sync helper, add a committed config file:

{
  "apiUrl": "https://neutronai.dev/api",
  "nucleusId": "neutron-code",
  "nucleusName": "neutron-code",
  "agentId": "agent:codex",
  "defaultScopes": ["repo:root", "agent:codex"],
  "recommendedScopes": [
    "repo:root",
    "package:<name>",
    "service:<name>",
    "infra:<provider>",
    "tests:<area>",
    "agent:codex"
  ],
  "envFile": "~/.config/neutron/codex-code-nuclei/neutron-code.env"
}

Commit .neutron/codex-code-nucleus.json; do not commit the env file. The env file should contain the three exports above.

Step 3: Try the public demos

The Neutron AI demo account includes two public-safe Nuclei:

Use them to validate the workflow before indexing a private repository.

1. Open the platform and select the neutron demo Enterprise workspace.
2. Open Nucleus and select Codex Demo or Neutron Codebase Demo.
3. Copy or rotate the Nucleus access token.
4. Set NEUTRON_API_TOKEN and NEUTRON_NUCLEUS_ID=neutron-codebase-demo locally.
5. Run a recall or context request with a coding task.

neutron recall \
  --scope repo:root,service:edge-api,infra:cloudflare,tests:edge-api,agent:codex \
  --query "Which files and tests should Codex inspect before changing Nucleus auth?"

You can also test the public HTTP demo directly:

curl https://neutronai.dev/v1/demo/codex/ask \
  -H "content-type: application/json" \
  -d '{"question":"How should Codex use AGENTS.md?"}'

curl https://neutronai.dev/v1/demo/code-nucleus/context \
  -H "content-type: application/json" \
  -d '{"question":"Plan a landing demo change"}'

Step 4: Seed repository context

Start with small, high-value memories. Keep each item scoped and durable.

npm install -g @neutron-ai/cli

neutron remember \
  --scope repo:root \
  --type project \
  --text "This monorepo contains a Cloudflare Worker API, Nuxt apps, SDK packages, docs, and research tooling."

neutron remember \
  --scope service:edge-api \
  --type knowledge \
  --text "The edge API owns memory routes, Nucleus routing, platform auth, billing checks, audit events, and MCP endpoints."

neutron remember \
  --scope tests:edge-api \
  --type procedural \
  --text "Run pnpm --dir services/edge-api build and targeted tests when changing API contracts."

For larger repositories, build a small indexing job that reads the repo, extracts file summaries and symbol summaries, then writes bounded memories into the right scopes.

For Codex repositories, the Neutron monorepo includes a reference sync script:

pnpm codex:nucleus:sync -- --dry-run
pnpm codex:nucleus:sync -- --root ../

It discovers repositories with both AGENTS.md and .neutron/codex-code-nucleus.json, reads each repo's env file when needed, writes bounded repo memories, and verifies agent-context. Keep this style of sync bounded: summarize structure, manifests, routes, tests, and safe lessons rather than uploading whole source files.

Step 5: Add Codex instructions

Add a short public-safe instruction block to the repository AGENTS.md.

## Neutron AI Code Nucleus

Before editing, request Neutron context for the relevant repo, service, package, infra, and test scopes.

Use:
- NEUTRON_API_URL
- NEUTRON_API_TOKEN
- NEUTRON_NUCLEUS_ID

For each task:
1. Recall context with the smallest relevant scope set.
2. Prefer cached context for stable repo facts.
3. Do not send secrets, private keys, tokens, or sensitive customer data.
4. After tests, remember safe task outcomes and reusable lessons.

Step 6: Plug Neutron into Codex

1. Create a Neutron workspace and Nucleus for the repository.
2. Generate one Nucleus access token for Codex.
3. Store the token in your local shell, CI secret store, or agent host secret manager.
4. Add the AGENTS.md instruction block above.
5. Before each task, request context from Neutron with the smallest relevant scope set.
6. Give Codex the returned context capsule as supporting context.
7. After verification, write back only safe task outcomes and reusable lessons.

If your Codex host supports local plugins, install the neutron-ai Codex plugin. It provides a global $neutron-ai skill plus helper commands for status, context, remember, init, and create-nucleus. The plugin reads .neutron/codex-code-nucleus.json and local env files, but it does not ship or store tokens.

Minimal shell setup:

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

Minimal context request:

curl "$NEUTRON_API_URL/v1/memory/agent-context" \
  -H "authorization: Bearer $NEUTRON_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "tenantId": "neutron-codebase-demo",
    "nucleusId": "neutron-codebase-demo",
    "scopeIds": ["repo:root", "service:edge-api", "tests:edge-api", "agent:codex"],
    "agentId": "agent:codex",
    "task": "Plan a safe route change",
    "tokenBudget": 1200
  }'

Source manifest:

curl https://neutronai.dev/v1/demo/codex/sources

Step 7: Request context before a task

neutron context \
  --scope repo:root,service:edge-api,infra:cloudflare,tests:edge-api,agent:codex \
  --task "Add support for jurisdictional Nucleus archive buckets."

Codex should use the context pack as supporting context, not as a replacement for reading the files it edits.

Step 8: Write back safe task outcomes

After a task completes, store the outcome in agent:codex.

neutron remember \
  --scope agent:codex \
  --type tool_lesson \
  --text "When Nucleus placement changes, verify platform creation, direct memory auth, and cache invalidation behavior."

Good task outcomes include:

• Files changed.
• Commands run.
• Test failures and fixes.
• Deployment notes.
• New security or tenant-isolation lessons.

Do not store:

• Secrets.
• Raw authorization headers.
• Session cookies.
• Private customer data.
• Full prompts containing sensitive context.

Step 9: Use MCP from compatible agent hosts

Use the remote MCP endpoint when your agent host supports MCP tools.

import { createNeutronMcpServerUrl, createOpenAIMcpTool } from "@neutron-ai/sdk";

export const neutron_memory = createOpenAIMcpTool({
  serverUrl: createNeutronMcpServerUrl("https://mcp.neutronai.dev"),
  serverLabel: "neutron_memory",
  authorization: `Bearer ${process.env.NEUTRON_API_TOKEN}`,
  allowedTools: ["memory_agent_context", "memory_recall", "memory_reflect"],
  requireApproval: "never"
});

Keep destructive tools disabled unless the host is trusted to write, forget, compact, or invalidate memory.

Step 10: Keep context fresh

Refresh cached repo context when any of these change:

• Commit SHA.
• AGENTS.md.
• Package manifests.
• Route definitions.
• Runtime config.
• Infrastructure config.
• Test contracts.
• Security rules.

Use stable scope names so old lessons remain useful across branches, while task-specific context can stay narrow and disposable.

Example workflow

flowchart LR
  A["Codex receives task"] --> B["Request Code Nucleus context"]
  B --> C["Read and edit local files"]
  C --> D["Run focused checks"]
  D --> E["Reflect safe outcome"]
  E --> F["Store reusable lesson"]

This gives Codex a durable project memory loop: recall before edits, verify after edits, and remember only the lessons that help future work.