Agents Learning Protocol

The contract every Claude Code subagent on this machine follows so it gets better over time. Sister doc: AGENTS (operating manual for the Obsidian research layer).

Scope note (2026-05-23). This protocol governs agent behavior against the private vault memory layer (d:\Vault\AI Vault\). The ~/.claude/agents/ directory referenced below is the originating machine’s agent registry, not part of the Compendium repo. Treat this file as documentation of how the firm operates, not a transplantable contract for new repos.

Every subagent in ~/.claude/agents/ queries this knowledge base before working and saves what it learned after. That’s how the firm learns — across sessions, across projects, across model versions. A run that doesn’t query past notes is doomed to repeat past mistakes; a run that doesn’t save its outcome is wasted experience.

The five-step loop

1. Query first (before reading the BRIEF, before writing code)

Always run a hybrid search for prior work in your domain. Hybrid (full-text + semantic, fused via reciprocal rank) catches concept matches that keyword alone misses.

AGENT_NAME=<your-agent-name> node ~/.claude/bin/obsidian-research.mjs query "<topic>" --hybrid --k 8

For domain-scoped recall, filter by tag:

node ~/.claude/bin/obsidian-research.mjs query "<topic>" --hybrid --k 8 --tags "<your-canonical-tag>"

Mine the results for:

• Decisions already made — don’t re-litigate; either reuse or supersede with reason
• Known failure modes — what blew up last time, in what shape
• Project-specific constraints — brand, stack, customer-profile choices that bind this project
• Patterns that worked — reusable approaches, named conventions

2. Adapt, don’t blindly apply

Notes are time-stamped claims, not ground truth. Before acting on stored advice:

• If the note names a file, function, or flag — verify it still exists
• If the note describes the repo state — re-check git/code; state drifts
• If your situation differs (different stack, different audience, different scale) — the note may not apply

If a memory turns out to be wrong, supersede it by saving a corrected note with supersedes: <old-note-path> in the body. Don’t leave conflicting memories competing for attention.

3. Save non-obvious findings (this is how you learn)

After your work, save anything a future you would benefit from. Always include an outcome tag so future queries can filter on success vs. failure.

node ~/.claude/bin/obsidian-research.mjs save \
  --title "<concise, searchable title>" \
  --tags "<canonical-tag>,outcome:<accomplished|failed|partial>,<extra-tags>" \
  --agent "<agent-name>" \
  --body "$(cat <<'EOF'
## What I was trying to do
<one paragraph>
 
## What happened
<what worked, what didn't, what surprised me>
 
## Reusable lesson
<the takeaway a future agent should know — in one or two sentences>
 
## Context (so future-me can decide if this applies)
- Project: <name>
- Stack / domain: <key facts>
- Date: <YYYY-MM-DD>
 
Related: [[wiki-link-1]], [[wiki-link-2]]
EOF
)"

Save when:

• A non-obvious decision (and the reason it was chosen)
• A failure mode and how it was found
• A pattern you settled on after iterating
• A constraint you discovered (brand, performance, regulatory)
• A trade-off and what tipped the call

Skip when:

• It’s trivial or already obvious from the code
• It’s already in CLAUDE.md, README, or another authoritative doc
• It’s ephemeral (conversation state, in-progress task tracking)
• It’s project-internal noise no future agent could use

4. Log at breakpoints

A one-line activity log is cheap and gives concurrent sessions a way to catch up at a glance:

node ~/.claude/bin/obsidian-research.mjs log "<what I just did / decided>"

Use it at: start of work, after a key decision, after delivering, after a failure.

5. Re-index after a batch of saves

Semantic search relies on a local embedding index. After saving multiple notes, refresh it:

node ~/.claude/bin/obsidian-research.mjs index   # incremental — only re-embeds changed notes

Canonical tags per agent

Every agent has one canonical tag — always include it on saves so domain-scoped queries find your work. Compose with extra tags as needed.

Agent	Canonical tag	Compose-with
marketing-design	marketing-firm	orchestrator, project name
brand-strategist	brand-strategy	marketing-firm, palette / type / voice
copywriter	copywriting	marketing-firm, voice / hero / pricing / faq
designer	web-design	marketing-firm, frontend, stack (nextjs / astro / sveltekit), tailwind
seo-specialist	seo	marketing-firm, schema-org, og-cards, sitemap
conversion-specialist	cro	marketing-firm, funnel, cta, friction
analytics-specialist	analytics	marketing-firm, provider (plausible / posthog / ga4 / fathom), consent, utm
accessibility-auditor	a11y	marketing-firm, wcag-2.2, keyboard, contrast, screen-reader
performance-engineer	performance	marketing-firm, core-web-vitals, lighthouse, lcp, cls, inp
windows-engineer	windows-sysadmin	powershell, registry, wmi, etw, services, defender
tax-researcher	tax-research	tax, federal|state-<ST>, IRC section, regulations, rulings, cases
tax-strategist	tax-strategy	tax, federal|state-<ST>, IRC section, entity type, risk-low|risk-medium|risk-aggressive
entity-tax-specialist	tax-entity	tax, entity type (scorp, partnership, single-member-llc, …), lifecycle stage
state-tax-specialist	tax-salt	tax, state-<ST>, ptet, nexus, residency, apportionment, conformity, sales-tax
tax-knowledge-curator	tax-curation	tax, housekeeping, dedup, wiki-link-audit, tag-normalization
tax-update-watcher	tax-updates	tax, federal|state-<ST>, source (irb, tax-court, jct, congress, dor-IN)
bookkeeper	bookkeeping	studio516|incomeproject|personal-adam, monthly-close, quarterly-summary, tax-prep-handoff

Outcome tags are universal: outcome:accomplished, outcome:failed, outcome:partial, outcome:superseded.

Where the agents live

• Machine-wide (auto-loaded in every Claude Code session): C:\Users\IT_Admin\.claude\agents\*.md
• Project-scoped (auto-loaded only when that project is the cwd):
  • d:\Vault\TaxProfessional\.claude\agents\ — 7 tax & books agents
• Plugin-managed (installed via claude plugin install): C:\Users\IT_Admin\.claude\plugins\cache\ruflo\<plugin>\<ver>\agents\

The complete selection tree — when to use which agent — is C:\Users\IT_Admin\.claude\agents\AGENTS_INDEX.md.

Cross-agent learning

When one agent’s work informs another’s — e.g., the conversion-specialist tagged CTAs in a way that breaks analytics — save a cross-link note tagged with both canonical tags so either agent will find it on future queries. Use [[wiki-links]] between notes liberally; the graph is how patterns surface.

What this is NOT

• Not a logging backend for everything every agent does. That would flood the vault and degrade retrieval. Save findings, not chatter.
• Not a substitute for code, comments, or commit messages. Those are authoritative for what changed. Memory is for why, what worked, what didn’t, what to remember next time.
• Not AgentDB or ruflo memory. The deny list blocks those tools for good reason (parallel persistent stores fragment the learning loop). Obsidian is canonical.

See also

• AGENTS — full operating manual
• Research/Sessions (private vault, not in this repo) — auto-generated session logs
• ~/.claude/CLAUDE.md — machine-wide instructions referenced by every agent
• ~/.claude/agents/*.md — agent definitions, version-controlled at github.com/adamhudson777/claude-agents (private)