A practical system for giving AI agents durable project knowledge without stuffing everything into every prompt.

Most AI coding sessions begin with little or no reliable memory of the work that came before. The agent that spent forty minutes yesterday learning why your password hashing must remain on an old package may cheerfully replace it with the modern alternative tomorrow.

 “AI amnesia” is often a filing problem, not a model problem.  The fix looks less like clever prompt engineering and more like running a small library: a catalog for what matters most, bookshelves for deeper knowledge needed only in context, and a librarian’s discipline for keeping both honest.

Let’s go on a tour of our Synergy ECP library; by the end, you’ll have a simple three-part system for giving an AI agent durable project instructions, searchable technical knowledge, and appropriate personal context without forcing the agent to reread everything on every task.

The system has three parts:

• Catalog: the small set of operating instructions the agent is configured to load automatically or consult at the beginning of a task.
• Shelves: deeper project knowledge the agent retrieves only when it becomes relevant.
• Personal memory: user-specific working preferences stored outside the project repository.

The catalog is a budget

The catalog is less like a bookshelf and more like a budget. Leaving a book on a shelf has little immediate cost because the agent opens it only when needed. Catalog entries are different. Depending on the tool, they may be loaded automatically, attached to many requests, or consulted at the start of each task. Either way, every unnecessary line competes for the agent’s limited attention.

Different tools look for different instruction files. One may use AGENTS.md, while another looks for a tool-specific file or rule directory. Choose one canonical source when your tools allow it, then generate, link, or explicitly reference the tool-specific versions from there. This reduces the chance that two files quietly give the agent conflicting instructions.

On one unusually large project, our instruction file runs hundreds of lines, and we still treat each line as suspect. If a line is not changing behavior, it is rent with no tenant.

What belongs in the catalog

The catalog should contain instructions that are broadly applicable, expensive to rediscover, and important enough to influence the agent’s behavior across many tasks.

• Rules with the reason attached. “Use X, not Y, because Y is not FIPS 140-3 approved” is less likely to be relitigated than “Use X, not Y.” FIPS 140-3 is a security standard for cryptographic technology; naming it tells the agent that the choice is a compliance constraint, not a personal preference.
• Numbered checklists for work that crosses several systems. A checklist makes an omission easier to spot than a paragraph does.
• Explicit “do not use” decisions. Record technologies or approaches you tried and rejected so the agent stops proposing something that looks locally reasonable but does not fit the architecture.
• Deprecated vocabulary. Record old product names and concepts the codebase has moved past so the agent does not revive them.
• Retrieval instructions. Tell the agent when to search the shelves and what to do if a note conflicts with the current code.

What does not belong there? Anything the agent can recover cheaply and reliably from the project itself. Directory layouts, function signatures, and test coverage usually belong in the code, not in a permanent instruction file. Spend the budget on what the code cannot tell you.

The bookshelves hold deeper knowledge

Rules go in the catalog. Explanations go on the shelves. The catalog points the agent toward the right shelf when the situation calls for it.

Our shelves are a version-controlled folder of Markdown notes stored beside the code. Markdown is simply a plain-text format that supports headings, lists, links, and other lightweight structure. Because the notes live in version control, the same system that records changes to the code also records who changed the knowledge and when.

We organize the notes around three kinds of information that are difficult to recover by reading source code alone:

Of roughly 200 notes in one working library, 102 are gotchas, or about five gotchas for every decision record. That is not a documentation failure. It is the shape of real software work. A gotcha records what the code cannot: why a workaround exists, what breaks if someone removes it, and how much the break will cost.

Name each note like a claim

One of the best habits in the whole system is naming each entry like a card-catalog claim instead of a broad topic.

Weak title: PostgreSQL Notes

Strong title: ANALYZE Samples a Fixed Row Count, Not a Fixed Fraction

A claim-shaped title does two jobs. First, a directory listing becomes a cheap index. The agent can scan a hundred titles without opening a hundred files, and sometimes the title contains enough information to answer the question. Second, the title forces the writer to have a point. If you cannot compress a note into a claim, you may not have finished understanding the problem.

The title and filename do not have to be identical. In repositories where spaces and punctuation make shell commands awkward, use a short filename and keep the full claim inside the note:

