Here's a situation most of us have lived through by now. You start a new project, you're using an AI coding assistant — doesn't matter if it's Claude, Gemini, GPT, or whatever's inside VS Code, Antigravity, Codex, or Replit — and for the first week it's brilliant. Then you switch machines, or the chat window resets, or you swap tools halfway through because one of them is better at something specific, and suddenly the AI has no idea what you built, why you built it that way, or which files it's absolutely not allowed to touch.
You end up re-explaining the same project from scratch, over and over. And worse — sometimes it "helpfully" undoes a decision you made two weeks ago, simply because that decision only ever existed inside a chat that's now gone.
The fix I landed on is a two-prompt system, and it doesn't depend on any one AI tool or editor. The first prompt runs exactly once, the moment you create a new project folder — before there's any code in it at all. Its entire job is to set up a small memory folder inside the repository itself, so the project's history lives in the project, not in a chat log that disappears.
That's the prompt I want to walk through here.
The core idea: the folder remembers, not the chat
Whatever folder you're working in — freshly created, empty or already has some files — you open it in whatever tool you use (VS Code, Antigravity, Codex, Replit, doesn't matter), and before asking for any feature, you give the AI this first prompt. It doesn't write application code. Its only job is to look at what's actually in the folder and build a .ai-memory/ directory that will act as the project's long-term brain.
From that point on, any AI — today's tool or a completely different one six months from now — can open that same folder, read the memory files, and pick up exactly where things left off. No conversation history required.
What the prompt actually makes the AI do, step by step
First, it has to look before it touches anything. The prompt explicitly tells it to inspect the whole folder structure first — existing source files, config files, docs, build scripts, whatever's already there — and figure out the tech stack, the entry points, and anything that looks sensitive or auto-generated. If the folder's empty, fine, it starts from scratch. But it's not allowed to modify any existing project file just because it's "setting things up." That instruction alone prevents a surprising number of accidental early mistakes.
Then it creates eight specific files, each with one job:
- PROJECT.md — the permanent identity of the project: what it is, who it's for, what stack it's built on, what it integrates with. Not day-to-day status, just the stuff that basically never changes.
- CURRENT-STATE.md — the single most important file in the whole system. What's actually built right now, what's in progress, what's broken, what the very next step is. This one has to stay accurate at all times — an outdated CURRENT-STATE.md is worse than no file at all, because now the AI is confidently wrong instead of honestly unsure.
- ARCHITECTURE.md — the real technical shape of the thing: components, data flow, APIs, dependencies, how it's deployed.
- DECISIONS.md — a running log of important technical choices, why they were made, what alternatives were considered. If a decision later changes, the rule is to add a new entry explaining why, not quietly erase the old one. That history matters more than it sounds like it would.
- TASKS.md — a simple backlog with statuses (TODO, IN PROGRESS, BLOCKED, COMPLETED, CANCELLED) kept in sync with what's actually happening.
- CHANGELOG.md — meaningful changes only, not every formatting tweak.
- RESTRICTIONS.md — the file that exists purely to stop bad ideas. Anything that must never be touched, removed, or replaced goes here. If it starts out empty, the prompt still creates the structure and says clearly that no restrictions exist yet, rather than leaving it blank and ambiguous.
- HANDOFF.md — written specifically for the moment one AI session ends mid-task and another one — possibly a different model entirely — has to pick it up. Current task, what's done, what's left, current errors, warnings for whoever comes next.
And on top of those, a README.md that explains the whole memory system to any AI reading it for the first time: which files to check first, which are permanent versus temporary, how updates and restrictions and handoffs actually work.
Why "never invent" shows up so often in this prompt
If you read through the whole thing, one instruction repeats in different forms constantly: don't fabricate. Don't invent APIs, requirements, architecture, completed work, or test results that didn't happen. If something genuinely isn't known, the file should literally say UNKNOWN or REQUIRES USER CONFIRMATION instead of the AI guessing and writing it down as fact.
This matters more than it sounds like it should. A memory system is only useful if the next session can trust it. The moment an AI writes "implemented and tested" into CHANGELOG.md for something it never actually ran, every future session inherits that lie as ground truth. One false entry poisons the whole system going forward — so the prompt treats honesty about uncertainty as a hard rule, not a nice-to-have.
There's a matching rule about secrets, too: passwords, API keys, tokens, connection strings — none of that ever goes into these markdown files. They get referred to by their environment-variable name instead. Memory files tend to get committed to git and read by multiple tools, so this isn't optional.
The rule that keeps the AI from "cleaning things up"
A specific, and honestly underrated, section of this prompt exists just to stop an AI from refactoring things nobody asked it to touch. No rewriting unrelated files, no swapping out a library because it seemed outdated, no deleting something that looks unused without actually checking why it's there. The instinct to tidy up while you're already in the code is strong, and it's exactly the instinct that causes unrelated regressions on a real project. This section just tells it: preserve existing behavior unless the requirement explicitly asks for a change.
What happens every single time after that — the daily protocol
Once the memory folder exists, the prompt sets a standing rule for every future task in that repository, regardless of which AI tool is being used:
- Read README.md, PROJECT.md, CURRENT-STATE.md, and RESTRICTIONS.md first — always.
- Read ARCHITECTURE.md if the task touches anything structural, and DECISIONS.md if an existing decision might be affected.
- Read the actual relevant source files.
- Check whether the new request conflicts with anything already decided or restricted.
- Never rely on previous conversation history — the repository and its memory files are the only source of truth that's allowed to matter.
And if a new requirement genuinely does conflict with something in RESTRICTIONS.md or an existing architectural decision, the AI isn't supposed to just quietly override it. It has to explain the conflict and ask before proceeding — unless the user's new instruction is clearly and explicitly meant to replace the old one, in which case the change gets recorded properly in DECISIONS.md instead of pretending the earlier decision never existed.
Why it's written to not care which AI you're using
One line in the prompt is easy to skim past but is really the whole point of the exercise: never write instructions that depend specifically on one AI model. The memory system has to be readable by Claude, Gemini, GPT, or anything else, because the whole reason it exists is so you're not locked into finishing a project with the same tool you started it with. You could prototype in one assistant and hand the same folder to a completely different one next week, and it should still work exactly the same way.
The actual prompt
This is the one to paste in first, the moment a new project folder exists — before any feature work, before any code:
You are the primary AI development agent for this project.
Before writing or modifying any application code, you MUST establish a
persistent project-memory system inside this repository.
The purpose of this system is to make the project independent of any single
AI model or conversation. Claude, Gemini, GPT, or another coding agent must
be able to open this repository later, read the project memory, understand
the current state, and continue the work without relying on previous chat
history.
## 1. First inspect the repository
Before creating anything:
1. Inspect the complete current folder structure.
2. Identify existing source files, configuration files, documentation,
assets, scripts, package files, environment files, build files, and
deployment files.
3. Do NOT modify existing project files during this initialization unless
absolutely necessary.
4. Identify the project's technology stack.
5. Identify the apparent entry points and important files.
6. Identify files that appear sensitive, generated, or environment-specific.
If the repository is empty, create the required structure from scratch.
## 2. Create the AI memory system
Create this directory: .ai-memory/
Inside it create:
.ai-memory/PROJECT.md
.ai-memory/CURRENT-STATE.md
.ai-memory/ARCHITECTURE.md
.ai-memory/DECISIONS.md
.ai-memory/TASKS.md
.ai-memory/CHANGELOG.md
.ai-memory/RESTRICTIONS.md
.ai-memory/HANDOFF.md
Also create: .ai-memory/README.md
The files must have clear Markdown structure and must be easy for another
AI agent to understand.
## 3. Purpose of each file
PROJECT.md — permanent project identity: name, purpose, business objective,
tech stack, main features, target users, integrations, deployment target,
repository structure, important URLs, permanent requirements. No temporary
task info here.
CURRENT-STATE.md — the most important file. Current objective,
implementation status, completed work, work in progress, pending work,
known issues, current errors, recently modified files, current technical
state, immediate next action, context required to continue. Must be
updated whenever the project state materially changes. Never leave it
describing an outdated state.
ARCHITECTURE.md — actual technical architecture: app architecture, folder
structure, major components, data flow, APIs, integrations, authentication,
data model, external services, important dependencies, build/deployment
architecture, technical constraints. Update when architecture changes.
DECISIONS.md — Architecture Decision Record style history. For every
important technical decision: date, decision, reason, alternatives
considered, consequences. NEVER silently replace an existing decision — if
one changes, append a new entry explaining why.
TASKS.md — task backlog with statuses: TODO, IN PROGRESS, BLOCKED,
COMPLETED, CANCELLED. Each task: task, status, related files, dependencies,
notes. Keep synchronized with actual progress.
CHANGELOG.md — meaningful changes only: date, change, files affected,
reason, result. No trivial formatting changes.
RESTRICTIONS.md — rules that MUST NOT be violated: files/directories not to
modify, code that must be preserved, functionality that must not be
removed, dependencies not to replace without approval, APIs/integrations
that must remain, security restrictions, deployment restrictions,
user-specified constraints. If initially empty, still create the structure
and state clearly that no restrictions have been defined yet. Never assume
something is safe to remove just because it looks unused. If a change could
violate a restriction, STOP and ask for confirmation.
HANDOFF.md — for transferring work between AI models or sessions: current
task, what's completed, what's in progress, what remains, current errors,
important decisions, files changed, files needing attention, exact next
steps, warnings for the next AI, anything that can't be safely inferred
from the code. Concise but complete.
README.md — explains the memory system to another AI agent: which files
to read first, which are permanent vs. temporary/current, how to update
them, how restrictions work, how handoff works.
## 4. Mandatory AI startup protocol
For EVERY future development task in this repository, before making
changes:
1. Read .ai-memory/README.md
2. Read .ai-memory/PROJECT.md
3. Read .ai-memory/CURRENT-STATE.md
4. Read .ai-memory/RESTRICTIONS.md
5. Read .ai-memory/ARCHITECTURE.md when the task is architectural or
technically significant.
6. Read .ai-memory/DECISIONS.md when an existing technical decision may be
affected.
7. Read relevant source files.
8. Determine whether the requested change conflicts with existing
restrictions or decisions.
Do not rely on previous conversation history. The repository and its
memory files are the persistent source of truth.
## 5. Mandatory task protocol
When a new requirement is provided:
1. Understand the requirement.
2. Read the relevant memory files.
3. Inspect the relevant existing code.
4. Determine what is already implemented.
5. Determine which files need modification.
6. Check RESTRICTIONS.md.
7. Check existing architectural decisions.
8. Do not duplicate existing functionality.
9. Do not rewrite unrelated code.
10. Implement the smallest safe change that satisfies the requirement.
11. Validate/test the implementation.
12. Update the relevant memory files.
## 6. Memory update rules
After completing a meaningful task, update only what actually needs
updating. At minimum consider CURRENT-STATE.md, TASKS.md, and
CHANGELOG.md. Also update ARCHITECTURE.md if architecture changed,
DECISIONS.md if an important technical decision was made, RESTRICTIONS.md
only when a new permanent restriction is explicitly established, and
HANDOFF.md when the task is incomplete, blocked, or another AI may need to
continue it. Do NOT modify memory files merely to create noise.
## 7. Never fabricate project information
Never invent APIs, requirements, architecture, completed work, test
results, user decisions, dependencies, or deployment status. If something
is unknown, explicitly write UNKNOWN or REQUIRES USER CONFIRMATION. Do not
turn assumptions into project facts.
## 8. Protected information rule
Never place secrets into Markdown memory files — no passwords, API keys,
access tokens, private keys, connection strings containing secrets, or
personal credentials. Refer to them by environment-variable name instead.
## 9. Existing code protection
Do not modify code simply to "clean it up." Do not rewrite unrelated
files, refactor without a requirement, replace libraries without
justification, remove apparently unused functionality without
verification, change configuration or APIs unnecessarily, change UI
behavior unrelated to the requested task, or delete files without
determining their purpose. Preserve existing behavior unless the
requirement explicitly asks for a change.
## 10. Conflict resolution
If a new requirement conflicts with RESTRICTIONS.md, an important
architectural decision, or an explicit previous user requirement, do NOT
silently override it — explain the conflict and ask for confirmation
first. However, if a previous temporary implementation clearly conflicts
with a newer explicit user requirement, record the change in DECISIONS.md
instead of pretending the old decision never existed.
## 11. Model independence
Never write instructions that depend specifically on one AI model. The
project memory must be understandable by Claude, Gemini, GPT, or other
coding agents. Do not assume the next AI has access to this conversation.
## 12. Final response after every meaningful task
At the end of each task, provide: what was changed, files changed, what
was tested, current status, remaining work, and any decision requiring
confirmation. Update the appropriate .ai-memory files BEFORE reporting the
task as complete.
## 13. Initialization task
Now perform ONLY the initialization process. Inspect the repository and
create the complete .ai-memory system described above. Do not implement
application features yet. Populate the memory files using information
that can actually be verified from the repository — do not invent missing
information.
At the end, show: created files, existing project structure discovered,
technology stack discovered, important restrictions discovered, and any
information that requires confirmation. Do not modify application/source
files unless required to create the memory system itself.
How you'd actually use it
Create your project folder. Open it in whichever tool you're working in — VS Code with an AI extension, Antigravity, Codex, Replit, anything that lets an AI read and write files in that folder. Paste the prompt above as your very first message, before you ask for a single feature. Let it inspect the folder and build out .ai-memory/.
From that point forward, every time you have a new requirement, you use a second, shorter prompt that tells the AI to read that memory first, check your new ask against what already exists and what's restricted, implement only what's needed, and then update the memory files before it considers the task done. Requirement by requirement, the files in .ai-memory/ grow and adjust to reflect the real, current state of the project — so six months from now, in a completely different tool, the project can still explain itself.
That's really the whole system: one prompt to set the memory up, one prompt to keep using it. Everything else is just discipline about actually running both, every time.
