Vibe coding is powerful until the project starts producing more memory than anyone can keep aligned. Every AI session creates new notes, implementation summaries, TODOs, design decisions, prompt fragments, generated docs, and half-true explanations of the codebase. Some of that material is useful. Some of it is stale the moment the next pull request lands.

The result is a strange tax on AI-assisted development. Before making even a small change, an agent often has to reread large parts of the codebase just to answer basic questions: Which docs are still true? Which contract matters? Which previous decision should not be broken? What did the last agent learn that is still worth trusting?

Project-LLM-Wiki is our open source answer to that problem. It adapts the spirit of Andrej Karpathy's llm-wiki.md GitHub Gist to software repositories: keep a small, structured, LLM-readable knowledge layer next to the real source material, then make agents verify important claims against current code before acting on them.

Open source repository: https://github.com/sologovision/Project-LLM-wiki

In other words, Project-LLM-Wiki is a practical memory system for Vibe coding and a foundation for Loop Engineering. Loop Engineering is the practice of making every coding loop improve the next one by preserving verified lessons, contracts, and failure modes inside the repository itself.

We built this method while developing Flato.ai, where AI agents help us maintain complex design-runtime, plugin, and content systems. In our workflow, Project-LLM-Wiki has helped improve development efficiency by at least 30%. The lesson was simple: faster generation is not enough. Serious AI-native development needs memory hygiene.

Key Takeaways

  • Project-LLM-Wiki is a repo-native LLM wiki for AI coding agents.
  • It adapts Karpathy's LLM Wiki idea to software repositories.
  • It supports Loop Engineering by recording durable lessons from each agent task.
  • At Flato.ai, it improved AI-assisted development efficiency by at least 30%.
  • It keeps code as the source of truth while making project memory reviewable in Git.

What Is Project-LLM-Wiki?

Project-LLM-Wiki is a repo-native framework for helping AI coding agents work with less confusion and less repeated context rebuilding. It is a clever application of the LLM Wiki pattern to code maintenance: the full project remains the raw corpus, while a small wiki becomes the curated trust layer.

It does not replace your codebase, issue tracker, product docs, or generated documentation. It adds a small structure around them so agents know what to trust, what to verify, and what to update after meaningful changes.

The method separates project knowledge into four layers:

  • Entry files: short launcher files such as AGENTS.md, CLAUDE.md, and CODEX.md.
  • .harness/: agent workflows, read order, routing, risk gates, review steps, and wiki update rules.
  • .project-wiki/: durable, sourced project knowledge such as architecture, modules, contracts, features, decisions, and methods.
  • raw/: unstructured source intake, including notes, transcripts, audits, copied legacy docs, URLs, and research fragments before they become authoritative.

A lightweight runtime wiki graph can then be derived from the Markdown metadata in .project-wiki/. The graph helps agents traverse related knowledge and detect broken links, but it is not a second database or a hidden memory service. Markdown remains the source.

How the System Works

The operating model is simple enough to fit in one ASCII diagram:

                 raw source material
     notes / chats / audits / old docs / code / API refs
                              |
                              v
+-------------------+   +--------------------+   +------------------+
| root entry files  |-->| .harness/          |-->| task workflow    |
| AGENTS/CODEX/etc. |   | routing and gates  |   | small/large/rev  |
+-------------------+   +--------------------+   +------------------+
                              |                          |
                              v                          v
                    +--------------------+      inspect current code
                    | .project-wiki/     |              |
                    | durable knowledge  |<-------------+
                    +--------------------+
                              |
                              v
                    runtime wiki graph
                    related knowledge, owners,
                    sources, broken links

The key is the feedback loop. The wiki does not become true because an AI wrote it. It stays useful only because each task routes through the harness, checks relevant wiki pages, inspects current code, verifies the change, and updates durable knowledge when reality changes.

Why This Is the Foundation of Loop Engineering

