How to keep project context across Codex, Claude Code and other AI tools

A simple way to store the current state directly with the project so both a person and another AI tool can understand where things stand.

When I started switching between Codex, Claude Code and other AI tools at work, each of them helped me with a different part of a project. Codex worked directly with project files and implementation. Claude Code brought another perspective to the problem. Across individual chats, decisions, new tasks, questions and ideas for what to do next gradually accumulated.

Each tool worked well on its own. The problem appeared when I returned to a project and needed to understand what had actually changed since the last session, which direction we had decided to take and what the next AI tool needed to know before it started editing files.

Part of the answer was in the project itself. Part was in the conversation with Codex. Another part was in Claude Code. Some of the reasoning behind decisions existed only in my head.

On a longer-running project, that created another task on top of the work itself: reconstructing context.

So I started storing important information directly with the project, in a form that both I and another AI tool can read. I now refer to this approach as project memory.

Why context gets lost between AI tools

Imagine a simple situation.

On Monday, you work on a project in Codex. During the session, you edit several files, reject one direction and discover another task that needs to be done. On Wednesday, you open the same project in Claude Code because you want a second perspective or you want to continue with a different part of the work.

Claude can see the current project files. It does not necessarily know the full Monday conversation with Codex.

It may see the outcome of a decision without knowing why that decision was made. It may suggest a direction you have already tested and rejected. Or it may start working from an assumption that is no longer true.

You can explain the full context again. For one short task, that may not be a problem. But on a project you return to over several weeks, repeated explanations start to pile up.

A useful check for me was this question:

If I close all AI chats today, will enough information remain with the project for me to continue tomorrow without reconstructing previous conversations?

If the answer is no, part of the project memory probably lives only in the chats.

What project memory should preserve

Project memory is the context needed to continue the work. It should not contain the entire history of the project or transcripts of every conversation. Its job is to preserve continuity.

It should help the next tool understand five areas in particular.

The current state of the project

A project can have a rich history. But when we continue working, we need to know what is true now. Which version is current, what already works, what is in progress and what the next step is.

If there are three different solution proposals, the next tool should not have to guess which one we chose.

Decisions that have already been made

AI tools can generate new alternatives very quickly. I have found it useful to record decisions that I do not want to reopen from scratch in every new chat.

For example, if we decided not to implement a particular feature yet, that information is still valuable a week later. Without it, a new tool may quite reasonably suggest exactly the approach we have already evaluated.

Evidence of what changed

A sentence such as “I implemented X” in a chat is useful. But with project memory, I try to anchor the state in what actually changed in the project.

That may be an edited file, a commit, a new document, a test result or another concrete output. AI then does not have to rely only on a summary of the previous conversation. It can inspect the source as well.

Open questions

Not every part of a project has an immediate answer. I still need to know that something remains open.

If a decision, evidence or information is missing, it is more useful to preserve an explicit NEEDS CONFIRMATION label than to let the next tool silently fill the gap with its own interpretation.

Boundaries for the next piece of work

Project memory should also contain things the next tool must not change without confirmation.

That may include the project scope, a confirmed decision, the meaning of an existing task, a deadline, a priority or a part of the solution that is currently locked. These boundaries matter especially when several tools take turns working on the same project.

How to create your first PROJECT_MEMORY.md

If you are starting with project memory, choose one active project. Ideally, pick one you return to regularly and where you already use more than one AI tool.

Create this file in the project’s main folder:

PROJECT_MEMORY.md

A simple starting structure can look like this:

# Project Memory

Last updated:
[DATE]

## Project goal

What the project is solving and what outcome should be created.

## Current state

Where the project stands now.

## Completed

What has actually been completed and what confirms it.

## In progress

What is currently being worked on.

## Next step

One concrete step the work should continue with.

## Important decisions

Decisions that have already been made and should not automatically
be reopened from scratch.

## Open questions

What still does not have a confirmed answer.

## Boundaries

What should not be changed without human confirmation.

## Relevant sources

Files, commits, documents or other evidence
the current state is based on.

You do not have to write the first version manually. If Codex or Claude Code can see the project files, it can prepare a draft.

I want to create project memory for this project so I can
switch between Codex, Claude Code and other AI tools without
explaining the context from scratch in every new chat.

Review the available project files and prepare a draft PROJECT_MEMORY.md.

It should contain only the information needed to continue the work:

1. the project goal,
2. the current state,
3. what is already complete,
4. what is currently in progress,
5. the next concrete step,
6. important decisions that have already been made,
7. constraints and things that must not change without confirmation,
8. open questions and decisions that require a human,
9. relevant sources or files the state is based on.

Do not invent missing information.

