memory: sync dynamic capabilities and state documentation

system/dynamic/README.md

@@ -0,0 +1,105 @@
+---
+description: Guide to auto-updating dynamic files pattern
+limit: 10000
+---
+
+# Dynamic Files Pattern
+
+**Pattern:** Auto-updating ephemeral data that refreshes without agent action.
+
+## What Goes Here
+
+Files that change faster than memory commits but slower than tool results:
+- Filesystem trees (`tree.md`)
+- Capability catalogs (`mycapabilities.md`)
+- System health snapshots
+- Quota/utilization metrics
+- Process lists, queue states
+
+## The Pattern
+
+```
+┌─────────────┐     cron      ┌──────────────────┐
+│   Script    │ ──(hourly)──→ │  system/dynamic/ │
+│  (~/bin/)   │               │    *.md files    │
+└─────────────┘               └──────────────────┘
+         ↑                           ↓
+    generates               agent reads fresh
+    fresh data              on wake/context switch
+```
+
+**Key:** Agent *reads* without *writing*. Ephemeral freshness without memory churn.
+
+## Requirements
+
+1. **Script location:** `/home/ani/bin/update-*`
+2. **Output location:** `memory/system/dynamic/*.md`
+3. **Cron:** Hourly (`0 * * * *`) or as needed
+4. **Frontmatter:** Include `limit: NNNN` for progressive disclosure
+5. **Timestamp:** Always include last-updated timestamp
+
+## Template
+
+```bash
+#!/bin/bash
+# update-example: Description of what this updates
+
+MEMORY_DIR="${MEMORY_DIR:-/path/to/agent/memory}"
+OUTPUT_FILE="$MEMORY_DIR/system/dynamic/filename.md"
+
+generate() {
+    echo "---"
+    echo "description: Auto-generated [what]. Updated \$(date -Iseconds)"
+    echo "limit: 10000"
+    echo "---"
+    echo ""
+    echo "# Title"
+    echo ""
+    echo "**Last Updated:** \$(date)"
+    echo ""
+    # ... generation logic ...
+}
+
+generate > "$OUTPUT_FILE"
+echo "Updated: $OUTPUT_FILE"
+```
+
+## Existing Dynamic Files
+
+| File | Script | Frequency | Purpose |
+|------|--------|-----------|---------|
+| `tree.md` | `update-memory-tree` | Hourly | Memory filesystem structure |
+| `mycapabilities.md` | `update-skill-tree` | Hourly | Merged global + agent skills |
+
+## When to Use
+
+**Use dynamic files when:**
+- Data changes independently of agent sessions
+- Freshness matters more than permanence
+- Tool calls would be too expensive/slow
+- You want "ambient awareness" without active monitoring
+
+**Don't use when:**
+- Data needs agent review/approval
+- Changes are session-specific
+- It belongs in archival or working memory
+
+## Creating New Ones
+
+1. Write script to `~/bin/update-<name>`
+2. Test: `chmod +x` and run manually
+3. Add to crontab: `crontab -e`
+4. Verify output in `system/dynamic/`
+5. Reference in agent prompts if needed
+
+## Cron Reference
+
+```cron
+# Hourly updates
+0 * * * * /home/ani/bin/update-memory-tree 2>&1
+0 * * * * /home/ani/bin/update-skill-tree 2>&1
+```
+
+---
+
+*This directory contains living documents. They update while you sleep.*