Loop Engineering means the development process should become smarter after every loop. A task is not finished when the patch works. It is finished when the useful learning from that task can be recovered by the next human or agent.

That is where Project-LLM-Wiki matters. It does not only solve the codebase single source of truth problem. It gives the agent a place to record what it learned while working: brittle contracts, misleading old docs, hidden module boundaries, recurring test failures, release gotchas, and other pitfalls that should not have to be rediscovered.

In a healthy Loop Engineering workflow, every meaningful agent stumble becomes structured project memory:

agent hits a pitfall
        |
        v
root cause is verified against current code
        |
        v
failure mode / contract / decision is recorded in .project-wiki/
        |
        v
next agent reads the harness and avoids repeating the same mistake

This is the difference between using AI as a one-off code generator and using AI as part of a compounding engineering system.

Why AI Coding Agents Need Project Memory

Most AI coding failures are not caused by a complete lack of context. They are caused by context that is stale, unsourced, or mixed together without priority.

A repository may have a README, old planning docs, API notes, release checklists, Slack summaries, previous agent instructions, and partially outdated architecture diagrams. A human engineer can often sense which ones are still true. An agent needs a sharper contract.

Project-LLM-Wiki makes that contract explicit:

  • Current code is always the immediate source of truth.
  • Historical docs can be preserved without being treated as authoritative.
  • Durable wiki pages cite their sources and mark source status.
  • Meaningful architecture, contract, workflow, or failure-mode changes should update project memory.
  • Review, CI, release, and push workflows can run checks so memory does not quietly drift from code.

This is especially useful for long-running AI-assisted development. The agent does not have to rediscover the same architecture boundary every session. It can read the harness, follow the routing, inspect the current code, and then update the wiki only when a real durable lesson has changed.

The Core Workflow

The working loop is intentionally simple:

  1. Start with the project entry file.
  2. Read .harness/index.md and route the task through the relevant workflow.
  3. Open the relevant .project-wiki/ pages.
  4. Inspect current code before trusting old claims.
  5. Make the smallest valid change.
  6. Run focused verification.
  7. Update project memory when durable knowledge changed.

That loop sounds modest, but it changes agent behavior. Instead of dumping more context into every prompt, the repository teaches the agent how to find the right context and how to keep it honest.

What Makes It Different from a Documentation Generator?

Project-LLM-Wiki is not trying to generate exhaustive docs. Exhaustive docs become stale quickly, and stale docs are dangerous for agents. The goal is a curated trust layer.

A good .project-wiki/ page should be small, sourced, and useful during future work. It might record:

  • which package owns a public API surface,
  • which integration contract must stay backward compatible,
  • why a design decision was made,
  • which failure mode has already cost the team time,
  • which workflow should be followed before release.

The point is not to document everything. The point is to preserve the things future agents and humans are likely to get wrong if the knowledge disappears.

How We Use This at Flato.ai

Flato.ai is building AI-native design infrastructure, including design canvas workflows, plugins, and MCP-based tooling. Those systems have many surfaces: public docs, plugin manifests, skills, OAuth flows, package layout, install instructions, editor behavior, release checklists, and product-facing claims.

In that kind of environment, a prompt-only memory strategy breaks down. Agents can produce code quickly, but they also need to preserve architectural boundaries and avoid repeating previously fixed mistakes.

Project-LLM-Wiki helped us turn repeated context into repo-local operating memory. In our workflow, it reduced context rebuilding, made handoffs clearer, and helped a small AI-native team keep architecture, contracts, release rules, and failure modes connected to current code truth. We estimate it improved development efficiency by at least 30% in our own process, with the more important gain being compounding coherence across long-running work.

A Public Sample: flato-design-mcp

