session-log

name	session-log
description	Human-readable markdown session logs for characters and adventures.
license	MIT
tier	1
allowed-tools	["read_file","write_file"]
related	["play-learn-lift","plain-text","character","adventure","summarize","honest-forget","markdown"]
tags	["moollm","logging","narrative","persistence","history"]

Session Log

Human-readable markdown logs that tell stories.

Session logs are living documents that capture the narrative of play. Unlike technical event logs, sessions are meant to be READ — by users, by future LLMs warming context, by anyone who wants to understand what happened.

[!IMPORTANT] Session logs are NOT append-only! They are living documents that grow and improve over time. You can and should retroactively improve them as new information comes in.

---

📍 Where Sessions Live

The default session file is SESSION.md in the character directory:

characters/
├── real-people/don-hopkins/
│   ├── CHARACTER.yml
│   └── SESSION.md          ← Default session log
├── fictional/donna-toadstool/
│   ├── CHARACTER.yml
│   └── SESSION.md          ← Default session log
└── animals/monkey-palm/
    ├── CHARACTER.yml
    └── SESSION.md          ← Default session log

Naming Sessions

You can create multiple session files with descriptive suffixes:

Session File	Purpose
SESSION.md	Default — the main session log
SESSION-day1-exploration.md	Specific day or theme
SESSION-fluxx-marathon.md	Named adventure arc
SESSION-debug-investigation.md	Debugging session

Command: START SESSION [name] — Creates a new session file with optional suffix.

---

📝 Writing Good Sessions

The Golden Rule

Sessions are meant to be read by humans. Write them like stories, not logs.

Structure with Outlines

Use <details open> tags to create collapsible sections that:

• Show narrative meant to be read (opened)
• Hide technical data and debugging (closed)
• Group related content into logical sections
• Allow readers to drill down on demand

<details open>
<summary><h2>🌟 Chapter Title — Descriptive Subtitle</h2></summary>

The narrative content goes here. This is what readers see first.

<details open>
<summary>📂 <strong>Technical details: What the YAML changes looked like</strong></summary>

```yaml
# The YAML data island
state_change:
  file: ./CHARACTER.yml
  changes: [location, inventory]

```

Outline Patterns

Pattern	When to Use	State
<details open>	Narrative chapters — always show	Open
<details open>	Technical details — hide by default	Closed
Nested <details open>	Data within narrative	Mixed

The Summary Line

The <summary> is part of the narrative! Write it as a headline:

<!-- BAD: Generic summaries -->
<summary>Turn 5</summary>
<summary>File operations</summary>

<!-- GOOD: Descriptive headlines -->
<summary><h2>🌟 Turn 5: The Wish is Spoken — Palm's Incarnation</h2></summary>
<summary>📂 <strong>File creation: CHARACTER.yml with 32 Mind Mirror dimensions</strong></summary>

Use Emojis in Section Headers

Add emojis after the folder icon for narrative sections:

Emoji	Meaning
📂	Technical/collapsed section
🌟	Major milestone
🎭	Character transformation
🗺️	Exploration/travel
💬	Dialogue/conversation
🎰	Games/randomness
🐕 🐱 🐵	Animal character sections
⚡	Speed-of-light simulation

---

📊 Session Index

Keep an index at the top of every session! Update it retroactively as you append.

<details open>
<summary><h2>⭐ Session Highlights & Index</h2></summary>

### 📚 Session Index (Internal Links)

