go-agent/claude/agentic/patterns/agent-memory.md

Agent Memory Pattern

Memory seeds provide structured context for agent initialization and task execution. Each seed type serves a distinct purpose in helping agents understand their operating environment.

Memory Seed Types

1. Context Seed

Current task and environmental information that frames the agent's work.

Contents:

• Task description and objectives
• Working directory and file locations
• Active branch/PR context
• Related tickets or issues
• Time constraints or deadlines

Example:

context:
  task: "Implement rate limiting middleware"
  directory: /home/claude/api-service
  branch: feature/rate-limiting
  issue: "#142"
  deadline: "EOD"

2. Pattern Seed

Coding conventions, architectural decisions, and established patterns to follow.

Contents:

• Code style guidelines
• Architectural patterns in use
• Error handling conventions
• Testing requirements
• Documentation standards

Example:

pattern:
  architecture: "Clean Architecture with ports/adapters"
  error_handling: "Return errors, don't panic"
  testing: "Table-driven tests required"
  naming: "snake_case for files, CamelCase for types"

3. History Seed

Record of previous attempts, outcomes, and lessons learned.

Contents:

• Approaches already tried
• What worked and why
• What failed and why
• Blockers encountered
• Solutions discovered

Example:

history:
  tried:
    - approach: "Redis-based rate limiting"
      outcome: "failed"
      reason: "Redis unavailable in test env"
    - approach: "In-memory sliding window"
      outcome: "success"
      reason: "Simple, meets requirements"
  blockers_resolved:
    - "Config loading order fixed in commit abc123"

4. Constraint Seed

Boundaries, limitations, and non-negotiable requirements.

Contents:

• Technical limitations
• Security requirements
• Performance thresholds
• Compatibility requirements
• Scope boundaries

Example:

constraint:
  technical:
    - "Must support Go 1.21+"
    - "No external dependencies without approval"
  security:
    - "All inputs must be validated"
    - "No secrets in code"
  performance:
    - "Response time < 100ms p99"
  scope:
    - "Only modify pkg/middleware/"

Usage in Agent Initialization

When spawning an agent, include relevant seeds in the task description:

## Memory Seeds

### Context
Task: Fix failing unit tests in auth package
Branch: fix/auth-tests
Issue: #203

### Pattern
- Use testify/assert for assertions
- Mock external dependencies
- One test function per behavior

### History
- Previous fix attempt broke integration tests
- Root cause: shared state between tests

### Constraint
- Do not modify production code
- Tests must pass in CI (no network access)

Best Practices

1. Keep seeds focused - Include only relevant information
2. Update history - Record outcomes for future agents
3. Be explicit about constraints - Ambiguity causes failures
4. Inherit patterns - Reference existing pattern documentation
5. Validate context - Ensure paths and branches exist before handoff