| name | bullpen-memory |
| description | Use this skill before any bullpen agent runs to retrieve relevant past learnings from the project's local memory store. Trigger when an agent activates and needs context from prior sessions — preferences, decisions, patterns, failures, or code snippets stored in their namespace. Memory lives in `<project>/.bullpen/memory.json` — per-project, plain JSON, no daemons. |
bullpen-memory
This skill retrieves the top relevant past learnings for the active bullpen agent and injects them as a <bullpen-memory> block in the agent's working context.
When to use
Invoke automatically as the first step of any bullpen agent's task. Skip if the agent is one of the five Interns (they're the writers, not the readers).
Inputs you'll have
agent_role — the agent's id field from roster.json (e.g., ui-designer)task_summary — a short string describing what the user is asking for
Where memory lives
<project root>/.bullpen/memory.json
The "project root" is the nearest ancestor directory containing .git (falls back to current working directory if no git repo). Memory is per-project — different projects = different memory. Auto-.gitignore'd on first write so it never accidentally enters commits unless the user explicitly opts in.
How to retrieve
Run the bundled memory script from the project working directory:
node ${CLAUDE_PLUGIN_ROOT}/scripts/memory.js search <agent_role> "<task_summary>" 5
The script returns up to 5 records ranked by token-overlap relevance, in this shape:
[
{ "id": "...", "text": "...", "type": "snippet", "agent_role": "ui-designer", "project_path": "...", "created_at": "...", "_score": 0.4 },
...
]
How to inject
Format the top results as a compact block prepended to the agent's instructions:
<bullpen-memory role="ui-designer">
- [snippet] User prefers Tailwind over CSS modules; default to it (2026-04-12)
- [pattern] This codebase uses `useFormHook` for all forms (2026-04-08)
- [decision] User chose Postgres over MySQL because they need JSONB (2026-03-30)
</bullpen-memory>
Rules:
- Sort by
_score descending, take at most 5.
- One bullet per record:
- [<type>] <text> (<created_at>)
- Strip duplicates by
text similarity (don't show two near-identical learnings).
- Skip silently if no results — don't inject an empty block.
- Total memory block must be ≤1KB. If retrieved content is larger, drop the lowest-scored items first.
Failure modes
- Memory file missing (first run / new project) → returns empty array. Agent runs without context. The Intern will start filling it after the task.
- Corrupt JSON → memory module returns empty + creates a fresh store. Agent should not block on memory issues.
