Overview

contox_populate batch creates or updates contexts using schemaKeys as identifiers. This is the primary tool used by the codebase scanner and CLI to push structured sub-contexts into the brain hierarchy. All created contexts default to the draft state.

The tool uses content-hash deduplication — if a context's content has not changed since the last populate, it is marked as unchanged and not re-written.

Parameters

Name	Type	Required	Default	Description
`nodes`	array	Yes	—	List of nodes to populate (see schema below)
`dryRun`	boolean	No	`false`	If true, only return diff stats without writing
`source`	string	No	—	Source identifier (e.g., `"cli-scan"`, `"mcp-populate"`)

Node schema

Each node in the nodes array has the following structure:

Field	Type	Required	Description
`schemaKey`	string	Yes	Unique schema key (e.g., `"root/api/auth"`)
`name`	string	Yes	Display name for the context
`content`	string	No	Markdown content
`description`	string	No	Brief description
`contextType`	enum	No	One of: `system`, `reference`, `memory`
`tier`	number	No	Tier level: 1 (always loaded), 2 (on-demand), 3 (archive)
`parentSchemaKey`	string	No	Parent schema key for hierarchy

Return value

Returns a summary of the populate operation:

Field	Type	Description
`runId`	string	Unique identifier for this populate run
`created`	number	Number of new contexts created
`updated`	number	Number of existing contexts updated
`unchanged`	number	Number of contexts with identical content (skipped)
`errors`	number	Number of errors during processing

Usage examples

Populating API documentation contexts

Claude calls: contox_populate({
  nodes: [
    {
      schemaKey: "root/api",
      name: "API Layer",
      description: "REST API routes and handlers",
      contextType: "reference",
      tier: 2
    },
    {
      schemaKey: "root/api/auth",
      name: "Auth API",
      content: "## Endpoints\n\n### POST /api/auth/login\nAccepts email and password...",
      parentSchemaKey: "root/api",
      contextType: "reference",
      tier: 2
    },
    {
      schemaKey: "root/api/users",
      name: "Users API",
      content: "## Endpoints\n\n### GET /api/users\nReturns paginated user list...",
      parentSchemaKey: "root/api",
      contextType: "reference",
      tier: 2
    }
  ],
  source: "mcp-populate"
})

Response:
Populate completed.
- Run ID: run_abc123
- Created: 3
- Updated: 0
- Unchanged: 0
- Errors: 0

Dry run to preview changes

Claude calls: contox_populate({
  nodes: [...],
  dryRun: true
})

Response:
Populate (dry run) completed.
- Run ID: run_def456
- Created: 2
- Updated: 1
- Unchanged: 5
- Errors: 0

Notes

Nodes should be ordered depth-first (parents before children) to ensure parent contexts exist when children reference them.
The schemaKey is the unique identifier — if a context with the same schemaKey already exists, it will be updated rather than duplicated.
Created contexts start in draft state. Use contox_approve to make them visible in the brain document.
The source field is recorded in the audit trail for tracking which tool or process created each context.

contox_search

contox_add_entry

On this page