flake-update-20260201

History System Documentation

Location: ~/.config/claude/history/ Format: Markdown (.md) only Purpose: Automated documentation of work performed by Claude Code

Overview

The History System captures significant work and learnings for future reference. All entries are markdown files, synced across machines via syncthing.

File Format

All history entries MUST use Markdown (.md) format.

  • Simple, universal format
  • Git-friendly diffs
  • Easy to read in any editor
  • Searchable with grep/rg

Directory Structure

~/.config/claude/history/
├── sessions/                 # Work session summaries
│   └── YYYY-MM/
│       └── YYYY-MM-DD-description.md
│
├── learnings/                # Problem-solving insights
│   └── YYYY-MM/
│       └── YYYY-MM-DD-description.md
│
├── research/                 # Deep investigations
│   └── YYYY-MM/
│       └── YYYY-MM-DD-topic.md
│
├── decisions/                # Architecture decisions
│   └── YYYY-MM/
│       └── YYYY-MM-DD-description.md
│
├── execution/                # Command/feature execution logs
│   └── YYYY-MM/
│       └── YYYY-MM-DD-description.md
│
└── tool-outputs/             # Tool execution logs (auto-generated)
    └── YYYY-MM/
        └── YYYY-MM-DD_tool-outputs.jsonl

Quick Decision Guide:

  • “What happened this session?” → sessions/
  • “What did we learn?” → learnings/
  • “What did we investigate?” → research/
  • “Why this approach?” → decisions/
  • “What was built/executed?” → execution/

Entry Templates

Session Entry

# Session: <Description>

**Date:** YYYY-MM-DD

## Summary
Brief description of what was accomplished.

## What Was Accomplished
- Task 1
- Task 2

## Files Changed
- `path/to/file.nix` - Description of change

## Outcome
Result of the session.

Learning Entry

# Learning: <Description>

**Date:** YYYY-MM-DD
**Context:** What problem was being solved

## The Problem
Clear description of the issue.

## Solution
How it was resolved.

## Key Insights
- Insight 1
- Insight 2

## Prevention
How to avoid this in the future.

Research Entry

# Research: <Topic>

**Date:** YYYY-MM-DD
**Question:** What was being investigated

## Findings
Key discoveries and insights.

## Conclusions
What was learned and decided.

## Sources
- Source 1
- Source 2

Decision Entry

# Decision: <Description>

**Date:** YYYY-MM-DD
**Context:** Why this decision needed to be made

## Options Considered
1. Option A: Pros/Cons
2. Option B: Pros/Cons

## Decision
Which option was chosen and why.

## Implications
What this means for the system.

Execution Entry

# Execution: <Description>

**Date:** YYYY-MM-DD
**Context:** What was being built or executed

## What Was Done
- Step 1
- Step 2

## Result
Outcome of the execution.

## Commands/Code
Relevant commands or code snippets.

Finding History

By Category

# Find all sessions
ls ~/.config/claude/history/sessions/*/*.md

# Find all learnings
ls ~/.config/claude/history/learnings/*/*.md

# Find recent research
ls -lt ~/.config/claude/history/research/

# Find all decisions
ls ~/.config/claude/history/decisions/*/*.md

# Find all executions
ls ~/.config/claude/history/execution/*/*.md

By Content

# Search all history
rg "keyword" ~/.config/claude/history/

Quick Reference

Create Session Entry

DATE=$(date +"%Y-%m")
mkdir -p ~/.config/claude/history/sessions/$DATE
vim ~/.config/claude/history/sessions/$DATE/$(date +"%Y-%m-%d")-description.md

Create Learning Entry

DATE=$(date +"%Y-%m")
mkdir -p ~/.config/claude/history/learnings/$DATE
vim ~/.config/claude/history/learnings/$DATE/$(date +"%Y-%m-%d")-description.md

Remember: When in doubt, save to history! It’s better to capture too much than to lose valuable insights.