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. 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. 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. 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. I looked through the Agent Skills ecosystem — awesome-agent-skills, LobeHub, skills.sh — and couldn't find anything that solves these two problems: 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. When files disagree — and they will, over months of work — the skill defines a priority order: CURRENT_STATE.md (latest entry) DECISION_LOG.md (latest dated entry) RESEARCH_LOG.md (latest dated entry) RECOVERY_NOTES.md HUMAN_BRIEF.md ROADMAP.md HYPOTHESIS_LAB.md The agent reports the conflict and proposes a patch. No silent merging. 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. 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 You don't maintain these files yourself. The skill instructs the agent to: Classify new information by type (fact, decision, hypothesis, evidence) Route it to the correct file Update RECOVERY_NOTES.md at session end Review HUMAN_BRIEF.md when the big picture changes 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. 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. 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. 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