Context Preservation — Stop Losing Decisions Between AI Sessions

The Context Problem

You've been there: you start a new Claude Code session, and you have to re-explain the project architecture, the decisions you made yesterday, and the task you were working on. As projects grow, this problem gets worse.

Decisions are forgotten. Tasks slip through the cracks. You end up re-explaining the same things over and over. The AI has no memory of what happened in previous sessions.

Frame's Approach

Frame combines project-wide records with the history of each feature. Project instructions guide the agent to the relevant files; the spec workflow adds intent, implementation decisions and outcomes as work progresses.

1. STRUCTURE.json — The Module Map

A machine-readable map of your codebase: which modules exist, what they export, what they depend on. The AI knows where everything is without scanning the entire project.

{
  "modules": {
    "main/tasksManager": {
      "path": "src/main/tasksManager.js",
      "purpose": "Task CRUD operations",
      "exports": ["init", "loadTasks", "addTask"],
      "depends": ["fs", "path", "shared/ipcChannels"]
    }
  }
}

This updates automatically via a pre-commit hook — only changed files are parsed, not the entire project.

2. PROJECT_NOTES.md — Decision Log

This is where decisions and important conversations are captured — as they happen, not as summaries after the fact.

"Don't write a summary — add the conversation as is, with its context. The user's words, the reasoning, the alternatives considered."

Record the reasoning, alternatives and relevant user context while a decision is fresh. Project notes complement the feature-specific history in specs and outcomes.

3. tasks.json — Task Tracking

Tasks are detected from conversations automatically. When the user says "let's add this feature" or "we'll do this later", the AI recognizes the pattern and offers to add it to the task list.

Each task includes the user's original request (verbatim), acceptance criteria, and technical notes — so a future session has full context on what needs to be done.

Design Principles

Several key principles shaped this system:

• No "End Session" button — context capture should be organic, not forced
• User decides importance — the AI suggests, but never auto-saves notes without asking
• Not summaries, but conversations — context must be preserved as-is
• Don't spam — not every small change deserves a note. Typo fixes, simple corrections — skip those

How It Works in Practice

When you start a new session with Claude Code in a Frame project, the AI reads AGENTS.md which tells it to check these three files. Those instructions direct it to:

• The recorded project structure and module dependencies
• Recorded decisions and their reasoning
• Pending tasks and their context

The next session has a durable starting point. It should still verify the files against the current code and record any new decisions.

This approach works with any AI coding tool — Claude Code loads .claude/rules/frame.md natively, and Codex CLI gets the context injected via a wrapper script. Same system, multiple tools.

Where spec-driven development fits

Project files describe the shared context. A feature’s spec.md, plan.md, tasks.md and outcome.md explain how a particular change came about. Keeping both lets a future session connect a rule to the implementation that introduced it.

For a concrete example, follow an email-reminder feature from spec to reusable context.