Project Wiki: Durable Traceable Project Memory for AI Coding Agents

A project wiki is a durable, versioned set of instructions and context that AI coding agents load into every session, so they never start from zero. The open AGENTS.md format — used by over 60,000 open-source projects — and Claude Code’s CLAUDE.md files give agents a predictable place to find build steps, conventions, and architecture. Because these files live in git, they are traceable: every change is recorded, reviewable, and honest. This guide shows you how to build one.

Why AI Coding Agents Forget Your Project

Every time an AI coding agent starts a session, it begins with a blank slate. Unless you give it durable context, it has to rediscover your build system, your testing conventions, and your architectural decisions from scratch — or worse, guess. This is the core problem that project memory solves.

The cost of forgetting is real. An agent that does not know your project conventions will:

• Run the wrong build command and fail
• Write tests that do not match your testing framework
• Refactor code in a style that conflicts with your team’s standards
• Repeat mistakes that were already documented and solved

The open-source community has converged on a simple answer: a dedicated, predictable file that agents read at the start of every session. The AGENTS.md project describes this as “a README for agents” — a single, well-known location where context and instructions live. README.md is written for humans; AGENTS.md is written for the agents that work on your code.

What Is a Project Wiki for Agents? (AGENTS.md as the Open Standard)

An agent project wiki is not a sprawling documentation site. It is a focused, machine-readable set of instructions that an agent loads automatically. The most important standard today is AGENTS.md, an open format adopted by more than 60,000 open-source projects.

The power of AGENTS.md is that it is tool-agnostic. One file works across a growing ecosystem of agents, including Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, and Devin. This means you write your project memory once, and every agent that touches your repository reads the same source of truth.

A good AGENTS.md typically contains:

• Build and test commands
• Project structure and architecture overview
• Coding conventions and style rules
• Common pitfalls and known gotchas
• Commands that must never be run

Because it is a plain markdown file in your repository, it is versioned in git, reviewed in pull requests, and traceable. You can see exactly when a convention was added, who added it, and why.

CLAUDE.md vs Auto Memory: Two Complementary Systems

Claude Code offers two complementary memory systems, and understanding the difference is key to building durable project memory.

The first is CLAUDE.md files, which you write. These are explicit, curated instructions that you control. They are loaded into every session and treated as context. Claude Code reads the first 200 lines or 25KB of these files, so keeping them concise matters.

The second is auto memory, which Claude writes automatically. It saves four note types — user, feedback, project, and reference — stored per-repository at ~/.claude/projects/<project>/memory/. This captures lessons learned during real work, such as “the user prefers X” or “this project uses Y.”

The two systems are complementary. Use CLAUDE.md for the durable, stable facts about your project that you want to control and version. Use auto memory for the organic lessons that emerge during work. Together they give you both explicit control and automatic capture.

Scoping Your Project Memory: Org, User, and Project Levels

Not all project memory belongs in the same place. Claude Code scopes CLAUDE.md files across three levels, and understanding when to use each keeps your memory clean and relevant.

• Managed policy (org level): Instructions that apply to every project in your organization. This is where you put company-wide standards, security rules, and compliance requirements.
• User level (~/.claude/CLAUDE.md): Personal preferences that apply across all your projects. This is where you put your own workflow preferences and tooling habits.
• Project level (./CLAUDE.md or ./.claude/CLAUDE.md): Instructions specific to one repository. This is where the bulk of your project wiki lives.

The same scoping logic applies to AGENTS.md. A global AGENTS.md can hold your personal or organizational defaults, while a project-level AGENTS.md holds repository-specific truth.

The rule of thumb is simple: put memory as close to the code it describes as possible. Project-specific conventions belong in the project file. Cross-project standards belong at the org or user level. This prevents your project wiki from becoming bloated with irrelevant instructions.

How to Keep Project Memory Durable and Traceable

Durability and traceability are the two qualities that separate a real project wiki from a throwaway note. Here is how to achieve both.

Durability means the memory survives context resets. Because AGENTS.md and CLAUDE.md live in your repository, they survive every session reset, every new agent, and every team member change. The memory is not in a model’s ephemeral context window — it is in your source control.

Traceability means you can see how the memory evolved. Because these files are versioned in git, every change is a commit. You can review a pull request that adds a new convention, see who approved it, and understand the reasoning. This is the “honest” part of project memory — the instructions reflect what the team actually decided, not what an agent hallucinated.

To keep memory single-sourced and honest, some teams use small tooling that keeps AGENTS.md and CLAUDE.md in sync. The agent-standard-oss project, for example, provides dependency-free bash tools that keep these files consistent and prevent them from drifting out of date. The goal is to avoid the problem of coding agents following stale instructions.

A practical traceability workflow:

1. Treat AGENTS.md and CLAUDE.md as code, not documentation
2. Require pull requests for any change to project memory
3. Review memory changes with the same rigor as code changes
4. Add a “last verified” note or test that confirms the instructions still work
5. Archive obsolete instructions rather than silently deleting them

