\r \r

Agent Memory Tiers Pro\r

\r

Turn a collection of agents into a production-grade swarm.\r \r The free agent-memory-tiers skill gives your agents memory. This skill gives your swarm structure, quality standards, and self-improvement. It is the difference between "I have some agents running" and "I have a system that gets better over time."\r \r Built from running a 20-agent swarm in production daily for 3+ weeks. Every pattern here solved a real problem.\r \r Requires: agent-memory-tiers installed and configured first.\r \r

What This Adds\r

\r | Component | What It Does |\r |-----------|-------------|\r | Quality Grading Rubric | Score any agent's SOUL.md on 8 criteria. Identify weak spots before they cause failures. |\r | Progressive Disclosure | 3-tier token loading system. Agents only read what they need, when they need it. |\r | Orchestrator Protocol | Patterns for a coordinator agent to manage the whole swarm efficiently. |\r | Self-Improvement Loop | Agents log mistakes and proven approaches. The swarm learns from itself. |\r | Agent Scoring Template | Evaluate and compare agents objectively. Know which ones need work. |\r \r ---\r \r

1. The 8-Point Quality Grading Rubric\r

\r Every agent SOUL.md should be scored on these 8 criteria. Use the rubric when building new agents or auditing existing ones.\r \r

## Agent Quality Rubric\r
\r
| # | Criterion | A (Top Tier) | C (Functional) | F (Broken) |\r
|---|-----------|-------------|----------------|-----------|\r
| 1 | Role Clarity | One sentence, crystal clear, no ambiguity | Vague or tries to do multiple jobs | Missing or contradictory |\r
| 2 | Activation Triggers | Explicit triggers + exclusion conditions | Partial triggers, some guessing | No triggers defined |\r
| 3 | Step-by-Step Workflow | Numbered steps with file paths and tool names | General guidance, some gaps | "Figure it out" |\r
| 4 | Output Format | Exact template with field names and structure | Loose format guidance | No format specified |\r
| 5 | Quality Checklist | Pre-completion validation steps | Partial checks | None |\r
| 6 | Error Handling | Common failures listed with specific fixes | Some error awareness | None |\r
| 7 | Boundaries | Explicit CAN and CANNOT lists | Partial limits | Vague or missing |\r
| 8 | Token Efficiency | Under 300 lines, references externalized | Under 500 lines | Over 500 or bloated with inline data |\r
```\r
\r
**Targets:**\r
- Score A on criteria 1, 2, 4, and 7 (non-negotiable for production agents).\r
- No F on any criterion.\r
- Review and re-score every agent monthly.\r
\r
### How to Score an Agent\r
\r
Read the agent's SOUL.md top to bottom. For each criterion, assign A/C/F based on the rubric. Record the scores.\r
\r
```markdown\r
## Agent Scorecard: [AGENT_NAME]\r
\r
Date: YYYY-MM-DD\r
Scored by: [human or auditor agent name]\r
\r
| Criterion | Score | Notes |\r
|-----------|-------|-------|\r
| Role Clarity | A | "Security monitor for production." Clear. |\r
| Activation Triggers | C | Lists triggers but no exclusion conditions. |\r
| Workflow | A | 12 numbered steps with file paths. |\r
| Output Format | A | JSON template with required fields. |\r
| Quality Checklist | C | 2 checks, should have 4-5. |\r
| Error Handling | F | No failure scenarios listed. |\r
| Boundaries | A | CAN: scan logs, alert. CANNOT: restart services, modify configs. |\r
| Token Efficiency | A | 240 lines, refs externalized. |\r
\r
**Overall: 5A / 2C / 1F — Priority fix: add error handling.**\r
```\r
\r
### Fixing Common Score Failures\r
\r
**Role Clarity F → A:**\r
\r
```markdown\r
# BAD (F):\r
You help with various tasks related to content and social media and marketing.\r
\r
# GOOD (A):\r
You are WRITER. You draft social media posts for 4 accounts (2 LinkedIn, 2 X).\r
You do NOT publish, schedule, or manage engagement. You only write drafts.\r
```\r
\r
**Error Handling F → A:**\r
\r
```markdown\r
# BAD (F):\r
(nothing — agent has no idea what to do when things break)\r
\r
# GOOD (A):\r
## Error Handling\r
\r
| Error | Cause | Fix |\r
|-------|-------|-----|\r
| "File not found: LEADS.md" | First run, file does not exist yet | Create LEADS.md with header template, then continue |\r
| "API rate limit reached" | Too many requests this session | Stop current task, update L0 flags: "Rate limited — retry next activation" |\r
| "Output exceeds 20,000 chars" | Response too large for workspace file | Split into multiple files: output-part1.md, output-part2.md |\r
| "Tool call failed: web_search" | Network issue or API key expired | Skip web search, use cached data from last run, flag in L1 blockers |\r
```\r
\r
**Boundaries F → A:**\r
\r
```markdown\r
# BAD (F):\r
Be careful and don't do anything dangerous.\r
\r
# GOOD (A):\r
## Boundaries\r
\r
**CAN:**\r
- Read and write files in own workspace\r
- Search the web for public information\r
- Draft content for human review\r
\r
**CANNOT:**\r
- Post, publish, or send anything externally (all output goes to approval queue)\r
- Access other agents' workspaces (read their L0 only via orchestrator)\r
- Install packages, modify system config, or run shell commands\r
- Spend money or commit to deadlines on behalf of the user\r
```\r
\r
---\r
\r
## 2. Progressive Disclosure (Token Efficiency System)\r
\r
Not every activation needs the full SOUL.md. Load information in tiers to minimize token cost.\r
\r
```markdown\r
## Progressive Disclosure Tiers\r
\r
| Tier | What Loads | When | Token Cost |\r
|------|-----------|------|------------|\r
| T1: Identity | L0.md (4 lines) + role sentence from SOUL.md | Every activation | ~50-100 tokens |\r
| T2: Context | L1.md (rolling 7-day state) | Every activation | ~100-200 tokens |\r
| T3: Full Instructions | Complete SOUL.md | When agent activates on a matching trigger | Full SOUL.md cost |\r
| T4: References | External docs from references/ folder | Only when task explicitly needs them | On demand |\r
\r
## Rules:\r
- SOUL.md must stay under 500 lines. If it exceeds this, externalize reference material.\r
- Large data files (logs, queues, trackers) go in workspace, NOT in SOUL.md.\r
- Tables and templates are more token-efficient than prose. Prefer structured formats.\r
- If a section of SOUL.md is only used for 1 out of 10 activations, move it to references/.\r
```\r
\r
### SOUL.md Size Budgets\r
\r
```markdown\r
## SOUL.md Section Budget\r
\r
| Section | Max Lines | Purpose |\r
|---------|-----------|---------|\r
| Role + Identity | 5 | Who am I, one sentence purpose |\r
| Quick Context (L0/L1 loader) | 5 | Pointer to memory files |\r
| Activation Triggers | 10 | When to wake up, when NOT to |\r
| Core Workflow | 60-80 | Numbered steps for primary tasks |\r
| Output Templates | 40-60 | Exact format for deliverables |\r
| Quality Checklist | 10-15 | Pre-completion validation |\r
| Error Handling | 15-20 | Failure table |\r
| Boundaries | 10-15 | CAN/CANNOT lists |\r
| End-of-Run (L0/L1 update) | 15 | Memory update mandate |\r
| **TOTAL** | **~200-300** | **Target range for production agents** |\r
```\r
\r
### Externalizing References\r
\r
When SOUL.md gets too large, move supporting material to separate files.\r
\r
```markdown\r
## Reference Externalization Pattern\r
\r
In SOUL.md, replace large sections with pointers:\r
\r
  For detailed style guidelines, read `references/STYLE_GUIDE.md`.\r
  For the full client list and history, read `references/CLIENTS.md`.\r
  For API endpoint documentation, read `references/API_DOCS.md`.\r
