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

🧠 Full-Repo Context Engineering

• 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

💾 Persistent AI Memory

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

📋 Rule Generation

• 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)

🔄 Self-Updating Summaries

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

🛠️ Integrations

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

Installation

npm install @guardrail/context-engine
# or
pnpm add @guardrail/context-engine

Quick Start

Initialize Context Engine

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

Generate Context Rules

guardrail context:rules

Generates context rules from your repository summary.

Scan Repository

guardrail context:scan

Scans repository and generates a context snapshot.

Watch for Changes

guardrail context:watch

Watches your repository for changes and automatically updates context.

Export Context

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

Initialize Project Context

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}`);

Scan Repository

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}`);

Generate Rules

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}`);
});

Memory Management

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

Repository Scanner

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)

Memory Manager

Maintains persistent AI memory:

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

Rule Generator

Generates context rules:

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

Summary Watcher

Self-updating summaries:

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

Enhanced Scanner

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

Basic Usage

# Initialize context engine
guardrail context:init

# Generate rules
guardrail context:rules

# Export for AI tools
guardrail context:export --format markdown --output context.md

Advanced Usage

# 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