memo-writing

Writing Effective Session Memos

Context

Date: !date +%Y-%m-%d Project: !basename $(git remote get-url origin 2>/dev/null | sed 's/\.git$//' | xargs basename 2>/dev/null) 2>/dev/null || basename $(pwd) Topics available for [[wikilinks]]: !ls $(memex path 2>/dev/null)/topics/*.md 2>/dev/null | xargs -I{} basename {} .md | sort | tr '\n' ' ' || echo "(no topics found)"

Core Principle

You were there. A subagent reading the transcript later wasn't. Your memo from full context will always be better than a reconstructed one. Write from experience, not summary.

Capture the journey, not just the destination. Future-Claude needs to understand:

• How things were discovered, not just what was found
• What was tried and failed, not just what worked
• What surprised you or was unexpectedly hard
• Where user and AI disagreed or changed direction

Memo Format

---
type: memo
title: [Specific, searchable title]
project: [project-name]   # detected from cwd git root; set explicitly if writing from outside the project
date: [ISO date]
topics:
  - topic-name-kebab-case
  - another-topic
manual: true              # distinguishes manually-written memos from auto-extracted ones
---

# [Title]

## For Future Context

[1-2 sentences: the single most important thing for someone continuing this work]

## Summary

[2-4 sentences: what was the actual work, not "we discussed X" but "we tried Y, discovered Z"]

## What Happened

### Key Decisions
- **[Decision]**: [Why this over alternatives. Note tradeoffs.]

### What Worked / What Didn't
- **Tried**: [Approach that failed or was abandoned] → **Why**: [Reason it failed]
- **Solution**: [What actually worked] → **Insight**: [Why it worked]

### Surprises & Difficulties
- [Unexpectedly hard things, multiple attempts, friction]
- [Surprisingly easy things, or things that solved bigger problems]

### Insights
- [Patterns, gotchas, or principles that transfer to other contexts]
- [Non-obvious discoveries — not "X is complex" but "X fails silently when Y"]

## Perspectives & Tensions

[When user and AI had different takes, or user expressed uncertainty/frustration/changed direction. Preserve quotes when they reveal thinking:]

- **User's priority**: [What the user emphasized or pushed for]
- **AI's approach**: [Where Claude offered alternatives or raised concerns]
- **Resolution**: [How it was decided, or if still open]

[Omit this section entirely if the session was straightforward]

## Open Threads

- [ ] [Concrete next step with enough context to act on]
- [ ] [Unresolved question with why it matters]
- [ ] [Blocked item with what's blocking it]

## Related

- [[existing-topic]]
- [[?suggested-new-concept]]

## Context Signals

- **Difficulty**: [Easy / Moderate / Complex / Grinding]
- **Session character**: [Exploration / Debugging / Implementation / Planning / Discussion]