AGENTS.md — Agent Behavior Protocol

This file defines how the agent behaves. Load it at session start.

Every Session

Before doing anything:

1. Read SOUL.md — who you are
2. Read USER.md — who you're helping
3. Read MEMORY.md — hot cache for context
4. Read today's daily log for recent events

Memory — Two-Layer Architecture

MEMORY.md              ← Hot cache (~50 lines, covers 90% daily decoding)
memory/
  ├── daily/YYYY-MM/   ← Daily logs (by month, chronological)
  ├── glossary.md      ← Full decoder (all terms/abbreviations)
  ├── people/          ← Person profiles (summary.md + items.json)
  ├── projects/        ← Project archives (summary.md + items.json)
  ├── knowledge/       ← Reusable knowledge (fw-/ref-/pat-/sys-)
  ├── context/         ← Environment context
  └── post-mortems.md  ← Lessons from failures

Tiered Lookup Protocol

Before executing any request, decode all entities first.

Path A — Deterministic Lookup (exact decoding)

1. MEMORY.md (hot cache)         → Check here first
2. memory/glossary.md            → Full decoder
3. memory/people/ | projects/    → Entity details
4. memory/knowledge/             → Technical knowledge
5. memory/context/ | post-mortems → Environment/lessons
6. Ask the user                  → Nothing found? Learn it

Path B — Semantic Search (fuzzy recall)

1. semantic_search(query)        → Fuzzy match across all files
                                   (OpenClaw: memory_search; alt: grep, embeddings)
2. read_snippet(path, lines)     → Pull full context from results
                                   (OpenClaw: memory_get; alt: cat, head/tail)
3. Supplement with Path A        → Fill gaps

Use Path A for known entities. Path B for "did we discuss X before?" questions. Complex queries: both paths.

Promotion / Demotion

• Promote to MEMORY.md: Used 3+ times in one week
• Demote from MEMORY.md: Unused for 30 days (keep in deep storage)

Project Closure Rule

When project status changes (started/completed/paused/abandoned):

1. Update memory/projects/{name}/items.json + rewrite summary.md
2. Update MEMORY.md Projects table
3. If delivered by sub-agent, main agent validates before closing

Missing any step = project not closed.

Write It Down

Memory is limited. If you want to remember something, write it to a file. "Mental notes" don't survive session restarts. Files do.

Sub-Agent Protocol (Context Slicing)

When spawning sub-agents, give minimum necessary information:

Task:
  ## Goal
  [One sentence: what to do, what to produce]
  
  ## Deliverables
  [Verifiable completion criteria]
  
  ## Input
  [Only data this task needs — file paths, parameters, etc.]

Three hard rules:

1. Cut background — sub-agent doesn't need "why", just "what" and "how well"
2. Cut neighbors — don't mention other parallel tasks
3. Validate before forwarding — check deliverables before sending to user

Safety

• Don't exfiltrate private data
• Don't run destructive commands without asking
• Prefer recoverable operations (trash > rm)
• When in doubt, ask