Memory and Context Management AGENTS.md Template

Overview

This AGENTS.md template defines the operating context for memory and context management agents. It governs how AI coding agents store, recall, and share memory, and how multi-agent orchestration is conducted with clear handoffs, control planes, and human review gates. Direct answer: Use this AGENTS.md Template to establish a consistent memory and context workflow for single-agent and multi-agent setups, including a canonical memory store, memory index, and orchestrator-driven governance.

When to Use This AGENTS.md Template

• When building memory and context management workflows for AI coding agents.
• When multiple agents must coordinate across memory stores, context retrieval, and tool usage.
• When you require tool governance, explicit handoffs, and escalation to human review for sensitive data.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Memory and Context Management for AI coding agents. This AGENTS.md describes the operating model for a memory/context workflow across single-agent and multi-agent setups.

Agent roster and responsibilities:
- Planner: defines memory schema, keys, and orchestration across memory_keeper and context_retriever.
- Memory Keeper: stores memories with metadata, TTL, ownership, and provenance.
- Context Retriever: fetches relevant memories given prompts and memory state.
- Orchestrator: supervises handoffs, enforces source-of-truth, and gates privileged actions.
- Implementer: executes actions and updates memory as directed.
- Reviewer: validates memory updates and policy compliance.
- Tester: runs unit/integration tests on memory operations.
- Researcher: pulls external knowledge into memory when required.
- Domain Specialist: provides domain-specific validation and gating.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates Planner, Memory Keeper, Context Retriever, Implementer, Reviewer, Tester, Researcher.
- It enforces memory boundaries, provenance, and a single source of truth.
- It triggers handoffs based on memory criteria, data drift, or policy changes.

Handoff rules between agents:
- Planner completes the plan and memory references; it passes these to Memory Keeper and Context Retriever via the Orchestrator.
- Memory Keeper records a memory entry with a canonical memory_ref and returns it to the Orchestrator.
- Implementer executes the action, then writes an updated memory entry through Memory Keeper. Context Retriever may update references.
- Handoffs must include a memory_ref, provenance, and a timestamp.

Context, memory, and source-of-truth rules:
- Canonical memory_store is the source of truth; memory_index provides fast lookup.
- Memory entries include id, type, content, context, timestamp, ttl, provenance.
- All reads go through Context Retriever; direct access to memory_store is prohibited.
- External data requires citation and traceable provenance.

Tool access and permission rules:
- Tools: memory_store, memory_index, external_api_gateway. Access to memory_store requires Orchestrator authorization.
- Agents may read memory only via the Orchestrator; writes go through Memory Keeper with provenance.
- Secrets must be encrypted at rest and in transit; rotate secrets regularly.

Architecture rules:
- Memory_store runs as a service; Orchestrator acts as controller and policy enforcer; memory_index serves as a read-optimized index.
- Clear boundaries between planning, memory management, and execution.

File structure rules:
- Memory modules live under memory/; agent logic under agents/; orchestration under orchestrator/.
- Do not place memory tests inside agent runtimes; keep tests under tests/.

Data, API, or integration rules when relevant:
- Memory API endpoints: GET memory by id, SEARCH by context, WRITE memory with provenance.
- Data retention TTL for stale memories; purge rules defined in policy.

Validation rules:
- Every memory_write must include provenance and timestamp; memory updates require valid authorization.
- Memory lookups return a deterministic, sorted result by relevance and timestamp.

Security rules:
- Encrypt data at rest and in transit; restrict memory edits to authorized roles; audit logs retained.

Testing rules:
- Unit tests for memory_write, memory_read, and handoffs.
- Integration tests for orchestrator with memory_keeper and context_retriever.
- End-to-end tests for multi-agent memory flows.

Deployment rules:
- Deploy memory services with canaries; roll back on failure.

Human review and escalation rules:
- If memory contains PII or secrets, escalate to human review; flag for sensitive data review.
- Alert on memory anomalies or policy violations.

