[Claude sub-agents] Evaluate role-local persistent memory for learning agents

[azalio]

Source

Source: https://code.claude.com/docs/en/sub-agents, read on 2026-07-21.

Relevant source takeaways:

• Claude Code supports a subagent memory frontmatter field with scopes user, project, and local.
• project memory lives under .claude/agent-memory/<agent-name>/ and is intended for project-specific shareable knowledge.
• When enabled, Claude includes bounded MEMORY.md content from the memory directory in the subagent prompt and gives the subagent memory-management instructions.
• Important risk: enabling memory automatically enables Read, Write, and Edit tools so the subagent can manage memory files.
• Non-fork subagents do not see the main conversation auto memory; a subagent needs its own memory field for persistent role-local learning.

Repo evidence

Inspected source-of-truth templates and memory surfaces:

• src/mapify_cli/templates_src/agents/reflector.md.jinja: Reflector extracts reusable lessons, but has no memory frontmatter. It only emits lesson suggestions to the caller.
• src/mapify_cli/templates_src/skills/map-learn/SKILL.md.jinja: /map-learn reads existing .claude/rules/learned/*.md, calls subagent_type="reflector", then the skill writes learned rules. Learning is optional and post-workflow.
• src/mapify_cli/templates_src/hooks/map-memory-capture.py.jinja, map-memory-recall.py.jinja, map-memory-finalize.py.jinja: MAP already has top-level session memory hooks, but these are session/user-prompt hooks, not role-local Claude subagent memory.
• src/mapify_cli/templates_src/hooks/workflow-gate.py.jinja: already exempts ~/.claude/projects/*/memory/ paths and .claude/rules/learned/*.md, but not .claude/agent-memory/** explicitly in the Claude template hook checked here.
• src/mapify_cli/templates_src/agents/monitor.md.jinja, predictor.md.jinja, evaluator.md.jinja, research-agent.md.jinja: no memory frontmatter.
• Existing in-run failure memory is implemented in src/mapify_cli/templates_src/map/scripts/map_step_runner.py.jinja around record_failure_signature, but it is branch/subtask retry memory, not persistent subagent memory.

Existing issue search

Commands/queries checked:

• gh issue list --repo azalio/map-framework --state all --limit 120 --search "subagent OR sub-agent OR agent frontmatter OR persistent memory OR memory field OR tools allowlist OR disallowedTools OR permissionMode OR maxTurns OR isolation worktree OR background agents"
• gh issue list --repo azalio/map-framework --state all --limit 80

Related issues inspected:

• BMAD-style named agent personas with persistent identity and 3-layer customization #290 BMAD-style named personas with persistent identity: persona/identity/customization, not Claude memory frontmatter or .claude/agent-memory policy.
• Intra-run failure memory: fail-twice→guardrail-sign + per-attempt reflexion fed back next iteration #253 intra-run failure memory: same-subtask anti-repeat retry constraints, not cross-session role-local memory.
• Scope learned rules by module/path — hierarchical rule loading from agentic engineering model #280 scoped learned rules: filters .claude/rules/learned by paths, not subagent-private memory.
• [Agent Skills] Add day-one project domain skill bootstrap #338 day-one project domain skill bootstrap: domain skill docs, not per-agent memory lifecycle.

Why this is not already covered

MAP has two memory mechanisms today: /map-learn writes project learned rules after a run, and session-memory hooks recall/finalize top-level session context. Claude docs make a separate point: a non-fork subagent starts fresh and does not inherit main auto memory, so role-local subagent memory needs explicit memory frontmatter. No current MAP Claude agent template uses that field.

Problem

The agents that most need calibrated historical context, especially Reflector and possibly review/evaluation roles, relearn their own role-specific lessons from scratch unless the main workflow explicitly injects learned rules. That misses a native Claude Code mechanism for role-local memory, but enabling it naively would also expand Write/Edit capabilities and add a new committed or local artifact surface.

Proposed slice

Add an eval-gated experiment for role-local persistent memory, starting with the safest learning-oriented agent rather than every agent:

1. Add config flag, for example claude_agents.persistent_memory = off|local|project, default off.
2. When enabled, add memory: local or memory: project only to selected learning/review agents after a written allowlist. Initial candidate: reflector.
3. Add .gitignore/manifest/policy handling for .claude/agent-memory-local/**; for .claude/agent-memory/**, require explicit project opt-in because it may be committed.
4. Update workflow-gate/path exemptions only for the exact memory directories and only for markdown memory files if practical.
5. Add a small eval or smoke that shows Reflector consults memory without duplicating /map-learn rules and without writing outside the allowed memory path.

Acceptance criteria

• Default mapify init behavior remains unchanged: no subagent memory field unless config opts in.
• The first opt-in target is a narrow allowlist, not all agents.
• Enabling memory does not allow source-file writes by read-only agents outside the memory directory.
• .claude/agent-memory-local/** is ignored or otherwise not accidentally shipped; .claude/agent-memory/** is documented as project-shared if enabled.
• Tests cover rendered frontmatter for off/local/project modes.
• Tests cover workflow-gate behavior for allowed memory writes and rejected non-memory writes.
• make render-templates, make check-render, and pytest tests/test_skills.py tests/test_template_render.py -v pass.

Guardrails

• Do not add memory: project to Monitor, research-agent, Predictor, or Evaluator by default.
• Do not let Claude memory silently replace /map-learn; role-local memory should complement learned rules, not bypass reviewable rule promotion.
• Do not commit user-local memory by accident.
• Do not broaden workflow-gate exemptions to arbitrary files under .claude/.