whylog

Git-native decision memory for AI coding agents.

whylog gives AI coding sessions a durable memory layer inside Git.

In the age of AI coding agents, code is increasingly produced across short-lived sessions, tool switches, and human/agent handoffs. A diff preserves what changed; it rarely preserves why. whylog turns commits into durable, queryable decision records so future humans and agents can recover the reasoning behind a change from Git history itself.

whylog is a Lore-compatible, CLI-first toolkit for keeping decision context inside Git.

It stores constraints, rejected alternatives, directives, and test context in structured commit trailers—without requiring a server, database, or hidden index.

• Git-native
• No server
• No database
• No hidden index
• Human + agent readable
• Local + CI validation

This repository currently ships a CLI tool, not a stable import/library API.

Why whylog exists

Most repositories preserve what changed, but lose why it changed.

Teams forget:

• which constraints shaped the current implementation
• which alternatives were considered and rejected
• what future maintainers should revisit
• how confident the original decision was
• what was tested and what was not

That problem gets worse in AI-assisted development.

Agents often work across:

• short-lived sessions
• changing tools and sandboxes
• incomplete context windows
• human ↔ agent handoffs
• multiple iterations of “try / fail / retry”

Without durable project memory, the next agent often sees only:

• the current code
• the current diff
• whatever chat context still fits
• partial PR discussion, if any

whylog solves that by storing decision context directly in Git commits, so reasoning survives beyond chat sessions, tool boundaries, and individual contributors.

What makes whylog different

whylog is not just another commit-message formatter.

Its core value is the combination of:

1. Git-native storage
   Decision context lives in commit history itself.

2. Structured rationale
   Commits can store constraints, rejected alternatives, directives, and test context in machine-readable trailers.

3. Queryable history
   Humans and agents can recover past reasoning with CLI commands instead of relying on memory or PR archaeology.

4. Agent-friendly workflows
   Agents can read context before making changes and write structured rationale back afterward.

5. No extra infrastructure
   No server, no vector database, no sidecar memory system.

That makes whylog useful in places where most teams currently lose context: refactors, debugging, revisit work, and agent handoffs.

How AI agents actually use whylog

Without whylog, an agent usually sees only the current codebase, the current task, and whatever short-lived chat context still survives.

With whylog, an agent can recover prior decision context directly from Git history before making a change.

A typical workflow looks like this:

1. Load local context before editing

whylog context <path>

This gives the agent the active constraints, directives, and recent reasoning around a file or subsystem.

2. Avoid repeating failed ideas

whylog rejected <path>

This shows approaches that were already tried and rejected, so the agent does not waste time rediscovering dead ends.

3. Understand why the current implementation exists

whylog why <path>

This helps the agent understand why the current code exists before proposing a refactor or fix.

4. Follow related decisions across time

whylog trace <Lore-id>

This lets the agent inspect related, dependent, or superseded decisions instead of relying on scattered PR comments or chat history.

5. Write back structured reasoning

whylog commit -i

or

whylog commit --from-json input.json

This lets the next human or agent inherit constraints, rejected alternatives, directives, and test context from Git itself.

Why that matters in practice

This makes AI-assisted development better in concrete ways:

• fewer repeated failed attempts
• better human ↔ agent handoffs
• less dependence on ephemeral chat context
• faster recovery of “why” during debugging and refactoring
• more durable project memory for long-lived codebases

Core principles

1. Git is the source of truth

whylog does not require a server, database, SaaS product, or hidden sidecar index.

Git history remains the source of truth.

2. Commits can carry decision context

whylog uses structured trailers to store decision context directly in commit messages.

Typical examples include:

• Lore-id
• Constraint
• Rejected
• Directive
• Tested
• Not-tested
• Supersedes
• Depends-on
• Related

This makes a commit message more than a summary: it becomes a small decision record.

3. Stable decision identity matters

Git hashes change across rebase, squash, and cherry-pick workflows. Decision identity should not disappear when history is rewritten.

whylog keeps a stable decision identifier (Lore-id) so the rationale and relationship graph remain trackable over time.

4. Adoption must stay lightweight

Teams usually do not fail to preserve rationale because the idea is bad. They fail because setup is annoying.

whylog is designed as a practical CLI with init, validation, hooks, CI scaffolding, and agent-facing instructions so it can be adopted incrementally.

5. Honest scope beats aspirational scope

whylog should only document and advertise behavior that the current implementation really supports.

If a feature is incomplete, the product surface should shrink instead of pretending the feature exists.

What you get

• Structured commits that preserve reasoning, not just diff summaries
• Git-native retrieval of constraints, rejected approaches, directives, and test context
• Better AI agent handoffs through durable, queryable project memory
• Consistent validation across local workflows and CI
• Human + agent usability, with interactive flows for people and machine-readable I/O for tooling
• Incremental adoption, so teams can introduce structured commit context without rewriting their entire workflow

Installation

From npm

npm install --save-dev whylog
npx whylog init

From GitHub

npm install --save-dev github:Juhwa-Lee1023/whylog#main
npx whylog init

Or run directly without pinning it as a dependency:

npx --yes --package github:Juhwa-Lee1023/whylog#main whylog init --no-package

From source

npm ci
npm run build
npm run dev -- help

Quick start

1. Initialize the repository

npx whylog init

Profiles:

• minimal: config only
• team: config + package + hooks + CI
• ai: team + agent instruction files

Examples:

npx whylog init --profile minimal
npx whylog init --profile team
npx whylog init --profile ai

