Context Builder

Standalone layered context builder for AI agents. Builds rich, structured context from multiple sources in a predictable layer order.

How It Works

Context is assembled in layers, each enriching the previous:

┌─────────────────────────────────┐
│  1. Contract (task definition)  │  ← What you want done
├─────────────────────────────────┤
│  2. Repo Facts (codebase scan)  │  ← What exists
├─────────────────────────────────┤
│  3. References (docs & search)  │  ← What's known
├─────────────────────────────────┤
│  4. Artifacts (generated files) │  ← What was built
└─────────────────────────────────┘

Install

npm install -g @agentxagi/context-builder
# or
npx @agentxagi/context-builder "build a REST API"

CLI Usage

# Basic usage
context-builder "build a REST API for user management"

# With output format
context-builder "refactor auth module" --format json

# With config file
context-builder "add caching layer" --config .context-builder.yaml

# Specific layers only
context-builder "fix memory leak" --layers contract,repo

# Custom repo path
context-builder "optimize queries" --repo ./my-project

# Memory search integration
context-builder "implement RBAC" --memory-search

Options

Flag	Default	Description
--format, -f	markdown	Output format: markdown or json
--config, -c	.context-builder.yaml	Config file path
--repo, -r	.	Repository root path
--layers, -l	all	Comma-separated layers to include
--output, -o	stdout	Output file path
--memory-search	false	Enable memory search integration
--dry-run	false	Show what would be built without executing

API Usage

import { buildContext } from '@agentxagi/context-builder'

const result = await buildContext({
  task: 'build a REST API for user management',
  repoPath: './my-project',
  format: 'json',
  layers: ['contract', 'repo', 'references'],
  memorySearch: true,
  config: {
    memorySearchEndpoint: 'http://localhost:3000/api/search',
    maxTokens: 8000
  }
})

console.log(result.context)  // The assembled context
console.log(result.meta)     // Metadata (tokens, layers, timing)

Configuration

Create .context-builder.yaml in your project root:

# Context Builder Configuration

# Layer configuration
layers:
  contract:
    enabled: true
    template: |
      ## Task
      {{task}}
      
      ## Requirements
      - Do X
      - Handle Y edge case
      
  repo:
    enabled: true
    scanPatterns:
      - "src/**/*.js"
      - "src/**/*.ts"
      - "lib/**/*.py"
    excludePatterns:
      - "node_modules/**"
      - "**/*.test.js"
      - "dist/**"
    maxFiles: 50
    maxLinesPerFile: 100
    scanDepth: 3
    
  references:
    enabled: true
    sources:
      - "docs/**/*.md"
      - "README.md"
      - "ARCHITECTURE.md"
      - "CONTRIBUTING.md"
    memorySearch:
      enabled: false
      endpoint: "http://localhost:3000/api/search"
      maxResults: 5
      
  artifacts:
    enabled: true
    paths:
      - "artifacts/**"
      - ".context/**"

# Output settings
output:
  format: markdown
  maxTokens: 8000
  includeMeta: true
  
# Custom templates
templates:
  markdown: |
    # Context: {{task}}
    
    Built at: {{timestamp}}
    Layers: {{layers}}
    
    ---
    
    {{content}}
    
  json: null  # uses default JSON structure

Output Format

Markdown (default)

# Context: Build a REST API for user management

Built at: 2024-01-15T10:30:00Z
Layers: contract, repo, references

---

## Layer 1: Contract

### Task
Build a REST API for user management

### Requirements
...

## Layer 2: Repo Facts

### Structure
src/
├── controllers/
├── models/
└── routes/

### Key Files
...

## Layer 3: References

### Documentation
...

JSON

{
  "task": "Build a REST API for user management",
  "layers": {
    "contract": { ... },
    "repo": { ... },
    "references": { ... }
  },
  "meta": {
    "tokens": 4500,
    "buildTime": 1250,
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Architecture

src/
├── index.js          # API entry point (buildContext)
├── builder.js        # Main context builder orchestrator
├── layers/
│   ├── contract.js   # Task definition & requirements
│   ├── repo.js       # Repository scanning & facts extraction
│   ├── references.js # Documentation & memory search
│   └── artifacts.js  # Generated artifacts collection
└── utils/
    ├── config.js     # Config loader & defaults
    ├── tokens.js     # Token estimation
    └── format.js     # Output formatters (markdown/json)
bin/
└── context-builder.js # CLI entry point

License

MIT