## Memory (Mind)

This project uses Mind for persistent memory across sessions.

### Required Protocol

1. **Session Start**: ALWAYS call `mind_recall()` before responding to the first message.

2. **During Work**: Log actively to SESSION.md (ephemeral) and MEMORY.md (permanent):

   **SESSION.md types - USE FREQUENTLY (cleared between sessions):**
   - `mind_log("reading auth module", type="experience")` - What you're doing NOW
   - `mind_log("can't find token validation", type="blocker")` - What's blocking you
   - `mind_log("tried Redis - overkill", type="rejected")` - What didn't work
   - `mind_log("assuming stable internet", type="assumption")` - What you're assuming

   **MEMORY.md types - For important discoveries:**
   - `mind_log("chose X over Y - simpler", type="decision")`
   - `mind_log("Safari needs vendor prefix", type="learning")`
   - `mind_log("API returns 500 on large payloads", type="problem")`
   - `mind_log("resolved by increasing timeout", type="progress")`

### SESSION.md Logging (IMPORTANT)

**Log to SESSION.md frequently as you work.** This prevents loops - repeating failed fixes, forgetting what you tried.

| When | Type | Example |
|------|------|---------|
| Starting a task | `experience` | "investigating login bug" |
| Making an assumption | `assumption` | "assuming user wants client-side validation" |
| Trying an approach | `experience` | "trying Redis for caching" |
| Something didn't work | `rejected` | "Redis too complex for this use case" |
| Getting stuck | `blocker` | "can't find where session is stored" |

**Rule: Log every 2-3 tool calls. If in doubt, log it - SESSION.md clears anyway.**

### Tools Available

- `mind_recall()` - Load context (CALL FIRST!)
- `mind_log(msg, type)` - Log to SESSION.md or MEMORY.md
- `mind_session()` - Check current session state
- `mind_blocker(desc)` - Log blocker + auto-search for solutions
- `mind_search(query)` - Find specific memories
- `mind_remind(msg, when)` - Set reminders

---

<!-- MIND:CONTEXT - Auto-generated by Mind. Do not edit. -->
## Stack
python

## Gotchas
(None yet - add to .mind/MEMORY.md Gotchas section)
<!-- MIND:END -->

# CRITICAL: Call mind_recall() FIRST

**At the start of EVERY session, call `mind_recall()` before doing anything else.**

This loads fresh context, detects session gaps, and ensures you have the latest memory state. The MIND:CONTEXT above may be stale - `mind_recall()` gets live data.

## MCP Tools - When to Use

### Reading Tools
| Tool | When to Use |
|------|-------------|
| `mind_recall()` | **FIRST thing every session** - loads fresh context |
| `mind_session()` | Check current goal, approach, blockers |
| `mind_search(query)` | When MIND:CONTEXT doesn't have what you need |
| `mind_status()` | Check memory health |
| `mind_reminders()` | List pending reminders |

### Writing Tools (USE THESE PROACTIVELY!)
| Tool | When to Use |
|------|-------------|
| `mind_log(msg, type)` | **Log frequently! See types below** |
| `mind_blocker(desc)` | When stuck - logs + auto-searches memory |

**SESSION.md types (ephemeral - log liberally, gets cleared between sessions):**
- `type="experience"` - What's happening right now, raw thoughts, observations
- `type="blocker"` - What's blocking progress
- `type="assumption"` - What you're assuming to be true
- `type="rejected"` - Approaches that didn't work and why

**MEMORY.md types (permanent - important stuff only):**
- `type="decision"` - Choices made and why
- `type="learning"` - Discoveries, gotchas, TILs
- `type="problem"` - Issues encountered
- `type="progress"` - What got fixed/shipped

### Other Tools
| Tool | When to Use |
|------|-------------|
| `mind_remind(msg, when)` | User says "remind me..." |
| `mind_edges(intent)` | Before implementing risky code |
| `mind_checkpoint()` | Force process pending memories |
| `mind_add_global_edge()` | Found a cross-project gotcha |

---

# SESSION.md Logging Protocol (MANDATORY)

**Log actively throughout work, not just at milestones.** SESSION.md prevents within-session loops - you suggesting the same failed fix twice, forgetting what you already tried, losing track of assumptions.

## When to Log

| Moment | Type | Example |
|--------|------|---------|
| Starting any task | `experience` | "reading auth module to understand flow" |
| Making an assumption | `assumption` | "assuming user wants client-side validation" |
| Considering an approach | `experience` | "could use Redis or in-memory cache" |
| Dismissing an approach | `rejected` | "Redis overkill for this - too much infra" |
| Hitting a wall | `blocker` | "can't find where tokens are validated" |
| Noticing something odd | `experience` | "this function has no error handling" |