2. Create a structured commit

For humans:

npx whylog commit -i

For agents or automation:

npx whylog commit --from-json input.json

3. Validate a commit

npx whylog validate --rev HEAD --strict

For incremental adoption in mixed-history repositories:

npx whylog validate --range main..HEAD --skip-unstructured --strict

4. Recover context from history

npx whylog context src/cache
npx whylog constraints src/cache
npx whylog rejected src/cache
npx whylog directives src/cache
npx whylog why src/cache
npx whylog trace 1a2b3c4d

Example commit message

feat(cache): avoid stale tenant config reuse

The previous cache key could survive a tenant switch and return stale data.

Lore-id: 1a2b3c4d5e
Constraint: Must not add a network roundtrip on the hot path
Rejected: Disable cache globally; too expensive under current traffic
Directive: Revisit once tenant-scoped cache keys are fully rolled out
Tested: Unit tests for tenant switch path
Not-tested: Production-like multi-tenant soak run
Confidence: medium
Scope-risk: medium
Reversibility: clean

The key idea is simple:

• keep the subject line familiar
• keep the decision context structured

This lets teams increase the value of commits without abandoning existing Git habits.

Main commands

Initialize

whylog init [--profile minimal|team|ai] [--ai all|agents|claude,copilot,cursor,windsurf] [--no-hooks] [--no-package] [--yes]

Create structured commits

whylog commit -i
whylog commit --from-json input.json
whylog commit --from-json -

Query decision context

whylog context <path>
whylog constraints <path>
whylog rejected <path>
whylog directives <path>
whylog why <path>
whylog search <query>
whylog stale
whylog trace <Lore-id>

Prepare a squash summary

whylog squash <range>
whylog squash --range <range> --title "feat(core): fold rollout context"

Validate and inspect

whylog validate --rev HEAD --strict
whylog validate --range main..HEAD --skip-unstructured --strict
whylog doctor

Many query and validation commands also support --json for automation and agent workflows.

Why this matters in the age of AI coding agents

Modern coding agents can write and modify code quickly, but they often operate across short-lived sessions, multiple tools, and incomplete context windows.

A diff preserves what changed.
It rarely preserves why.

whylog gives teams a Git-native way to preserve that missing reasoning: constraints, rejected alternatives, directives, and test context become durable commit history instead of ephemeral chat context.

That matters especially during:

• agent-to-human handoff
• human-to-agent handoff
• cross-session resume
• long-lived maintenance of AI-assisted codebases

In that sense, whylog acts as a durable memory layer inside Git.

Git compatibility

whylog is designed to work with Git workflows, not replace them.

Conventional subject lines are still fine

You can keep a familiar subject line style, such as:

feat(cache): avoid stale tenant config reuse

whylog strengthens the structured context around the commit rather than forcing an entirely new subject style.

Common foreign footers should coexist

whylog should coexist with common Git footer patterns such as:

• Signed-off-by
• Co-authored-by
• Reviewed-by
• Acked-by
• BREAKING CHANGE

Special commit types should not be treated like normal authored commits

Merge commits, revert commits, and autosquash flows should not be forced through the same structured-commit rules as ordinary authored commits.

Incremental adoption is expected

Teams with mixed history should be able to start with range-based validation and grow stricter over time.

Humans and agents

whylog is designed for both.

Humans

Humans can use an interactive flow:

whylog commit -i

Agents and automation

Agents can use JSON-based entry points and machine-readable output:

whylog commit --from-json input.json
whylog context <path> --json
whylog why <path> --json
whylog validate --rev HEAD --json

The initialization flow can also generate repo-level instructions for agent-facing tools such as Claude Code, GitHub Copilot, Cursor, and Windsurf.

Security considerations

Structured commit messages are powerful, but Git history is durable.

Do not store:

• API keys or tokens
• private keys
• internal-only hostnames or URLs
• customer secrets
• sensitive incident-response details

whylog validation should help catch obvious mistakes, but validation is only a guardrail, not a guarantee.

Teams should still treat commit history as durable shared project memory.

Exit codes

The CLI should use stable exit codes:

• 0 — success
• 1 — validation failure
• 2 — invalid user input / usage error
• 3 — internal unexpected failure

Verifying the package before release

npm ci
npm run build
npm test
npm run pr:check
npm pack --dry-run

If you want to inspect the tarball directly:

npm pack

Inspiration

whylog is an independent, Lore-compatible CLI for keeping decision context inside Git.

This project was inspired by the paper Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents and by the broader Lore Protocol direction.

In particular, whylog draws on ideas such as:

• using Git-native commit trailers as durable decision records
• preserving stable decision identity separately from Git hashes
• making decision context readable by both humans and AI coding agents
• keeping the workflow lightweight, queryable, and infrastructure-free

whylog is not an official implementation of Lore Protocol.
It is an independent project that adapts and extends some of the same ideas for a CLI-first workflow.

References

• Ivan Stetsenko, Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents, arXiv:2603.15566 — https://arxiv.org/abs/2603.15566
• Lore Protocol — https://lore-protocol.com/

Status

whylog is a CLI-first Lore-compatible toolkit.

Its current focus is:

• structured commit context
• Git-native decision retrieval
• local and CI validation
• practical human + agent workflows
• incremental adoption in real repositories

This repository currently does not promise a stable import/library API.

Contributing

See CONTRIBUTING.md for local setup, validation steps, and PR expectations.

License

MIT