**Day 1 — The Wish**
- [🌿 LOOK AROUND](#-look-around) — First impressions
- [Turn 1: Talk to Marieke](#turn-1-talk-to-marieke) — Lucky strains
- [Turn 7: THE WISH IS SPOKEN](#turn-7-the-wish-is-spoken-) — 🌟 Palm's incarnation

**Day 2 — The Fluxx Marathon**
- [🎰 33 Turns of Gezelligheid](#33-turns-of-gezelligheid) — Speed of Light demo

### 🏠 Key Locations (External Links)

| Location | Description |
|----------|-------------|
| [Palm's Nook](../../examples/adventure-4/pub/stage/palm-nook/) | The monkey's home |
| [The Pub](../../examples/adventure-4/pub/) | Main location |

</details>

Index Rules

1. Internal links use anchor syntax: [Title](#anchor-name)
2. External links use relative paths: [File](../../examples/adventure-4/pub/pie-table.yml)
3. Update retroactively — every append is a chance to improve the index
4. Group by day/arc — natural narrative divisions

---

🔗 Linking Generously

Links draw people into the repo! Every file, character, room, and skill mentioned should be a link.

Link Everything

<!-- BAD: No links -->
Palm wrote an essay about being a monkey.

<!-- GOOD: Link everything -->
[Palm](../../examples/adventure-4/characters/animals/monkey-palm/) wrote an essay 
([palm-on-being-palm.md](../../examples/adventure-4/pub/stage/palm-nook/study/palm-on-being-palm.md)) 
about being a monkey.

Use Tables for Related Files

### Files Created

| File | Description |
|------|-------------|
| [CHARACTER.yml](../../examples/adventure-4/characters/animals/monkey-palm/CHARACTER.yml) | Soul file |
| `physical:` in [CHARACTER.yml](../../examples/adventure-4/characters/animals/monkey-palm/CHARACTER.yml) | Physical description |
| [→ Full directory](../../examples/adventure-4/characters/animals/monkey-palm/) | Complete character |

### Related Skills

| Skill | Purpose |
|-------|---------|
| [incarnation]($SKILLS/incarnation/) | Character creation protocol |
| [speed-of-light]($SKILLS/speed-of-light/) | Multi-agent simulation |

Path variables in YAML vs Markdown: Use $SKILLS/ in YAML files (runtime resolution). Use relative paths in Markdown for GitHub rendering.

---

📈 Tables Tell Stories

Tables are excellent for:

• Summarizing actions — turns, outcomes, stats
• Showing state — inventories, relationships, locations
• Listing files — what was created, edited, linked
• Character rosters — who's present, their status

## Current Status

| Character | Location | Status |
|-----------|----------|--------|
| [Don](../../examples/adventure-4/characters/real-people/don-hopkins/) | pub/ | Active |
| [Palm](../../examples/adventure-4/characters/animals/monkey-palm/) | stage/palm-nook/ | Writing |
| [Biscuit](../../examples/adventure-4/characters/animals/dog-biscuit/) | following Don | WIGGLING |

## Session Statistics

| Metric | Value |
|--------|-------|
| Turns | 33 |
| NPCs encountered | 15 |
| Relationships formed | 12 |
| Gold spent | 31 |

Fold Large Tables

<details open>
<summary>📂 <strong>Full inventory (47 items)</strong></summary>

| Item | Location | Value |
|------|----------|-------|
| ... | ... | ... |

</details>

---

🔄 Retroactive Improvement

Sessions are living documents. Every time you append:

1. Update the index — add new sections, fix anchors
2. Add missing links — file paths, character names
3. Improve summaries — make them more descriptive
4. Fill in context — as you learn more, annotate earlier sections
5. Fix broken links — paths change as files move

Ninja Edits

Small retroactive improvements are encouraged:

• Correcting typos
• Adding links to newly-created files
• Improving section summaries
• Updating the index

---

📋 YAML Data Islands

Embed structured data in fenced code blocks for machine readability:

<details open>
<summary>📂 <strong>State change: Moving player from start/ to coatroom/</strong></summary>

```yaml
state_change:
  file: ./CHARACTER.yml
  changes:
    player.location: "coatroom/"  # Was: "start/"
    
  file: ../../../ADVENTURE.yml
  changes:
    player.location: "coatroom/"  # Mirror update

```

Data Island Best Practices

Practice	Reason
Use # comments	Explain the WHY, not just WHAT
Abbreviate long data	Show structure, not everything
Include file paths	Link to actual files
Explain relationships	"Mirror update", "Canonical source"

---

🆚 Session Logs vs Event Logs

Session Logs (SESSION.md)	Event Logs (events.yml)
Human readable	Machine readable
Narrative style	Structured data
Living document (editable)	Append-only
Collapsible outlines	YAML events
For reading	For debugging/audit
In character directories	In .agent/ or adventure root

Create event logs for:

• Technical debugging
• Append-only audit trails
• Machine-parseable history

Create session logs for:

• User-facing narrative
• GitHub browsing
• Context warming
• Storytelling

---

🌟 Examples: Gold Standard Sessions

These sessions demonstrate best practices:

Don Hopkins' Marathon Session

examples/adventure-4/characters/real-people/don-hopkins/sessions/marathon-session.md

7000+ lines spanning 5 days of adventure. Demonstrates:

• Extensive use of collapsible sections
• Comprehensive index at top
• Generous linking to files and skills
• Tables for menus, stats, and rosters
• Speed-of-light simulation transcripts
• Technical details hidden in collapsed sections

Donna Toadstool's Session

examples/adventure-4/characters/fictional/donna-toadstool/SESSION.md

Complete character creation narrative. Demonstrates:

• Table of contents with parts
• Character transformation documentation
• File operation explanations
• Appendix with technical reference
• Clear separation of narrative and data

---

🎯 Quick Reference

Starting a New Section

---

<details open>
<summary><h2>🌟 Turn N: Title — Descriptive Subtitle</h2></summary>

Narrative description of what happened.

<details open>
<summary>📂 <strong>Technical: What changed under the hood</strong></summary>

```yaml
changes:
  - file: path/to/file.yml
    field: value

```

Checklist for Every Append

• Updated index at top with new section
• Added links to all mentioned files
• Linked character names to their directories
• Used collapsible sections appropriately
• Wrote descriptive summary lines
• Included relevant tables
• Fixed any broken links noticed

---

The Intertwingularity

Session-log is the PLAY stage of play-learn-lift — capture everything.

graph LR
    SL[📜 session-log] -->|PLAY stage of| PLL[🎮 play-learn-lift]
    SL -->|tracks| R[🚪 room]
    SL -->|tracks| TC[🎴 card]
    SL -->|monitored by| SR[🔧 self-repair]
    
    AP[⚔️ adventure] -->|LOG.md is| SL
    DB[🔧 debugging] -->|logs to| SL
    CH[👤 character] -->|SESSION.md is| SL

---

Dovetails With

Sister Skills

Skill	Relationship
character/	Session files live in character directories
adventure/	Adventure LOG.md follows session-log patterns
play-learn-lift/	Session-log is the PLAY capture stage
summarize/	Compress session-log when too long
self-repair/	Monitors session-log integrity
debugging/	Debug sessions log here

Protocol Symbols

Symbol	Link
SESSION-LOG	PROTOCOLS.yml
NARRATIVE-FIRST	Write for humans
LINK-GENEROUSLY	Every file is a link

Kernel

• kernel/event-logging-protocol.md — Technical event format
• schemas/event-schema.yml — YAML block schema

Navigation

Direction	Destination
⬆️ Up	skills/
⬆️⬆️ Root	Project Root
🎮 Sister	play-learn-lift/
👤 Sister	character/