Failure handling and rollback rules:
- On failure, rollback to the previous memory entry; retry with backoff.
- If handoff fails, re-run Planner and Orchestrator workflow.

Things Agents must not do:
- Do not leak memory outside the canonical store.
- Do not bypass the Orchestrator or memory governance.
- Do not perform memory edits without proper validation.

Recommended Agent Operating Model

The memory/context management operating model defines roles, decision boundaries, and escalation paths for AI coding agents. The Planner scopes memory needs; the Memory Keeper enforces the canonical store; the Context Retriever delivers relevant memories; the Orchestrator enforces governance and handles handoffs; Implementer, Reviewer, and Tester execute and verify memory actions; Researcher and Domain Specialist provide domain-specific validations. Escalations route to human review when data sensitivity or policy exceptions occur.

Recommended Project Structure

memory-context-management/
├── agents/
│   ├── planner/
│   ├── memory_keeper/
│   ├── context_retriever/
│   ├── orchestrator/
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   └── researcher/
├── memory/
│   ├── store/
│   │   └── (memory_store implementation and data)
│   └── index/
│       └── (memory_index implementation)
├── workflows/
├── integrations/
└── tests/

Core Operating Principles

• Single source of truth for memory: memory_store with an index for fast lookup.
• Explicit, auditable handoffs between agents with provenance and timestamps.
• Memory vault: all memory writes go through the orchestrator and memory keeper.
• Access controls: only authorized roles may read or write memory.
• Context is retrieved per-prompt; stale memories are pruned by policy.
• Decisions are traceable to source data and agent actions.

Agent Handoff and Collaboration Rules

• Planner to Memory Keeper: provide memory schema and a plan; include memory_ref templates.
• Memory Keeper to Orchestrator: confirm memory_entry_id and provenance.
• Orchestrator to Implementer: deliver action plan and memory references; enforce gating.
• Implementer to Reviewer: submit results for validation and memory updates.
• Reviewer to Orchestrator: approve or request rework; escalate when needed.
• Researcher and Domain Specialist provide domain insights at handoff checkpoints.

Tool Governance and Permission Rules

• Only orchestrator can grant access to memory_store and external tools.
• Memory reads require minimal privilege; writes require explicit authorization and provenance.
• Secrets are stored encrypted; rotation policy enforced.
• All tool calls are logged; any privileged action requires justification.

Code Construction Rules

• Memory operations must be idempotent where possible.
• Keys must be sanitized; avoid leaking raw secrets in memory entries.
• Handoffs embed memory_ref tokens and provenance metadata.
• Modules should fail fast and provide clear rollback paths.

Security and Production Rules

• Data at rest and in transit encrypted; access controls enforced;
• PII and secrets flagged for human review; automated redaction where possible.
• Observability through metrics and logs; anomaly detection on memory writes.

Testing Checklist

• Unit tests for memory_write and memory_read.
• Integration tests for Planner/Memory Keeper/Context Retriever/Orchestrator.
• End-to-end tests for multi-agent memory workflow.
• Security tests for access controls and secret handling.

Common Mistakes to Avoid

• Skipping the orchestrator gating and bypassing memory governance.
• Allowing memory writes without provenance or timestamps.
• Over-sharing memory across agents without access controls.
• Unclear handoffs leading to context drift.

FAQ

What is the purpose of this AGENTS.md Template?

It defines memory and context management workflow for AI coding agents, including orchestration and governance.

What memory model does this template prescribe?

A canonical memory_store with a memory_index; memory entries include provenance, timestamp, and TTL.

How are agent handoffs enforced?

Handoffs occur via the Orchestrator with explicit memory_ref and provenance; all steps are auditable.

How is security enforced in memory operations?

Access controls, encryption, secrets rotation, and human review for sensitive data.

How should memory workflows be tested?

Unit tests for memory access, integration tests for orchestration, and end-to-end tests for multi-agent memory flows.