When to Use a Wiki vs Skills vs Path-Scoped Rules

Project memory is not the only tool for guiding agents. Knowing when to use a wiki versus skills versus path-scoped rules keeps your setup clean.

• Project wiki (AGENTS.md / CLAUDE.md): Use for stable, project-wide facts and conventions that every agent should know. This is your default home for durable memory.
• Skills: Use for reusable, procedural knowledge that applies across projects — for example, “how to run our deployment” or “how to write a release note.” Skills are portable and can be shared.
• Path-scoped rules: Use for instructions that apply only to specific directories or files. For example, a rule that says “never modify files in vendor/” belongs in a path-scoped rule, not in the global wiki.

The decision framework is: if it applies to the whole project, put it in the wiki. If it is a reusable procedure, make it a skill. If it applies to a specific path, scope it there. This keeps each mechanism focused and prevents overlap.

A Practical Workflow for Building Your Project Wiki

Building a project wiki does not have to be a big-bang effort. Start small and iterate.

Step 1: Start with the essentials. Create an AGENTS.md or CLAUDE.md with just three things: how to build, how to test, and how to run the project. This alone eliminates the most common agent failures.

Step 2: Add conventions as you encounter them. When an agent makes a mistake, add the correction to the wiki. When you discover a gotcha, document it. This turns the wiki into a living record of what you have learned.

Step 3: Review and prune regularly. Stale instructions are worse than no instructions, because agents trust them. Schedule a periodic review to verify that every instruction still reflects reality.

Step 4: Version and trace everything. Keep the wiki in git, require reviews for changes, and archive obsolete content. This is what makes the memory traceable.

Step 5: Let auto memory complement the wiki. Enable auto memory so the agent captures lessons you might not think to document, then periodically promote the valuable ones into your curated wiki.

Common Pitfalls and How to Avoid Stale Instructions

The biggest risk with project memory is staleness. An agent that follows an outdated instruction can cause more harm than an agent with no instructions at all. Here are the common pitfalls and how to avoid them.

Pitfall 1: Instructions that drift from reality. The build command changes, but the wiki still says the old one. Avoid this by treating the wiki as code and updating it in the same pull request that changes the build.

Pitfall 2: Bloated, unfocused memory. A wiki that tries to document everything becomes noise. Keep it focused on what agents actually need, and move reusable procedures to skills.

Pitfall 3: Duplicated, conflicting sources. If AGENTS.md and CLAUDE.md say different things, agents get confused. Use tooling to keep them single-sourced and in sync.

Pitfall 4: No review process. If anyone can edit project memory without review, it degrades quickly. Require pull requests and reviews for memory changes.

Pitfall 5: Ignoring auto memory. If you rely only on hand-written files, you miss the lessons the agent learns during real work. Review auto memory periodically and promote valuable insights.

Conclusion: Make Memory a First-Class Project Artifact

AI coding agents are only as good as the context you give them. A project wiki built on AGENTS.md and CLAUDE.md turns your repository into a durable, traceable source of truth that survives context resets and multi-agent collaboration. Because these files live in git, your project memory is versioned, reviewable, and honest — never stale, never lost.

The open standard is already proven: more than 60,000 open-source projects use AGENTS.md, and it works across Codex, Claude Code, Cursor, and a dozen other agents. Start with the essentials, add conventions as you learn them, and keep everything versioned and traceable. Make project memory a first-class artifact of your repository, and your agents will stop forgetting — and start shipping.

FAQ

What is a project wiki for AI coding agents? A project wiki is a durable, versioned set of instructions and context — typically an AGENTS.md or CLAUDE.md file — that AI coding agents load at the start of every session. It gives agents a predictable place to find build steps, conventions, and architecture so they do not start from zero each time.

What is the difference between AGENTS.md and CLAUDE.md? AGENTS.md is an open, tool-agnostic standard used by over 60,000 projects and works across many agents including Codex, Cursor, and Devin. CLAUDE.md is Claude Code’s project memory file. Both serve the same purpose — durable project context — but AGENTS.md is the cross-tool open standard.

How do I make project memory traceable? Keep your project wiki in git and treat it as code. Require pull requests for any change, review memory edits with the same rigor as code changes, and archive obsolete instructions. Because every change is a commit, you can always see when and why a convention was added.

What is Claude Code auto memory? Auto memory is a system where Claude Code automatically saves lessons it learns during work, stored per-repository in ~/.claude/projects/<project>/memory/. It captures four note types — user, feedback, project, and reference — and complements the hand-written CLAUDE.md files you control.

How do I prevent stale instructions in my project wiki? Treat the wiki as code and update it in the same pull request that changes the underlying behavior. Schedule periodic reviews to verify every instruction still reflects reality, keep AGENTS.md and CLAUDE.md single-sourced and in sync, and archive obsolete content instead of leaving it to mislead agents.