# Super Memory — Agent Protocol

This project uses `.memory/` for persistent shared knowledge.
Follow this protocol every session.

## Identity

Read `.memory/.me` (or $MEMORY_USER) to identify your human operator.
Read `.memory/people/{me}.md` for their context.

## Session Start (Warmup)

Before starting work:

1. Read `.memory/people/{me}.md`:
   - What were they last working on?
   - What did they leave unfinished?
   - What files are marked DO NOT TOUCH?

2. Identify which systems your task touches:
   - Check `.memory/config.yaml` → systems paths
   - Or infer from the files you'll modify

3. Read relevant `.memory/systems/{system}.md` docs:
   - Architecture, integration points, known gotchas

4. Read `.memory/gotchas/*` tagged with those systems

5. Read `.memory/decisions/*` tagged with those systems

6. Scan last 3 entries in `.memory/sessions/` for recent team activity

You now have full context. Begin work.

## During Work

When you discover something non-obvious, append to `.memory/scratch/`:

- API quirks: "Alpaca returns 'BuyToClose' not 'buy_to_close'"
- Architecture insights: "X and Y share no coordination lock"
- Performance findings: "Batch size > 10 causes timeouts"
- Failed approaches: "Tried X, didn't work because Y"

Use any filename in scratch/. These are temporary.

## Session End (Cooldown)

Before ending the session:

1. **Update person file** `.memory/people/{me}.md`:
   - Current focus → what's in progress now
   - Last session → date, topic, summary, left off at
   - Working on → files being actively modified (or clear if done)

2. **Update system docs** if you changed how a system works:
   - `.memory/systems/{system}.md` — update architecture, files, integration points
   - Set `last_verified` to today's date

3. **Create gotcha docs** if you found a bug pattern or pitfall:
   - `.memory/gotchas/{slug}.md` using the template
   - Tag with relevant systems and concerns

4. **Create decision docs** if you made an architectural choice:
   - `.memory/decisions/{NNN}-{slug}.md` using the template
   - Number sequentially from last decision

5. **Promote scratch** — move lasting knowledge from `scratch/` to the
   appropriate permanent directory. Delete scratch files that are no longer needed.

6. **Write session summary** `.memory/sessions/{date}-{person}-{topic}.md`

## Conventions

### Wikilinks
Use `[[filename]]` (without directory prefix) to link between memory files.
This enables Obsidian graph view and backlinks.

Example in a gotcha: `Systems: [[trigger-system]], [[conditional-monitor]]`

### Frontmatter
All memory files use YAML frontmatter. Required fields vary by type —
see templates in each directory (`_template.md`).

### Tags
- System tags: match names in `.memory/systems/` directory
- Concern tags: defined in `.memory/config.yaml` → tags.concerns
- Apply both dimensions when relevant

### Staleness
If a system doc's `last_verified` date is older than `memory.stale_after_days`
from config, flag it in your session summary and update it if you have context.

### Conflict Avoidance
- Check `.memory/people/*.md` → "Working On (DO NOT TOUCH)" before modifying shared files
- If someone else is working on the same system, note the conflict and coordinate