For a public example, look at sologovision/flato-design-mcp. It shows how this method can keep a focused developer-tool repository easier to maintain:

  • .harness/ routes agent work through repo-specific workflows and checklists.
  • .project-wiki/architecture/repository-boundary.md defines what the repository owns and what it does not own.
  • .project-wiki/modules/codex-plugin-package.md records public package and manifest surfaces.
  • .project-wiki/contracts/flato-agent-operating-contract.md keeps durable rules for agents using Flato Design MCP.
  • .project-wiki/methods/release-doc-sync.md and .harness/checklists/doc-sync.md create a gate for public claim changes.

That last point matters. Public docs, registry metadata, plugin manifests, and skill files are not just marketing copy. For developer tools, they are code-adjacent truth surfaces. If they drift, agents and users both pay the cost.

Who Should Use Project-LLM-Wiki?

Project-LLM-Wiki is a good fit when a repository is already important enough that repeated context loss is expensive.

It is especially useful for:

  • teams using Codex, Claude Code, Cursor, or other AI coding agents across the same repo,
  • developer-tool projects with public docs and integration contracts,
  • AI-native product teams that need durable decisions and failure-mode memory,
  • open source maintainers who want agent instructions to be reviewable in Git,
  • repositories where old docs are useful but cannot be blindly trusted.

It is probably not necessary for a tiny throwaway prototype. It also should not become a documentation bureaucracy. The best adoption path is additive: initialize the harness, seed only the highest-value wiki pages, and let the memory grow from real tasks.

Quick Start

Once the repository is available locally, the core commands are straightforward:

node scripts/init-project-llm-wiki.mjs /path/to/target-repo
node scripts/verify-project-llm-wiki.mjs /path/to/target-repo
node scripts/wiki-graph.mjs /path/to/target-repo

The initializer is additive. Existing files are skipped instead of overwritten. After initialization, point your agent entry files at .harness/index.md, then start seeding the project wiki with only the knowledge that future work truly needs.

Why We Are Open Sourcing It

We think AI coding should become more transparent, not more mystical. If agents are going to help maintain serious software, teams need repo-local memory that humans can review, diff, challenge, and improve.

Project-LLM-Wiki is our contribution to that direction. It is deliberately small: Markdown, scripts, templates, and a method. No hosted platform is required. No stored graph database is required. No hidden memory layer is required.

For the Flato.ai team, this is also part of how we want to build in public. The same discipline that helps us ship AI-native design tools can help other teams make their repositories easier for agents and humans to maintain together.

FAQ

What is Project-LLM-Wiki?

Project-LLM-Wiki is an open source starter kit for making repositories easier for AI coding agents to maintain over time. It adds a repo-local harness, project wiki, raw source intake area, and runtime wiki graph helper.

How is Project-LLM-Wiki related to Karpathy's LLM Wiki?

It applies the LLM Wiki idea to software projects. The full repository and source material remain the raw corpus, while .project-wiki/ becomes the curated trust layer for durable, sourced project knowledge.

What problem does it solve for Vibe coding?

It reduces the cost of repeated context rebuilding. Instead of forcing every agent to reread the whole codebase and guess which docs are true, it gives agents a reviewable path for finding current project memory and verifying it against code.

How does it support Loop Engineering?

It turns each meaningful coding loop into reusable project memory. When an agent finds a brittle contract, stale doc, hidden boundary, or recurring failure mode, that lesson can be recorded in .project-wiki/ so future agents avoid the same mistake.

Does Project-LLM-Wiki replace documentation?

No. It is not a documentation generator or a user-doc replacement. It is a small operating layer for project memory: architecture, contracts, decisions, methods, and failure modes that need to stay aligned with current code.

Try Project-LLM-Wiki

If you are building with AI coding agents, try Project-LLM-Wiki on one active repository. Start small. Add the harness. Seed one architecture page, one contract page, and one decision page. Then run the verifier and ask your next agent to follow the loop.

The result should not feel like more documentation. It should feel like less confusion.

For more AI-native design and developer-tool work from our team, follow Flato.ai and explore the public Flato Design MCP project.