AI Agents & Compound Memory
Relevant source files
The following files were used as context for generating this wiki page:
AI Agents & Compound Memory represents the architectural framework for integrating AI coding assistants into the Financial Asset Relationship Database project. This system uses "compounded memory" to ensure that agents maintain technical context across sessions, sessions, and different toolsets. The framework prioritizes the production architecture (FastAPI/Next.js) and enforces strict boundaries on state mutations and documentation ownership.
Sources: AGENTS.md:1-12, ARCHITECTURE.md:1-10, .cursor/rules/architecture-expert.mdc:1-10
Architecture Overview
The agentic system operates through sidecar configuration files and microagents that consume documentation from docs/compound/. A synchronization script, scripts/compound/sync_agent_packs.py, generates these packs to maintain consistency between the project's internal state and the AI's understanding.
Component Structure
The following diagram illustrates the relationship between the core documentation and the agent-specific sidecars.
The sync script reads canonical documentation and generates rules for specific AI tools.
Sources: scripts/compound/sync_agent_packs.py:16-25, .openhands/microagents/architecture_expert.md:1-5
Operational Constraints
Agents must follow specific entry routes and state verification procedures before modifying the codebase. This prevents the use of stale historical context.
Verification Workflow
You must verify the environment state before performing any summaries or edits.
Branch and Ref Verification
Agents must never assume a task is complete based on a clean working tree. They must verify:
- The current active branch.
- The specific commit or Pull Request (PR) reference.
- The delta between the current branch and
main.
Sources: AGENTS.md:19-25, .cursor/rules/architecture-expert.mdc:11-15
Compounded Memory Tiers
The system distinguishes between "Landed" and "Provisional" information to prevent AI-generated drift.
| Tier | Definition | Usage Rule |
|---|---|---|
| Landed | Information merged to main or explicitly promoted. | Treat as canonical source of truth. |
| Provisional | Information in open PRs or watched series. | Label clearly; do not present as fact. |
| Human-Owned | ADRs, .github policy, and AGENTS.md. | Agents may cite or propose; never rewrite. |
Sources: .cursor/rules/architecture-expert.mdc:17-28, .openhands/microagents/architecture_expert.md:20-30
Compound Memory Synchronization
The scripts/compound/sync_agent_packs.py utility serves as the bridge between human-authored documentation and agent memory.
Key Logic and Sanitization
- Link Rewriting: The script converts relative markdown links to absolute paths relative to the repository root.
- Instruction Sanitization: It detects and rewrites forbidden write instructions. For example, instructions to "rewrite ADRs" are converted to "cite or propose annotation."
- Constraint Enforcement: The script aborts if the synchronization process attempts to modify
AGENTS.md, which is reserved for Dosu maintenance.
Sources: scripts/compound/sync_agent_packs.py:38-60, scripts/compound/sync_agent_packs.py:141-150
The synchronization process enforces documentation ownership boundaries.
Sources: scripts/compound/sync_agent_packs.py:130-155
Agent Tooling & Triggers
Agents are integrated into the workflow through specific file triggers and command patterns.
Agent Interface Table
| Tool | Trigger / File Path | Purpose |
|---|---|---|
| Cursor | .cursor/rules/*.mdc | Provides context for the Cursor IDE chat and composer. |
| OpenHands | @architecture-expert | Triggers the knowledge microagent in OpenHands environments. |
| GitHub Copilot | .github/copilot-instructions.md | Standardizes Copilot responses regarding production architecture. |
| Query Memory | scripts/compound/query_memory.py | Allows agents to query the compound memory via CLI. |
Sources: .openhands/microagents/architecture_expert.md:11-16, .cursor/rules/architecture-expert-query.mdc:1-12, .github/copilot-instructions.md:1-5
Production Architecture Mandate
All agent interactions must prioritize the FastAPI backend and Next.js frontend. The Gradio UI (app.py) is explicitly labeled as Non-Production and reserved for demos or internal testing. Agents are instructed to prioritize the production stack unless a request specifically mentions the demo app.
Sources: AGENTS.md:32-40, .github/copilot-instructions.md:10-15
Failure Modes & Safety
The system implements safety gates for agent-led changes, particularly regarding concurrency and state.
- Concurrency Locks: All lock context managers must have a maximum TTL of 300 seconds.
- PR Triage: Agents must define "Upstream Source", "Downstream Impact", and "Failure Mode" in every PR description.
- Manual Halts: CI pipelines must pause if tags like
[manual-stop]are present, requiring human sign-off. - Rebuild Safety: Modified processing loops must check for
cancel_eventand validateexecution_idto prevent stale mutations.
Sources: GEMINI.md:10-25, AGENTS.md:175-185
Conclusion
The AI Agents & Compound Memory system ensures that AI contributors operate within a strictly defined architectural and documentation framework. By utilizing automated synchronization of memory packs and enforcing tiered access to documentation, the project maintains high technical accuracy and prevents the drift typically associated with long-term agentic code maintenance.
Sources: .cursor/rules/architecture-expert.mdc:35-40, scripts/compound/sync_agent_packs.py:1-10