AI Agent Configuration & Rules

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CONVENTIONS.md
• README.md
• crates/mcb-server/src/tools/registry.rs
• crates/mcb-validate/rules/schema.json
• config/mcb-validate-internal.toml

AI Agent Configuration & Rules within the Memory Context Browser (MCB) project establish an inviolable framework for engineering conduct, architectural integrity, and automated validation. These rules serve as the "Universal Agent Law," binding any AI agent (such as Claude, Cursor, or Cline) and human developers to strict standards of root-cause resolution, surgical code edits, and inward-only dependency flows.

The configuration encompasses both behavioral guidelines for agents and technical validation schemas that enforce Clean Architecture and code quality. By integrating these rules into the project's core, MCB ensures that persistent memory, semantic search, and codebase understanding features are developed with zero tolerance for technical debt or architectural regressions.

Universal Agent Law

The Universal Agent Law is a self-contained core of engineering conduct that applies to every project type and session. It is designed to be agent-agnostic, binding any AI entity interacting with the repository to a set of strict operational protocols.

Core Principles

• Zero-Tolerance/Strict-Total: Agents must always fix root causes rather than symptoms. Superseded code must be removed immediately, and the system must "fail loud" if the single source of truth is absent.
• Fix-Forward-Only: Reverting shared work is forbidden without explicit user consent. Agents must accept the current state and apply fixes on top of it to avoid destroying in-flight work from other agents.
• Evidence-Based Completion: "Done" is defined by objective evidence (commands, exit codes, and output lines). Assumptions and speculative results are strictly prohibited.
• Strict Typing: The system requires the most restrictive types possible, forbidding Any or unchecked casts unless documented with a specific justification.

Sources: AGENTS.md:12-68

Operational Protocols

When an operation is blocked by security hooks or sandboxes, agents must follow a specific protocol:

1. Stop immediately without retrying variations.
2. Diagnose the blockage in one sentence.
3. Provide the exact command to the user for manual execution.
4. Wait for user output before continuing.

Sources: AGENTS.md:70-80

Architectural Validation Framework

Architectural integrity is maintained through mcb-validate, a specialized engine that enforces Clean Architecture rules and dependency boundaries.

Layered Dependency Rules

The project enforces a strict inward-only dependency flow, preventing lower-level crates from depending on higher-level implementation details.

Layer	Permitted Internal Dependencies	Role
mcb-domain	None	Entities, ports, and business logic
mcb-providers	mcb-domain, mcb-utils	Adapters for search, storage, and VCS
mcb-infrastructure	mcb-domain, mcb-providers, mcb-utils	DI wiring and runtime configuration
mcb-server	mcb-domain, mcb-infrastructure, mcb-utils	MCP protocol and API handlers
mcb-utils	None	Leaf utilities and helpers

Sources: README.md:99-115, config/mcb-validate-internal.toml:17-23, AGENTS.md:155-168

Validation Engine Flow

The following diagram illustrates how the validation engine processes code against defined rules:

The validation engine uses AST analysis and linter integration to ensure source code complies with the project's architectural and quality standards.
Sources: crates/mcb-validate/rules/schema.json:71-110, config/mcb-validate-internal.toml:178-195

AI Agent Tools and MCP Registry

MCB exposes a suite of tools through the Model Context Protocol (MCP), which are registered via a distributed registry for agent consumption.

Registered Tool Categories

Agents have access to several tool families registered in the server's registry:

• Search: search_code, search_memory for natural language codebase queries.
• Index: index_repo, index_status, clear_index for managing semantic search data.
• Memory: store_memory, get_memories, list_memories, memory_timeline, inject_context for cross-session knowledge storage.
• Validation: validate_code, analyze_code, list_rules for architectual checks.
• VCS: list_repos, compare_branches, analyze_impact for git-aware operations.

Sources: crates/mcb-server/src/tools/registry.rs:88-250, README.md:73-86

Tool Registration Mechanism

Tools are defined using a ToolDescriptor that serves as the single source of truth for both listing and dispatch. This includes the tool name, description, JSON schema for arguments, and an async dispatch function.

pub struct ToolDescriptor {
    pub name: &'static str,
    pub description: &'static str,
    pub schema: fn() -> schemars::Schema,
    pub call: ToolCallFn,
}

Sources: crates/mcb-server/src/tools/registry.rs:46-52

Rule Schema and Configuration

Validation rules are defined in YAML using a specific JSON schema, allowing for complex checks across multiple languages.

Schema Properties

The schema.json defines the structure for all validation rules, including:

• Engine Selection: Choices include ast, regex, path, and rust-rule-engine.
• Selectors: Targeted AST nodes (e.g., function_item) for specific languages like Rust, Python, and TypeScript.
• Metrics: Thresholds for cognitive_complexity, cyclomatic_complexity, and function_length.
• Severity: Levels including error, warning, and info.

Sources: crates/mcb-validate/rules/schema.json:11-177

Quality Configuration

The project configuration sets specific thresholds to ensure code readability and safety.

Configuration Metric	Default Value	File Reference
max_file_lines	800	config/mcb-validate-internal.toml
max_function_lines	50	config/mcb-validate.toml
max_trait_methods	10	config/mcb-validate.toml
unsafe_code	deny	CONVENTIONS.md
dead_code	deny	CONVENTIONS.md

Sources: config/mcb-validate-internal.toml:158, CONVENTIONS.md:12-13

Conclusion

The AI Agent Configuration & Rules in MCB create a robust environment where AI agents operate under strict engineering discipline. By combining the ethical and operational mandates of the Universal Agent Law with the automated enforcement of mcb-validate, the project ensures that every contribution—whether human or AI-generated—adheres to Clean Architecture principles and high-quality coding standards. This framework is essential for maintaining the integrity of the project's complex multi-provider memory and search systems.