\r
Rules:\r
- Agent reads reference files ONLY when the current task needs them.\r
- Never inline reference content back into SOUL.md.\r
- Reference files have no size limit but should be focused (one topic per file).\r
- Update references independently of SOUL.md — they are living documents.\r
```\r
\r
---\r
\r
## 3. Orchestrator Coordination Protocol\r
\r
When one agent (the orchestrator) manages a swarm of specialist agents, use these patterns.\r
\r
### Swarm Status Check\r
\r
```markdown\r
## Orchestrator: Morning Status Check\r
\r
1. Read L0.md for every agent in the swarm.\r
2. Build a status table:\r
\r
| Agent | Focus | Last Active | Flags |\r
|-------|-------|-------------|-------|\r
| WRITER | Draft LinkedIn posts | 2026-03-16 | None |\r
| SCOUT | Find 5 leads this week | 2026-03-16 | None |\r
| WATCHDOG | Monitor v2.4 deploy | 2026-03-15 | Grafana intermittent |\r
\r
3. Flag any agent with:\r
   - Last active > 48 hours ago (may be stuck or disabled)\r
   - Non-empty flags (needs attention)\r
   - Focus misaligned with current priorities\r
\r
4. Present status brief to human operator. Do NOT auto-reassign tasks.\r
```\r
\r
### Task Routing\r
\r
```markdown\r
## Orchestrator: Task Routing Protocol\r
\r
When a new task arrives:\r
\r
1. Identify which agent's role matches the task.\r
2. Read that agent's L0.md — check flags for blockers.\r
3. Read that agent's L1.md "Blockers" section — confirm agent is not stuck.\r
4. If agent is clear:\r
   - Route the task with a structured brief: WHAT (task), WHY (context), DEADLINE (if any), OUTPUT (expected deliverable format).\r
