Guardrail Context Engine

Full-repo context engineering, persistent AI memory, and rule generation

The Context Engine is a comprehensive system that scans your repository, generates multiple summary layers, maintains persistent AI memory, and creates context rules for AI assistants. It ensures tools like Cursor, Claude Code, GitHub Copilot, and other AI assistants have full project awareness and stay aligned with your codebase as it grows.

Features

$3

- Scans entire repository and generates multiple summary layers
- Analyzes project structure, component relationships, APIs, data models, and dependencies
- Creates comprehensive context maps that AI tools can understand

$3

- Maintains and updates a memory of your codebase as it evolves
- Versioned snapshots with summary layers
- Interoperable memory keeps AI coherent as projects grow

$3

- Automatically produces "context rules" that tell AI how your project works
- Reduces hallucinations and broken suggestions even in large files
- Rules are categorized (architecture, patterns, conventions, APIs, data, dependencies)

$3

- Watches for code changes and updates context maps automatically
- File watchers detect changes and trigger updates
- AI assistants always see the latest structure

$3

- CLI: guardrail context:* commands
- MCP Server: Tools for context engineering
- INIT Integration: Auto-initialize on project setup
- MDC Generator: Creates documentation from context

Installation

``bash
npm install @guardrail/context-engine


or


pnpm add @guardrail/context-engine
`

Quick Start

$3

`bash
guardrail context:init
`

This will:

1. Scan your repository
2. Create a context snapshot
3. Generate context rules
4. Create MDC documentation files
5. Optionally start a file watcher

$3

`bash
guardrail context:rules
`

Generates context rules from your repository summary.

$3

`bash
guardrail context:scan
`

Scans repository and generates a context snapshot.

$3

`bash
guardrail context:watch
`

Watches your repository for changes and automatically updates context.

$3

`bash
guardrail context:export --format markdown
`

Exports context snapshot for AI tools (JSON or Markdown).

CLI Commands

- guardrail context:init - Initialize context engine for a project
- guardrail context:scan - Scan repository and generate context snapshot
- guardrail context:rules - Generate context rules from repository summary
- guardrail context:watch - Watch repository for changes and auto-update context
- guardrail context:export - Export context snapshot for AI tools

API Usage

$3

`typescript
import { initializeProjectContext } from '@guardrail/context-engine';

const result = await initializeProjectContext({
projectPath: './my-project',
generateRules: true,
generateMDC: true,
startWatcher: false,
});

console.log(Snapshot: ${result.snapshot.id});
console.log(Rules: ${result.rules.length});
`

$3

`typescript
import { RepositoryScanner } from '@guardrail/context-engine';

const scanner = new RepositoryScanner('./my-project');
const summary = await scanner.scan();

console.log(Files: ${summary.metadata.totalFiles});
console.log(APIs: ${summary.apis.length});
console.log(Models: ${summary.dataModels.length});
`

$3

`typescript
import { RuleGenerator, RepositoryScanner } from '@guardrail/context-engine';

const scanner = new RepositoryScanner('./my-project');
const summary = await scanner.scan();

const generator = new RuleGenerator();
const rules = await generator.generateRules(summary, 'project-id');

rules.forEach((rule) => {
console.log(${rule.name}: ${rule.rule});
});
`

$3

`typescript
import { MemoryManager, FileMemoryStorage } from '@guardrail/context-engine';

const storage = new FileMemoryStorage('./.guardrail/context');
const memoryManager = new MemoryManager(storage);

// Create snapshot
const snapshot = await memoryManager.createSnapshot('project-id', summary);

// Get latest snapshot
const latest = await memoryManager.getLatestSnapshot('project-id');

// Get layers
const layers = await memoryManager.getLayers(snapshot.id);
`

MCP Server Integration

The Context Engine is available as MCP tools:

- guardrail.context.scan - Scan repository and generate context snapshot
- guardrail.context.rules - Generate context rules
- guardrail.context.export - Export context snapshot
- guardrail.context.init - Initialize context engine for a project
- guardrail.context.watch - Watch repository for changes

Architecture

$3

Scans repository and generates summary layers:

- Project structure (architecture type, layers, entry points)
- Component relationships (imports, exports, dependencies)
- APIs (endpoints, methods, handlers)
- Data models (interfaces, types, classes, schemas)
- Dependencies (runtime, dev, internal)

$3

Maintains persistent AI memory:

- Versioned snapshots
- Summary layers (structure, relationships, APIs, data-models, dependencies)
- Update tracking

$3

Generates context rules:

- Architecture rules
- Pattern rules
- Convention rules
- API rules
- Data model rules
- Dependency rules

$3

Self-updating summaries:

- File system watching (chokidar)
- Change detection
- Automatic updates

$3

Advanced analysis with AST parsing:

- TypeScript AST analysis
- Dependency graphs
- Call graphs
- Architecture layers
- Code patterns
- Security patterns

Integration with INIT

The Context Engine integrates with project initialization. When you run guardrail init, it can automatically:

1. Scan the repository
2. Generate context rules
3. Create MDC documentation files
4. Set up file watchers

This ensures your project is fully contextualized from the start.

Integration with MDC Generator

The Context Engine integrates with the MDC generator to create comprehensive documentation:

- Architecture documentation
- API reference
- Data models documentation
- Dependencies documentation
- Component relationships documentation

Generated Files

When you initialize the context engine, it creates:

- .guardrail/context/ - Memory storage directory
- .guardrail/context-rules.json - Generated context rules
- .guardrail/config.json - Configuration file
- .specs/ - MDC documentation files (if enabled)

Context Rules

Context rules are automatically generated and describe:

- Architecture: Project structure, layers, build system
- Patterns: Common patterns used in the codebase
- Conventions: Coding conventions and best practices
- APIs: API structure and patterns
- Data Models: Data model patterns
- Dependencies: Dependency management patterns

Rules are prioritized (high, medium, low) and can be enabled/disabled.

Best Practices

1. Initialize Early: Run guardrail context:init when starting a new project
2. Keep Updated: Use guardrail context:watch to keep context updated automatically
3. Review Rules: Review generated rules and customize as needed
4. Regenerate: Regenerate context after major codebase changes
5. Export for Tools: Export context for use with AI tools (Cursor, Claude, etc.)

Examples

$3

`bash


Initialize context engine

guardrail context:init

Generate rules

guardrail context:rules

Export for AI tools

guardrail context:export --format markdown --output context.md
`

$3

`bash


Initialize with custom options

guardrail context:init --no-mdc --watch

Scan and generate snapshot

guardrail context:scan --output snapshot.json

Watch for changes

guardrail context:watch
``

License

MIT

Support

For issues and questions, visit https://github.com/guardiavault-oss/codeguard/issues