Git tracks what changed. It doesn't track why

Last month I lost a three-week conversation with Claude. API timeout, session gone. All the context — the hypotheses we'd tested, the decisions we'd made, the dead ends we'd explored — vanished.

I spent two hours trying to reconstruct it from memory. I got maybe 60% back.

That was the last time.

The problem nobody names

If you use AI agents for anything longer than a single session, you've hit this wall:

• Chat disappears. You start over.
• You switch models. The new one knows nothing.
• A teammate needs context. There's no doc to hand them.
• Three months later, you can't remember why you chose approach A over B.

Git doesn't solve this. Git tracks what changed in code. It doesn't track why you made that decision, what you tried and ruled out, or which ideas are still unverified hunches vs. confirmed facts.

And now that AI agents write most of the commits, even the commit messages are losing human intent.

What I built

I created an Agent Skill called project-memory that turns a project folder into a durable memory system. The AI agent maintains it during the session. The human reads it when needed.

It separates project knowledge into canonical markdown files:

• CURRENT_STATE.md — what is true right now
• DECISION_LOG.md — what was decided and why
• RESEARCH_LOG.md — what was tested or observed
• HYPOTHESIS_LAB.md — what is still unverified
• ROADMAP.md — what is planned
• HUMAN_BRIEF.md — what a human should read first
• RECOVERY_NOTES.md — how to resume after interruption

No database. No embeddings. No vendor lock-in. Just markdown files in your repo.

Why not just use a README?

Because READMEs become dumps. Setup instructions, current state, decisions, hypotheses, and recovery notes all collapse into one overloaded file. Nobody maintains it, and nobody trusts it.

project-memory keeps each concern in its own file with clear ownership rules. The AI agent knows exactly where to write each type of information.

The two features that don't exist anywhere else

I looked through the Agent Skills ecosystem — awesome-agent-skills, LobeHub, skills.sh — and couldn't find anything that solves these two problems:

1. Promotion rules

A hypothesis in HYPOTHESIS_LAB.md cannot be promoted to CURRENT_STATE.md without:

• Evidence recorded in RESEARCH_LOG.md, or
• An explicit decision recorded in DECISION_LOG.md, or
• A clearly stated user decision

This sounds obvious, but it's the thing that breaks most project documentation. Someone writes "we should probably use OAuth2" in a note, and six weeks later everyone treats it as a decided fact. Nobody remembers it was just a hunch.

project-memory makes the status transitions explicit. Hypotheses stay hypotheses until proven.

2. Conflict resolution

When files disagree — and they will, over months of work — the skill defines a priority order:

1. CURRENT_STATE.md (latest entry)
2. DECISION_LOG.md (latest dated entry)
3. RESEARCH_LOG.md (latest dated entry)
4. RECOVERY_NOTES.md
5. HUMAN_BRIEF.md
6. ROADMAP.md
7. HYPOTHESIS_LAB.md

The agent reports the conflict and proposes a patch. No silent merging.

Model-independent by design

This is the part I'm most proud of. The memory lives in plain markdown — not in Claude's memory feature, not in ChatGPT's custom instructions, not in any tool's hidden state.

I've tested this across multiple models. Hand over the folder, and the new model picks up where the last one left off. The context recovery takes seconds.

This matters more than it sounds. Today you're using Claude. Tomorrow you might switch to Gemini or GPT for a specific task. Your project memory shouldn't be locked inside any single vendor.

Three profiles for different scales

Not every project needs 11 files. The skill comes with three profiles:

• Light — for small projects. Just CURRENT_STATE.md, RECOVERY_NOTES.md, and a logbook.
• Standard — for general long-running work. Adds decision log, hypothesis lab, and human brief.
• Research — for experiments and investigation. Adds RESEARCH_LOG.md with evidence and confidence fields.

python scripts/init_memory_workspace.py /path/to/project --profile standard

How the AI agent uses it

You don't maintain these files yourself. The skill instructs the agent to:

1. Classify new information by type (fact, decision, hypothesis, evidence)
2. Route it to the correct file
3. Update RECOVERY_NOTES.md at session end
4. Review HUMAN_BRIEF.md when the big picture changes
5. Never promote a hypothesis without evidence

Example prompt:

Resume this project. Read CONTEXT_MANIFEST.md and 
RECOVERY_NOTES.md first, then tell me what to do next.

The agent reads the files in the defined order and comes back with: current goal, last completed step, active blockers, and recommended next action.

The parallel threads problem

One thing that drove me crazy: when you have multiple workstreams running in parallel, time-series logs become unreadable. Thread A and Thread B interleave in the log, and a human scanning the file can't tell what's happening in either one.

HUMAN_BRIEF.md solves this with a tracked threads table:

Thread	Status	Next action / blocker	Source
Auth migration	active	Waiting on OAuth2 test results	RSC-042
Performance audit	paused	Blocked by staging deploy	BLK-003

Updated only when the human-facing picture changes. Not on every small commit.

Try it

git clone https://github.com/tasuku-9/project-memory-skill
python scripts/init_memory_workspace.py ./my-project --profile standard

Then tell your AI agent to read the SKILL.md and start maintaining the docs.

Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and any agent that supports the Agent Skills standard.

What's next

I submitted this as PR #1001 to Anthropic's official skills repository. Whether it gets merged or not, the skill is free and open source under MIT.

If you've ever lost a chat and wished you hadn't, give it a try. And if you find a better way to handle any of this, PRs are welcome.

---

GitHub: tasuku-9/project-memory-skill
License: MIT
Compatibility: Claude Code, Codex CLI, Gemini CLI, Cursor