## Frequency

- **Minimum:** Log at least once every 2-3 tool calls
- **Ideal:** Log whenever your thinking shifts
- **Don't batch:** Log in the moment, not retroactively

## Why This Matters

Without active logging:
- You'll suggest the same failed approach twice
- You'll forget what you assumed vs verified
- Next session starts with zero context on what you tried

With active logging:
- `mind_session()` shows your current mental state
- Rejected approaches prevent loops
- Assumptions are visible to question when stuck

## Quick Reference

```
mind_log("what I'm doing/seeing", type="experience")
mind_log("what I'm treating as true", type="assumption")
mind_log("approach X - didn't work because Y", type="rejected")
mind_blocker("what's stopping me")  # Also auto-searches memory
```

**Rule of thumb:** If in doubt, log it. SESSION.md gets cleared anyway.

---

# Loop & Rabbit Hole Detection

**Check yourself before you wreck yourself.** Call `mind_session()` when any of these happen:

## Warning Signs You're Looping

| Signal | What's Happening |
|--------|------------------|
| Trying a fix for the 2nd time | You forgot it failed before |
| "Let me try one more thing" | You're guessing, not diagnosing |
| Same error after 3+ attempts | Root cause not understood |
| Editing the same file repeatedly | Symptom-chasing, not solving |
| Growing frustration | Time to step back |

## Warning Signs You're in a Rabbit Hole

| Signal | What's Happening |
|--------|------------------|
| Task scope expanded without user asking | You're solving imaginary problems |
| "While I'm here, I should also..." | Feature creep |
| 10+ tool calls without user check-in | Lost in the weeds |
| Can't explain what you're doing in 1 sentence | Lost the thread |
| Original goal feels far away | Drifted off course |

## What To Do

1. **Stop.** Don't try another fix yet.
2. **Call `mind_session()`** - See what you've already tried
3. **Check Rejected section** - Have you tried this before?
4. **Check Assumptions section** - Is something you assumed wrong?
5. **If stuck 3+ times:** Use `mind_blocker()` - it auto-searches memory for solutions
6. **Ask the user** - "I've tried X, Y, Z. Should I keep going or try a different approach?"

## Prevention

- Log every approach **before** trying it: `mind_log("trying X approach", type="experience")`
- Log failures **immediately**: `mind_log("X didn't work - reason", type="rejected")`
- State assumptions upfront: `mind_log("assuming Y is true", type="assumption")`

**The goal:** Never suggest the same failed fix twice. Never drift without noticing.

---

# CLAUDE.md - Mind

## Project Overview

Mind is a file-based memory system for AI coding assistants. The core insight: **The file is the memory. Mind is the lens.**

## Architecture

```
Source of truth: .mind/MEMORY.md (per project)
Session tracking: .mind/SESSION.md (ephemeral, cleared between sessions)
Context delivery: MIND:CONTEXT section in CLAUDE.md (auto-injected)
MCP: 12 tools (recall, log, session, blocker, search, remind, reminders, reminder_done, edges, checkpoint, status, add_global_edge)
```

## Key Files

```
src/mind/
+-- cli.py           # CLI commands (init, add, list, status, etc.)
+-- parser.py        # Loose regex extraction from markdown/comments
+-- context.py       # MIND:CONTEXT generation
+-- detection.py     # Stack detection
+-- storage.py       # Projects registry
+-- templates.py     # File templates
+-- mcp/
    +-- server.py    # 12 MCP tools (stateless)
```

## Design Principles

1. **File is the memory** - MEMORY.md is source of truth
2. **Loose parsing** - Accept natural language, score confidence
3. **Auto context** - CLAUDE.md gets MIND:CONTEXT injected
4. **Multiple capture** - MEMORY.md, inline comments, git commits
5. **Zero friction** - No commands during/after work

## Parser Keywords

Decisions: decided, chose, going with, using, went with, settled on
Issues: problem, issue, bug, doesn't work, stuck on, blocked
Learnings: learned, discovered, realized, turns out, TIL, gotcha
Status: fixed, resolved, tried, blocked on

## Quick Syntax

```
MEMORY: decided X because Y
MEMORY: problem - X
MEMORY: learned - X
```

## Global vs Project Edges

- Global: Platform/language gotchas (via mind_add_global_edge)
- Project: In .mind/MEMORY.md Gotchas section

## Testing

```bash
uv run pytest tests/
```

## Running

```bash
# CLI
uv run mind <command>

# MCP Server (for Claude Code integration)
uv run mind mcp
```

## Memory

Append to `.mind/MEMORY.md` as you work on this project.