Distinguish between:
- confirmed state,
- your own interpretation,
- a new proposal.

If two sources conflict or you cannot confirm something,
mark it as: NEEDS CONFIRMATION.

Show me the draft first.
Do not create or edit the file until I confirm it.

Treat the output as a working draft. AI may capture the technical state of a project correctly while still missing a decision from a meeting or the reason a particular direction was rejected.

When reviewing it, check:

• whether the current state is actually current,
• whether completed work is backed by a concrete result,
• whether AI is confusing its own proposal with a confirmed decision,
• whether any information exists only in your head or in a chat,
• whether someone who was not part of the project can understand the next step.

Remove details that are related to the project but do not help the next tool continue the work. A good project memory is not defined by its length. What matters is that it is current and reliable.

How to test the handoff between two tools

Once PROJECT_MEMORY.md exists, the next step is a test that shows whether the experiment is actually useful.

If Codex has been working on the project, open it in Claude Code, for example. Do not give the new tool the full transcript of the previous chat. Let it start from the project memory and current files.

First read PROJECT_MEMORY.md and the relevant project files.

Tell me:

1. how you understand the goal of the project,
2. what is currently true according to the sources,
3. what is in progress,
4. what the next step is,
5. which decisions have already been made,
6. where you see missing or conflicting context.

For each point, distinguish between:
- confirmed information,
- your own interpretation,
- information that needs confirmation.

Do not change anything yet.

Compare its understanding with what you know about the project.

If the new tool correctly understands the state and can name the next step without a long explanation, Project Memory is starting to work. If it gets lost, look at exactly where the problem appeared.

Maybe the file is missing a decision. Maybe it is not clear which document is current. Maybe a completed state is based only on a claim from a previous chat. That result is still useful because it shows what context is missing from the project today.

How to update project memory

Project memory loses its value if it becomes outdated after the next piece of work. That is why it makes sense to close a work session with a proposed update.

Before the session ends, AI can review the changed files and prepare a summary of what should be updated in the memory.

Before ending this work session, prepare a proposed update to PROJECT_MEMORY.md.

First review:
- today's changes in the project files,
- tests that were run,
- the current PROJECT_MEMORY.md,
- decisions confirmed during this session.

Propose:

1. what should change in the current state,
2. what was actually completed and what evidence confirms it,
3. what remains in progress,
4. what the next step is,
5. whether a new decision was made,
6. what remains open,
7. what requires my confirmation.

Distinguish between:
- a confirmed change,
- your own interpretation,
- a new proposal.

Do not delete existing decisions or open questions without explaining why.

Show me the proposed changes first.
Do not edit PROJECT_MEMORY.md until I confirm them.

This avoids creating another document that has to be manually rewritten from scratch after every session. AI prepares a proposal and the human confirms what actually happened and what should remain true going forward.

What not to store in project memory

Project memory can quickly turn into an archive of everything that has ever happened in the project. That usually makes it less useful in everyday work.

Full chat transcripts, every alternative you tried or all technical details that are already available in the code increase the volume without necessarily improving orientation.

I also would not copy information that can be reliably found in a specific source file. Project memory can point to that file and explain why it matters.

The most valuable context is the context that cannot be safely inferred from the code or documents themselves:

• why we did something,
• what we decided not to do yet,
• what remains open,
• what needs confirmation,
• where the next piece of work should continue.

When one file stops being enough

On a smaller project, PROJECT_MEMORY.md can work well for a long time. On a larger project, stable information, current state, tasks, decisions and new proposals gradually start to mix together.

At that point, it can make sense to split it, for example, like this:

PROJECT.md
CURRENT_STATE.md
TASKS.md
DECISIONS.md
INBOX.md

PROJECT.md holds the more stable goal and project rules. CURRENT_STATE.md captures the current checkpoint. TASKS.md holds longer-lived tasks. DECISIONS.md stores confirmed decisions and INBOX.md is used for new proposals that have not yet been approved.

I would not make this split pre-emptively. First use one file to learn what context actually repeats in your work. Only then give those categories their own place.

What the first week of use should show you

After several work sessions, check whether you still have to explain the whole project to a new AI tool, whether it can correctly describe the current state and whether it respects decisions that have already been made.

Also watch whether proposals are turning into confirmed state without your knowledge and whether uncertainty remains visible as uncertainty.

Project memory does not need to transfer the full history of the work between tools. It needs to preserve the context required to continue: the current state, decisions, open questions, the next step and the sources those statements are based on.

The biggest quick win for me came when I could open a project in a different AI tool without rebuilding the whole story from old chats.

Once this works for one project, the next question appears: how do you stay oriented across multiple projects without opening them one by one every day?

That is what the second chapter on shared portfolio memory covers.