main

History System Documentation

Location: ~/.local/share/ai/ (unified across all AI coding tools) Format: Markdown (.md) only Purpose: Automated documentation of work performed by AI coding tools Synced: Via syncthing (actual data in ~/.local/share/ai-sync/)

Overview

The History System captures significant work and learnings for future reference. All entries are markdown files, stored in a unified location shared by all AI coding tools (Claude Code, pi, opencode, etc.) and 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

Filename Convention

STRICT FORMAT: YYYY-MM-DD-description-with-dashes.md

Rules:

  • Date prefix is mandatory
  • Use only lowercase letters, digits, and dashes
  • NO underscores (except _session-log.txt)
  • NO timestamps beyond the date (no _155616_SESSION_)
  • NO SESSION prefix
  • Keep description to 3-6 words, max 60 characters for the slug
  • Slug is generated: title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").substring(0, 60)

Good: 2026-02-10-tekton-pr-review.md Bad: 2026-02-10_155616_SESSION_tekton-pr-review.md

Directory Structure

~/.local/share/ai/
├── sessions/                 # Work session summaries
│   └── YYYY-MM/
│       ├── YYYY-MM-DD-description.md
│       └── YYYY-MM-DD_session-log.txt
│
├── learnings/                # Problem-solving insights
│   └── YYYY-MM/
│       └── YYYY-MM-DD-description.md
│
├── research/                 # Deep investigations
│   └── YYYY-MM/
│       └── YYYY-MM-DD-topic.md
│
├── plans/                    # Project plans (NOT date-organized)
│   └── plan-name.md
│
└── .pending/                 # Auto-saved transcripts (temporary)
    └── *.json

Note: Tool-specific data (like tool-outputs JSONL) stays under tool config:

  • Claude: ~/.config/claude/history/tool-outputs/

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

# <Description>

**Date:** YYYY-MM-DD
**Tool:** claude-code (or pi)
**Project:** org/repo or ~/path (REQUIRED — infer from cwd, git remote, or context)
**Directory:** /path/to/working/directory

## Summary
Brief description of what was accomplished.

## What Was Accomplished

### 1. First thing done
Description and details.

### 2. Second thing done
Description and details.

## Changes Made
- **Modified** `path/to/file.ext` — description of change
- **Added** `path/to/new-file.ext` — what it does
- **Removed** `path/to/old-file.ext` — why

## Learnings
- Key insight 1
- Key insight 2

IMPORTANT metadata rules:

  • **Project:** is REQUIRED — use org/repo format (e.g., tektoncd/pipeline) or path (e.g., ~/src/home)
  • **Directory:** is REQUIRED — the actual working directory (process.cwd())
  • For git worktrees, Project must be the real project name, not the worktree path
  • **Repository:** can be used as alias for Project
  • These fields enable filtering in review-tool (-d / -D flags)

Learning Entry

# <Description>

**Project:** org/repo or ~/path (when applicable)
**Date:** YYYY-MM-DD

## The Problem
Clear description of the issue.

## The Fix
How it was resolved (with code snippets, commands, config changes).

## Key Details
Tables, gotchas, and technical specifics.

## Why This Matters
Impact and how to avoid in the future.

Research Entry

# Research: <Topic>

**Date:** YYYY-MM-DD
**Tool:** claude
**Project:** org/repo or ~/path (when applicable)
**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
**Tool:** claude
**Project:** org/repo or ~/path (when applicable)
**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
**Tool:** claude
**Project:** org/repo or ~/path (when applicable)
**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 ~/.local/share/ai/sessions/*/*.md

# Find all learnings
ls ~/.local/share/ai/learnings/*/*.md

# Find recent research
ls -lt ~/.local/share/ai/research/

# Find all plans
ls ~/.local/share/ai/plans/*.md

By Content

# Search all history
rg "keyword" ~/.local/share/ai/

Quick Reference

Create Session Entry

DATE=$(date +"%Y-%m")
mkdir -p ~/.local/share/ai/sessions/$DATE
vim ~/.local/share/ai/sessions/$DATE/$(date +"%Y-%m-%d")-description.md

Create Learning Entry

DATE=$(date +"%Y-%m")
mkdir -p ~/.local/share/ai/learnings/$DATE
vim ~/.local/share/ai/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.