AGENTS.md Template: Memcached Production Architecture

Overview

Direct answer: This AGENTS.md Template for Memcached production architecture provides a structured, repeatable operating manual for AI coding agents that manage a Memcached-backed cache tier in a multi-agent workflow, including handoffs, governance, and human review. It governs both single-agent and multi-agent orchestration.

When to Use This AGENTS.md Template

• When building or operating a Memcached-based cache layer in production with AI agents.
• When you require clear handoff rules and accountability across planner, implementer, reviewer, tester, and domain experts.
• When you need tool governance, secrets handling, and secure deployment controls for a cache tier.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Memcached Production Orchestrator for AI coding agents
Agent Rosters and Responsibilities:
- CacheArchitect: designs Memcached topology, shard layout, and eviction policy
- CacheProvisioner: provisions Memcached instances, config, and TLS where applicable
- CacheOperator: runs warm-up, cache population, and health checks
- MonitorAgent: collects metrics, alerts on cache misses/hits, TTL drift
- DataIngestor: feeds relevant data to cache entries and TTL policies
- SecurityOfficer: enforces secret handling and access controls
- HandoffCoordinator: manages cross-agent handoffs and memory passing
- Reviewer: validates changes against policy and compliance
- Tester: executes integration tests for cache behavior
- DomainSpecialist: provides service-specific caching constraints

Supervisor/Orchestrator Behavior:
- The Planner assigns tasks based on priority and dependencies.
- The Orchestrator ensures global invariants (e.g., cache hit rate thresholds).
- All agents should pass context on handoffs and fail gracefully with rollback signals.

Handoff Rules:
- Handoff only after complete context, memory state, and acceptance criteria are met.
- Handoff includes: task description, current state, last successful checkpoint, and required inputs.
- On failure, escalate to Reviewer and then SecurityOfficer if secrets are implicated.

Context, Memory, and Source of Truth:
- Central memory store with versioned logs; agents reference keys and owners.
- All cache configuration state is stored in a central repository and reflected in Memcached config.

Tool Access and Permissions:
- Access to Memcached admin interface, config repository, and monitoring dashboards is restricted by role.
- API keys and secrets exist only in approved secret stores.
- All commands requiring production modification must be approved by the Planner or a designated Gatekeeper.

Architecture Rules:
- Use a single Memcached cluster per service with TTL-based eviction tuned for workload.
- Define consistent shard placement and replica strategy where possible.
- Keep a reference architecture doc up to date in the repo.

File Structure Rules:
- /services/memcached
- /ai-skills/agents-md-templates/roster.md
- /configs/memcached/
- /docs/architecture/memcached.md

Data, API, and Integration Rules:
- All cache entries must accompany a TTL and optional tags.
- Do not cache sensitive data unless encrypted-at-rest and access-controlled.
- Use metrics API endpoints for health checks and stat collection.

Validation Rules:
- Validate cache hits > 70% baseline after deployment; else roll back.
- Validate eviction events and TTL drift within acceptable bounds.
- All changes pass Reviewer approval before production.

Security Rules:
- Never expose Memcached admin port publicly.
- Secrets must be stored in a vault; rotation rules enforced.
- Production changes require multi-party approval.

Testing Rules:
- Unit tests for TTL logic, eviction policy, and cache key naming.
- Integration tests for end-to-end cache warm-up and invalidation.
- End-to-end tests in staging; performance tests for latency under load.

Deployment Rules:
- Canary deployments for cache topology changes.
- Monitor metrics and rollback if thresholds degrade.

Human Review and Escalation Rules:
- Human review required for any production topology changes.
- Escalate policy violations to SecurityOfficer and Compliance.

Failure Handling and Rollback Rules:
- If cache is unresponsive, revert to prior working config and re-validate.
- Maintain a rollback document with steps and owners.

Things Agents Must Not Do:
- Do not bypass security controls.
- Do not share secrets in logs or messages.
- Do not perform unsupervised production changes.
- Do not drift away from defined architecture or policy.

ai-memcached-ops/
├── configs/
│   └── memcached.yaml
├── services/
│   └── memcached/
├── agents/
│   ├── planner.md
│   ├── implementer.md
│   ├── tester.md
│   ├── reviewer.md
│   └── domain-specialist.md
├── docs/
│   └── architecture.md
└── tests/
    └── integration/

• Operate with explicit, testable outputs and versioned memory.
• Favor safety, rollback, and observability over boldness.
• Handoffs must preserve context and state with clear acceptance criteria.
• Respect data ownership and security constraints.

• Planner assigns tasks; Implementer executes; Reviewer validates; Tester tests; DomainSpecialist provides constraints.
• Handoffs require memory state, inputs, outputs, and checkpoints.
• Cross-team collaboration rules require explicit approvals and references.

• Commands to modify Memcached config require Planner approval.
• Edits to docs or configs require review and commit in version control.
• Secrets and credentials must be rotated and stored in vaults.
• Automatic production changes are forbidden without manual gates.

• Use consistent naming; keep code modular and testable.
• Dont duplicate cache entries; centralize TTL computation.
• All code changes must be accompanied by tests and docs.

• Use least privilege principle for all agents.
• Audit trails for any production changes; enable alerting on anomalies.
• Memcached exposure must be minimized; TLS is optional based on deployment.

• Unit tests for TTL logic and eviction rules.
• Integration tests for end-to-end cache warm-up and invalidation flows.
• End-to-end tests in staging; performance checks.

• Skipping memory state updates during handoffs.
• Over-permissive tool access leading to secrets leakage.
• Not validating TTL drift after topology changes.

What is this AGENTS.md Template for Memcached production architecture?

It defines how AI coding agents operate in a Memcached-based cache tier, including multi-agent orchestration and governance.

How many agents are involved and what are their duties?

Roster includes CacheArchitect, CacheProvisioner, CacheOperator, MonitorAgent, DataIngestor, SecurityOfficer, HandoffCoordinator, Reviewer, and Tester; duties range from topology to validation.

How are handoffs managed between planners, implementers, and reviewers?

Handoffs pass context, memory state, and acceptance criteria; planners assign tasks, implementers execute, reviewers verify, testers test.

What are the security and production rules?

Secrets must be stored securely, production changes require approvals, rollbacks are documented with ownership.

How is memory and source of truth maintained?

All state lives in a central, versioned memory store; agents reference memory via keys and maintain data ownership.

Related implementation resources: AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.