diff --git a/.claude/agents/weather.md b/.claude/agents/weather.md index 2f9e4c5..b727358 100644 --- a/.claude/agents/weather.md +++ b/.claude/agents/weather.md @@ -2,8 +2,9 @@ name: weather description: Use this agent PROACTIVELY when you need to fetch and transform weather data for Karachi, Pakistan. This agent fetches real-time temperature from wttr.in API and applies transformation rules from weather-orchestration/input.md, writing results to weather-orchestration/output.md. tools: WebFetch, Read, Write -model: haiku +model: sonnet color: green +memory: project skills: - weather-fetcher - weather-transformer @@ -19,6 +20,7 @@ Execute the weather workflow by following the instructions from your preloaded s 1. **First**: Follow the `weather-fetcher` skill instructions to fetch the current temperature 2. **Then**: Follow the `weather-transformer` skill instructions to apply transformations and write results +3. **Finally**: Update your agent memory with the reading details for historical tracking ## Workflow @@ -38,11 +40,12 @@ Follow the weather-transformer skill instructions to: ## Final Report -After completing both steps, provide a summary: +After completing all steps, provide a summary: - Temperature unit: Celsius - Original temperature fetched - Transformation rule applied - Final transformed result +- Comparison with previous reading (if available in memory) - Confirmation that output was written to `weather-orchestration/output.md` ## Critical Requirements diff --git a/CLAUDE.md b/CLAUDE.md index 97a5f13..754bf5e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -55,6 +55,7 @@ Subagents in `.claude/agents/*.md` use YAML frontmatter: - `model`: Typically "haiku" for efficiency - `color`: CLI output color for visual distinction - `skills`: List of skill names to preload into agent context +- `memory`: Persistent memory scope — `user`, `project`, or `local` (see `reports/claude-agent-memory.md`) ### Configuration Hierarchy 1. `.claude/settings.local.json`: Personal settings (git-ignored) @@ -94,3 +95,4 @@ From experience with this repository: - `reports/claude-in-chrome-v-chrome-devtools-mcp.md`: Browser automation MCP comparison (Playwright vs Chrome DevTools vs Claude in Chrome) - `reports/claude-md-for-larger-mono-repos.md`: CLAUDE.md loading behavior in monorepos (ancestor vs descendant loading) - `reports/claude-skills-for-larger-mono-repos.md`: Skills discovery and loading behavior in monorepos (static vs dynamic discovery) +- `reports/claude-agent-memory.md`: Agent memory frontmatter — persistent memory scopes (user, project, local) for subagents diff --git a/reports/claude-agent-memory.md b/reports/claude-agent-memory.md new file mode 100644 index 0000000..7d26dfa --- /dev/null +++ b/reports/claude-agent-memory.md @@ -0,0 +1,244 @@ +# Claude Code: Agent Memory Frontmatter + +Persistent memory for subagents — enabling agents to learn, remember, and build knowledge across sessions. + + + + + + +
← Back to Claude Code Best PracticeClaude
+ +## Table of Contents + +1. [Overview](#overview) +2. [Syntax](#syntax) +3. [Memory Scopes](#memory-scopes) +4. [How It Works Under the Hood](#how-it-works-under-the-hood) +5. [Agent Memory vs Other Memory Systems](#agent-memory-vs-other-memory-systems) +6. [Practical Patterns](#practical-patterns) +7. [Tips for Effective Agent Memory](#tips-for-effective-agent-memory) +8. [Sources](#sources) + +--- + +## Overview + +Introduced in **Claude Code v2.1.33** (February 2026), the `memory` frontmatter field transforms subagents from stateless tools into **context-aware assistants** that persist knowledge across conversations. + +Before this feature, every agent invocation started from scratch — a code review agent couldn't remember patterns it flagged last week, and a debugging agent couldn't recall the architecture it mapped yesterday. The `memory` field fixes this by giving each agent its own persistent markdown-based knowledge store. + +--- + +## Syntax + +Add the `memory` field to the YAML frontmatter of any agent file in `.claude/agents/`: + +```yaml +--- +name: code-reviewer +description: Reviews code for quality and best practices +tools: Read, Write, Edit, Bash +model: sonnet +memory: user +--- + +You are a code reviewer. As you review code, update your agent memory with +patterns, conventions, and recurring issues you discover. +``` + +The `memory` field accepts one of three scope values: `user`, `project`, or `local`. + +--- + +## Memory Scopes + +| Scope | Storage Location | Version Controlled | Shared With Team | Best For | +|-------|-----------------|-------------------|-----------------|----------| +| `user` | `~/.claude/agent-memory//` | No | No | Cross-project knowledge (recommended default) | +| `project` | `.claude/agent-memory//` | Yes | Yes | Project-specific knowledge the team should share | +| `local` | `.claude/agent-memory-local//` | No (git-ignored) | No | Project-specific knowledge that's personal | + +### Scope Selection Guide + +**Use `user` when** the agent's knowledge applies across projects — coding style preferences, common anti-patterns, general best practices. This is the recommended default scope. + +**Use `project` when** the agent's knowledge is codebase-specific AND should be shared — architectural decisions, project conventions, known quirks. This gets committed to version control so teammates benefit. + +**Use `local` when** the agent's knowledge is codebase-specific but personal — your local environment setup, debugging notes, personal workflow preferences for this project. + +### Scope Hierarchy Parallel + +These scopes mirror the existing settings hierarchy: + +| Agent Memory Scope | Settings Equivalent | Philosophy | +|-------------------|---------------------|------------| +| `user` | `~/.claude/settings.json` | Global personal defaults | +| `project` | `.claude/settings.json` | Team-shared project config | +| `local` | `.claude/settings.local.json` | Personal project overrides | + +--- + +## How It Works Under the Hood + +When an agent has `memory` configured: + +1. **On startup**: The first 200 lines of `MEMORY.md` from the agent's memory directory are injected into the agent's system prompt +2. **Tool access**: `Read`, `Write`, and `Edit` tools are automatically enabled (regardless of the `tools` frontmatter) so the agent can manage its memory files +3. **During execution**: The agent can read from and write to its memory directory at any time +4. **Memory structure**: The agent maintains a `MEMORY.md` file and can create additional topic-specific files as needed + +### Memory Directory Structure + +``` +~/.claude/agent-memory/code-reviewer/ # user scope example +├── MEMORY.md # Primary memory file (first 200 lines loaded) +├── react-patterns.md # Topic-specific file +└── security-checklist.md # Topic-specific file +``` + +**Important**: If `MEMORY.md` exceeds 200 lines, the agent is instructed to curate it — moving detailed notes into separate topic files and keeping the main file as a high-level index. + +--- + +## Agent Memory vs Other Memory Systems + +Claude Code has multiple memory mechanisms. Here's how they compare: + +| System | Who Writes It | Who Reads It | Scope | Location | +|--------|--------------|-------------|-------|----------| +| **CLAUDE.md** | You (manually) | Main Claude + all agents | Project | `./CLAUDE.md` | +| **Auto-memory** | Main Claude (automatically) | Main Claude only | Per-project per-user | `~/.claude/projects//memory/` | +| **`/memory` command** | You (via editor) | Main Claude only | Per-project per-user | Opens auto-memory files | +| **Agent memory** ✨ | The agent itself | That specific agent only | Configurable (user/project/local) | Scope-dependent (see above) | + +### Key Distinctions + +- **CLAUDE.md** is human-authored project instructions — shared with everyone, loaded everywhere +- **Auto-memory** is what the main Claude conversation learns about your project over time — personal, automatic +- **Agent memory** is what a specific subagent learns over repeated invocations — scoped to that agent, self-maintained +- These systems are **complementary, not overlapping** — an agent reads both CLAUDE.md (for project context) and its own memory (for agent-specific knowledge) + +--- + +## Practical Patterns + +### Pattern 1: Code Review Agent with Learning + +```yaml +--- +name: code-reviewer +description: Reviews PRs for quality, patterns, and conventions +memory: project +--- + +Review the code changes. Check your memory for known patterns and recurring +issues in this codebase. After reviewing, update your memory with any new +patterns or conventions you discovered. +``` + +Over time this agent builds a project-specific knowledge base of code conventions, common mistakes, and architectural patterns — shared with the whole team via `project` scope. + +### Pattern 2: Architecture Explorer + +```yaml +--- +name: arch-explorer +description: Maps and remembers codebase architecture +memory: user +--- + +Explore the codebase to answer architecture questions. Consult your memory +first for previously mapped codepaths. Update your memory as you discover +new architectural decisions, module boundaries, and key integration points. +``` + +Using `user` scope means this agent's architectural knowledge carries across all your projects. + +### Pattern 3: Debugging Assistant + +```yaml +--- +name: debugger +description: Investigates bugs with context from past debugging sessions +memory: local +--- + +Investigate the reported issue. Check your memory for similar bugs or +known problematic areas. Document your findings and resolution in memory +for future reference. +``` + +Using `local` scope keeps personal debugging notes private and project-specific. + +### Pattern 4: Complete Agent with Skills and Memory + +```yaml +--- +name: api-developer +description: Implement API endpoints following team conventions +tools: Read, Write, Edit, Bash +model: sonnet +memory: project +skills: + - api-conventions + - error-handling-patterns +--- + +Implement API endpoints. Follow the conventions from your preloaded skills. +As you work, save architectural decisions and patterns to your memory. +``` + +This combines **skills** (static knowledge loaded at startup) with **memory** (dynamic knowledge built over time). + +--- + +## Tips for Effective Agent Memory + +### 1. Prompt the Agent to Use Its Memory + +Include explicit memory instructions in the agent's markdown body: + +```markdown +Before starting work, review your memory for relevant context. +After completing the task, update your memory with what you learned. +``` + +### 2. Request Memory Consultation + +When invoking agents, you can ask them to check their memory: + +> "Review this PR, and check your memory for patterns you've seen before." + +### 3. Request Memory Updates + +After task completion, prompt the agent to save learnings: + +> "Now that you're done, save what you learned to your memory." + +### 4. Include Proactive Memory Instructions in the Agent Body + +For agents that should always maintain their memory: + +```markdown +Update your agent memory as you discover codepaths, patterns, library +locations, and key architectural decisions. This builds institutional +knowledge across conversations. Write concise notes about what you found +and where. +``` + +### 5. Choose the Right Scope + +| If the knowledge is... | Use scope | +|------------------------|-----------| +| Useful across all your projects | `user` | +| Codebase-specific, useful for the team | `project` | +| Codebase-specific, personal to you | `local` | + +--- + +## Sources + +- [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/sub-agents) +- [Manage Claude's memory — Claude Code Docs](https://code.claude.com/docs/en/memory) +- [Claude Code v2.1.33 Release Notes](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) diff --git a/weather-orchestration/output.md b/weather-orchestration/output.md index bd67070..717c4da 100644 --- a/weather-orchestration/output.md +++ b/weather-orchestration/output.md @@ -1,13 +1,13 @@ # Weather Transformation Result ## Original Temperature -24°C +27°C ## Transformation Applied -Add +20 to the temperature value +Add +20 to the result ## Final Result -44°C +47°C ## Calculation Details -24°C + 20 = 44°C +27°C + 20 = 47°C