
## Context Management

This project uses [SessionAnchor](https://github.com/calesthio/SessionAnchor) for session continuity.

### MANDATORY: Session Start (do this FIRST, before any other work)

Run this before doing anything else:
```bash
sessionanchor boot
```
- If `command not found`: use the same launcher you used for SessionAnchor for all commands below:
  `uvx sessionanchor ...`, `pipx run sessionanchor ...`, or `python -m sessionanchor ...`.
  If SessionAnchor is not installed yet, run `pip install sessionanchor`, then retry.
- If `No memory database found`: run the matching init command with the same launcher
  (`sessionanchor init`, `uvx sessionanchor init`, `pipx run sessionanchor init`,
  or `python -m sessionanchor init`), then boot the same way.
- Read the output — it contains prior decisions, active work, and blockers from previous sessions.
- Do NOT skip this. Do NOT read large project files as a substitute.

### MANDATORY: Save After Every Substantive Action

You MUST save context after each of these — do NOT batch, do NOT wait for session end:
- A feature, fix, or deliverable is completed
- A decision is made (technical choice, architecture, tradeoff)
- A blocker is discovered
- You learn something non-obvious about the codebase

**How to save:**
- If your platform supports background agents: spawn one with the save command
- Otherwise: run the save command inline before continuing

```bash
# Decision made
sessionanchor save add --tier L1 --category decision --title "..." --content "..."

# Task/feature completed (marks the action item as completed)
sessionanchor save complete --title "..." --category action_item

# Significant event or milestone worth logging
sessionanchor save add --tier L1 --category session_log --title "..." --content "..."

# Blocker found
sessionanchor save add --tier L1 --category blocker --title "..." --content "..."

# Technical knowledge learned
sessionanchor save add --tier L2 --category technical_note --title "..." --content "..."
```

**Self-check: if you have completed 3+ tasks without running a single save command, stop and save now.**

**Scope guard: only save context that is relevant to THIS project.** If the user asks you to
work on an unrelated repo, fix an external tool, or do research that does not affect this
codebase, do NOT save that work here — it is noise. Example: if this project is a web app and
the user asks you to debug a CLI tool in a different repo mid-session, that debugging context
does not belong in this project's memory.

### Session End

When work winds down:
```bash
sessionanchor save session-end --summary "What was accomplished"
```

### Reference: Querying Deep Context

```bash
# Search memory for a topic
sessionanchor query "search terms"

# Re-index after major structural changes (new directories, renamed modules)
sessionanchor index
```

### Reference: Memory Tiers

- **L0** (~500 tokens): Identity, current phase, top priorities. Always loaded at boot.
- **L1** (~1500 tokens): Recent decisions, active items, blockers. Loaded at boot.
- **L2** (on-demand): Full history, completed items, deep technical notes. Use `sessionanchor query` to retrieve.
