The most useful memory upgrade we gave our AI project was not a larger prompt or a complete chat archive. It was a small set of Markdown files inside the repository.

In our first Our AI Journey field note, I described how a loose question became @whitebalance_ai, a publisher, platform connections and an editorial workflow. That project quickly became too large to reconstruct from old conversations every time a new task started.

So we gave the project a memory it could carry forward.

This guide shows the setup we now use: a navigable project wiki, a rule that tells the agent when to read and maintain it, and a clear separation between current facts, decisions, open questions and session outcomes.

You do not need wiki software. A folder of well-maintained Markdown files is enough.

The problem is not context length

Long conversations accumulate several kinds of information at once:

  • decisions that should remain true
  • temporary ideas that were never accepted
  • implementation details that later changed
  • unresolved questions
  • failed attempts and their useful lessons
  • credentials, account details or personal information that should not be copied anywhere

Saving all of that as one transcript does not create reliable project knowledge. It creates a larger search problem.

The goal of a project wiki is not to remember everything. It is to preserve the smallest current set of information that helps the next task make a better decision.

Start with one small structure

Our setup grew over time, but the useful core looks like this:

project/
├── AGENTS.md
└── docs/
    └── knowledge/
        ├── index.md
        ├── project-overview.md
        ├── architecture.md
        ├── design-system.md
        ├── missing-information.md
        ├── technical-debt.md
        ├── decisions/
        │   ├── index.md
        │   └── ADR-0001-example-decision.md
        └── session-history/
            ├── index.md
            └── 2026-08-01-example-outcome.md

Do not copy this tree mechanically. Keep only the files your project can maintain. A small project may need only an index, an overview, open questions and decisions.

The important part is that every file has a distinct job.

Make the index a router, not a summary dump

The agent should not load the entire wiki before every task. That wastes context and makes irrelevant rules compete with the current problem.

Use index.md as a routing page:

# Project knowledge

- Scope and current status: project-overview.md
- Architecture and data flow: architecture.md
- UI and brand rules: design-system.md
- Unresolved questions: missing-information.md
- Known limitations: technical-debt.md
- Why we made important choices: decisions/index.md
- Outcomes from completed work: session-history/index.md

A deployment task can open the architecture and operations material. A visual task can open the design system. Both begin from the same index without carrying the entire project into the conversation.

Separate facts by their lifespan

One large notes.md file is easy to start and difficult to trust. Separate information according to how it changes.

Current state

Files such as project-overview.md and architecture.md describe what is true now. Update them when the implementation changes. Do not keep obsolete behavior in the main description merely because it used to be correct.

Decisions

Decision records explain a choice that future work might otherwise reopen:

  • What problem were we solving?
  • What did we decide?
  • Which alternatives did we reject?
  • What are the consequences?
  • Has a later decision superseded this one?

The explanation matters more than the date. “Use PHP” is a rule. “Use PHP because the existing host supports it and the project explicitly excludes Node.js toolchains” is a decision future tasks can apply.

Open questions and technical debt

Do not write assumptions as facts. Put unresolved product choices in missing-information.md and known implementation limits in technical-debt.md.

This gives the next task permission to see uncertainty instead of inventing certainty.

Session outcomes

A session history is not a transcript. Record what changed, what was verified and what remains open. Leave out conversational detours unless they explain an important constraint or failure.

Tell the agent how to use the wiki

A knowledge folder helps only if the working process consistently reads and updates it. Put a short maintenance contract in the repository-level AGENTS.md or the equivalent instruction file used by your tools.

Before a non-trivial task:
1. Read docs/knowledge/index.md.
2. Open only the documents relevant to the task.
3. Check the current implementation before trusting the documentation.

While working:
- Update existing knowledge instead of creating duplicate notes.
- Store confirmed facts only.
- Put unresolved points in missing-information.md.
- Never store secrets, credentials or personal data.

Before finishing:
- Check whether architecture, behavior, workflow or known limits changed.
- Update the relevant documents and their index links.

The instruction does two jobs. It makes project memory available at the beginning, and it prevents that memory from becoming stale at the end.

Keep evidence close to the claim

The wiki is not automatically correct because it lives in the repository.

When documentation and implementation disagree, inspect the actual code, configuration or platform state. Then update the wiki and record the discrepancy if it matters.

Useful evidence includes:

  • the current code path
  • a passing test that enforces a boundary
  • a confirmed deployment result
  • an official platform response
  • a human product decision

Avoid phrases such as “probably configured” or “should be live” in current-state documents. Those belong in open questions until someone verifies them.

Keep secrets and transcripts out

Project memory should reduce risk, not become a second secret store.

Never put passwords, API tokens, recovery codes, private customer information or raw environment files into the wiki. Reference the approved storage mechanism instead: for example, “the production signing key is stored in the macOS Keychain and private server configuration.”

Complete transcripts are usually a poor default too. They contain abandoned ideas, repeated context and information that was useful only for one moment. Preserve the decision or outcome, not every sentence that led to it.

Use a maintenance loop

The workflow is small enough to repeat after every meaningful task:

  • Read the index.
  • Load only the relevant knowledge.
  • Inspect the current files or external state.
  • Do the work and verify the result.
  • Update current-state documentation.
  • Record new decisions or limitations.
  • Add a short session outcome when the change is worth preserving.

The wiki becomes valuable through this loop, not through an elaborate initial setup.

A one-sentence starter prompt

You do not need to design the whole knowledge architecture before starting. This is enough:

Set up a small Markdown project wiki in docs/knowledge, add an index that routes tasks to the right files, and add repository instructions that keep confirmed knowledge current without storing secrets or full chat transcripts.

Review the first tree. Remove categories you will not maintain. Add a file only when the project has a real type of knowledge that needs a home.

Where this approach has limits

A repository wiki works well for project-specific engineering, content and operational knowledge that changes alongside files. It is less suitable as the only source for:

  • rapidly changing external rules that must be rechecked at implementation time
  • credentials or sensitive records
  • large datasets and analytics
  • company-wide knowledge owned outside one repository
  • decisions no one is willing to maintain

The wiki should point to authoritative external systems where necessary instead of copying everything into Markdown.

The smallest useful version

If the full structure feels heavy, start with four files:

docs/knowledge/
├── index.md
├── project-overview.md
├── decisions.md
└── missing-information.md

Add the read-and-update rule to AGENTS.md. That is enough to stop reconstructing the project from zero in every new task.

The best project memory is not the largest one. It is the one the next task can find, trust and maintain.

AI, properly calibrated.Follow @whitebalance_ai