knowledge/gotchas/analyze-samples-fixed-row-count.md

# ANALYZE Samples a Fixed Row Count, Not a Fixed Fraction

Write notes an agent can retrieve

A useful note is narrow enough to find and specific enough to trust.

• Keep each note focused on one claim. Add tags and cross-links only when they improve retrieval.
• Include exact words an agent might search for: error messages, configuration values, migration numbers, ticket numbers, product names, and absolute dates.
• State what breaks if the advice is ignored. “Page loads rise from one second to 10 to 30 seconds” tells the agent how firmly to protect the workaround.
• Record the basis of the claim. A decision without its evidence is difficult to audit and almost impossible to reevaluate well.

Teach the agent how to use the library

A well-organized library is still useless if the agent has not been taught how to retrieve from it. “Our notes are in the knowledge folder” is an address, not a retrieval method.

A practical catalog instruction can be short:

This approach keeps retrieval selective. Titles come first and bodies come second. The agent spends a little attention finding the right material instead of spending a great deal of attention rereading the entire library.

For a large collection, ask a separate search step or helper agent to scan the index and return only the likely matches. The main agent can then read those notes in full. Delegation helps with scale, but it does not remove the need to verify a note against the current project.

Teach the agent to distrust politely. Documentation is a lead, not unquestionable truth. Code changes. Infrastructure changes. A note may be stale even if it was accurate when written.

You are the librarian

A library nobody organizes becomes a library nobody uses. Worse, a confidently wrong memory can do more damage than no memory at all. A few maintenance habits keep the collection honest.

1. Make the agent write the card. After a useful debugging session, “write that up as a gotcha” often produces a good first draft while the evidence is still fresh. A human remains responsible for the note’s accuracy.
2. Update entries in place. Do not append a contradictory correction and leave both versions standing. Competing truths force the next agent to guess.
3. Assign ownership where it matters. A note about deployment should have a team or reviewer who can recognize when it becomes stale.
4. Use absolute dates. “September 18, 2026” survives the passage of time better than “recently” or “last month.”
5. Record the cost of the mistake, not only the fix. The impact tells the agent how cautious to be when a shortcut looks tempting.

Keep personal memory on a separate shelf

One reserve shelf should stay outside the project repository: personal memory. It can store details that affect how you work, such as your preferred tone, formatting conventions, development tools, and recurring machine quirks. Those preferences can help an agent collaborate with you without pretending they are project-wide rules.

Keep the boundary firm. Personal memory should not contain passwords, API keys, health information, confidential personnel information, or anything you would not want exposed in a prompt or system log. Do not mix personal details into project instructions unless they materially affect the work.

A minimal structure you can copy

You do not need 200 notes to begin. Start with one instruction file and three empty shelves:

Then add knowledge only when the work produces something worth remembering. A ten-note library that is current and searchable is more valuable than a thousand-note archive nobody trusts.

Move enforceable rules out of prose

Some rules eventually outgrow the library. If a decision can be enforced by a test, a linter, a schema, or a build check, move it there. Continuous integration, often shortened to CI, is the automated process that checks the project whenever someone proposes a change. A failing build cannot be skimmed or forgotten the way a paragraph can.

The best entry in the library may be the one you get to delete because the system now enforces it automatically. Every time a rule graduates from a note to a check, the library gets smaller and more trustworthy.

Record why, not only what

Building this system taught us one lesson that reaches beyond AI agents: record the basis of a decision, not just the decision.

We once measured our own traffic, found that a particular file format represented only 1 percent of transferred bytes, and decided not to support it. The measurement was accurate, but the basis was wrong. Our traffic was not necessarily representative of our customers’ traffic.

A note that says “we skipped this format” is unauditable. A note that says “we skipped this format because it represented 1 percent of our transferred bytes” preserves the assumption. When better evidence appears, the next person can reevaluate the decision instead of treating it as ancient law.

Start small and keep it honest

You need one catalog, a few well-defined shelves, and a habit of naming notes as claims. Add a retrieval rule. Verify notes against reality. Delete what the project can enforce on its own.

The payoff is not that the agent suddenly knows everything. It is that you stop having the same argument every day with something that cannot remember having it.