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.

Scope: write boundaries

The learning loop writes to exactly one place — the user’s private vault — and explicitly does not write to the Compendium content layer or to other projects. Codified per Conventions § “Compendium is read-only with respect to other projects” and AGENTS § “Cross-project rule (locked 2026-05-25)”:

• Saves via obsidian-research.mjs save land in the private vault at d:\Vault\AI Vault\Research\Topics\ (or whatever --folder overrides to, still inside that vault). This is allowed under the cross-project rule’s exception clause for user-personal storage.
• Saves do NOT go into d:\Vault\Compendium\ itself. The Compendium content layer is authored (deliberate, curated reference notes), not auto-generated by the learning loop. A Compendium edit is its own discrete decision — not a side effect of finishing a task. If a lesson genuinely belongs in Compendium long-term, save it to the vault first, then promote it deliberately in a separate step.
• Saves do NOT go into any other project’s repo. No agent writes into d:\Projects\Suits\, d:\Projects\TaxProfessional\, d:\Projects\IncomeProject\, or any future project as part of the learning loop. If a finding is project-specific (e.g., “this Suits routing pattern worked”), the agent surfaces it for the relevant project’s agent to take action — it does not auto-write across the boundary. The vault note is the durable record; the cross-project action is dispatched by the user.

The single-writer discipline keeps the Compendium safe to grow, keeps each project’s history under its own agent’s control, and keeps the learning index honest (every lesson note lives in one searchable place).

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
autonomous-income-strategist	income-strategy	incomeproject, engine (engine-a-filingrail, engine-b-fabric-ext, engine-c-rdpmaster, …), phase (research, ranking, plan, execution), approvals-queue, kill-criteria

Outcome tags

Every lesson save also carries exactly one outcome tag. These are universal — they apply across every canonical tag above, and they’re what makes the post-hoc query “what worked?” / “what didn’t?” cheap and reliable.

Tag	When to apply
outcome:accomplished	The agent did the thing it set out to do, and the result holds up under verification. The “this works, do it again” bucket.
outcome:failed	The attempt did not produce the intended result, and the agent stopped or pivoted. The “don’t repeat this mistake” bucket. Failures are as valuable as successes — save them.
outcome:partial	The agent got somewhere but not all the way (e.g., the test suite passes but one edge case is unhandled; the deploy succeeded but observability is still missing). The “useful progress, but verify before reusing” bucket.
outcome:superseded	A previously-saved note has been replaced by a newer, more correct understanding. Use this tag on the new note, and include supersedes: <old-note-path> in the body so the old note’s claim is visibly retracted.

Pick one, never zero, never more than one. If the run touched multiple subtasks with different outcomes, save multiple notes — one outcome per note keeps the query semantics clean.

Cross-link discipline

Lesson notes are the bridge between durable Compendium knowledge and ephemeral session work. They earn that role only if they actually link both directions. Every lesson save should include [[wiki-links]] to:

• Other lesson notes in the vault’s Research/Topics/ — related findings, prior decisions on the same topic, the superseded note this one corrects. Use the wiki-link form even when the note name is long; the graph view depends on the links being real.
• Compendium reference notes when relevant — the canonical reference doc the lesson confirms, refines, or contradicts. Example: a [[Compute/Claude/prompt-caching]] link from a lesson note that found a cache-breakpoint behavior the Compendium reference glossed over. The Compendium reader follows the link back to lived experience; the lesson reader follows the link forward to the canonical reference.

Two-way linkage is what turns the learning loop from a write-only journal into a navigable graph. A lesson note with no [[links]] is an orphan and probably should be folded into an existing note instead.

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)