5. If agent is blocked:\r
   - Check if a backup agent can handle it.\r
   - If no backup, escalate to human operator with: blocked agent name, blocker description, suggested fix.\r
6. Never route a task to an agent whose L0 flags indicate it cannot execute right now.\r
```\r
\r
### Cross-Agent Handoffs\r
\r
```markdown\r
## Orchestrator: Handoff Protocol\r
\r
When Agent A's output feeds into Agent B's input:\r
\r
1. Agent A completes its task and writes output to a shared handoff file:\r
   `workspace/handoffs/[AGENT_A]-to-[AGENT_B]-YYYY-MM-DD.md`\r
\r
2. Agent A updates its L0.md line 3: "Handed off [deliverable] to [AGENT_B]."\r
\r
3. Orchestrator reads Agent A's L0, confirms handoff file exists.\r
\r
4. Orchestrator triggers Agent B with:\r
   - Pointer to the handoff file\r
   - Context: what Agent A produced and why\r
   - Expected output format\r
\r
5. Agent B reads the handoff file, executes its task, writes output.\r
\r
6. Agent B updates its L0.md and L1.md as normal.\r
\r
Rules:\r
- Handoff files are write-once. Agent B never modifies Agent A's output.\r
- Handoff files older than 7 days can be archived to handoffs/archive/.\r
- If the handoff file is missing or malformed, Agent B stops and flags the orchestrator.\r
```\r
\r
---\r
\r
## 4. Self-Improvement Protocol\r
\r
The swarm should get better over time. These two files make that happen.\r
\r
### Lessons File\r
\r
Create `workspace/lessons.md` in your main workspace. Any agent (or human) can append to it.\r
\r
```markdown\r
# Lessons Learned\r
\r
Format: Date | Category | What Happened | Root Cause | Fix Applied\r
\r
## Template:\r
- YYYY-MM-DD | [agent/system/workflow] | [what went wrong] | [why] | [what we changed]\r
\r
## Examples:\r
- 2026-03-05 | agent | HERALD used wrong model, task failed | Model ID was invalid for provider | Updated all agents to correct model in config\r
- 2026-03-08 | workflow | Agent output exceeded file size cap | No size check before write | Added pre-write size validation to SOUL.md workflow\r
- 2026-03-10 | system | Credentials exposed in config file | Env vars stored in committed file | Moved secrets to .env.local, rotated all keys\r
- 2026-03-12 | agent | SCOUT searched wrong platforms | Activation trigger too broad | Added exclusion conditions to SOUL.md triggers\r
```\r
\r
### Patterns File\r
\r
Create `workspace/patterns.md` in your main workspace. When something works well, record it.\r
\r
```markdown\r
# Proven Patterns\r
\r
Format: Pattern Name | When to Use | How It Works\r
\r
## Template:\r
### [Pattern Name]\r
**When:** [situation where this applies]\r
**How:** [step by step]\r
**Why it works:** [one sentence]\r
\r
## Example:\r
### Batch-Then-Review\r
**When:** Agent needs to produce multiple outputs (posts, reports, emails).\r
**How:** Generate all items in one run. Write to a review queue file. Human reviews the batch. Approved items move to the action queue.\r
**Why it works:** One activation for N outputs is cheaper than N activations for N outputs. Batch review is faster for the human too.\r
```\r
\r
### Monthly Swarm Audit\r
\r
```markdown\r
## Monthly Audit Checklist\r
\r
Run this on the 1st of every month:\r
\r
1. Score every agent using the 8-point rubric. Record in scorecards/.\r
2. Review lessons.md — are the same mistakes repeating? If yes, the fix was insufficient.\r
3. Review patterns.md — are proven patterns actually being used? If not, add them to SOUL.md workflows.\r
4. Check L0/L1 freshness — any agent with "Last run" older than 14 days is either unused or broken.\r
5. Check SOUL.md sizes — any over 400 lines needs externalization.\r
6. Archive old handoff files (> 7 days) and resolved blockers.\r
7. Update the orchestrator's agent roster with any new or retired agents.\r
\r
Output: One-page swarm health report for the human operator.\r
```\r
\r
---\r
\r
## 5. Agent Scoring and Comparison\r
\r
Use this template to track agent quality over time.\r
\r
```markdown\r
## Swarm Scorecard — YYYY-MM\r
\r
| Agent | Role | Clarity | Triggers | Workflow | Output | Quality | Errors | Bounds | Tokens | Grade |\r
|-------|------|---------|----------|----------|--------|---------|--------|--------|--------|-------|\r
| WRITER | Content | A | A | A | A | C | A | A | A | 7A 1C |\r
| SCOUT | Leads | A | A | C | A | C | C | A | A | 5A 3C |\r
| WATCHDOG | Security | A | C | A | A | A | F | A | A | 6A 1C 1F |\r
\r
**Swarm Average:** X.X / 8.0\r
**Weakest Criterion (swarm-wide):** [identify which criterion has the most C/F scores]\r
**Priority Fix:** [one action item to raise the weakest area]\r
```\r
\r
### Tracking Improvement Over Time\r
\r
```markdown\r
## Swarm Quality Trend\r
\r
| Month | Agents | Avg Score | A% | C% | F% | Top Agent | Needs Work |\r
|-------|--------|-----------|----|----|----|---------|-----------|\r
| 2026-03 | 20 | 6.8 | 78% | 18% | 4% | LEDGER | WATCHDOG |\r
| 2026-04 | 22 | 7.1 | 82% | 16% | 2% | LEDGER | SCOUT |\r
\r
Target: 85%+ A scores, 0% F scores within 3 months of deployment.\r
```\r
\r
---\r
\r
## Permissions\r
\r
This skill requires:\r
- **File read/write** in agent workspace directories — to manage L0.md, L1.md, scorecards, lessons, patterns, and handoff files.\r
- **File read** across agent workspaces — orchestrator needs to read other agents' L0.md files (read only, never write).\r
- No network access required.\r
- No external API access required.\r
- No sensitive data access required.\r
\r
## Credits\r
\r
Built and battle-tested by the Megaport swarm team across a 20-agent production deployment. Quality rubric inspired by Anthropic's skill-building guidelines and the OpenViking tiered memory architecture.\r
\r
## License\r
\r
MIT — use it, modify it, share it.\r