AI_CONTEXT

Repository-native shared memory for AI coding agents.

AI_CONTEXT is a lightweight, vendor-neutral pattern for preserving the engineering context that normally gets trapped inside one AI chat, one coding agent, or one context window.

The idea is simple:

Put the important project memory in the repository, then let every AI agent read and maintain the same source of truth.

Instead of depending on a particular model's conversation history, AI_CONTEXT stores concise, durable project knowledge alongside the code:

project/
├── AGENTS.md / CLAUDE.md / GEMINI.md   # Agent-specific entry point
└── docs/
    ├── AI_CONTEXT.md                   # Current project state
    ├── decisions/                      # Durable design decisions
    └── sessions/                       # Useful development handoffs

The result is a practical bridge between Codex, Claude Code, Gemini CLI, other coding agents, human developers, and future sessions that have never seen the original conversation.

This repository uses AI_CONTEXT itself

AI_CONTEXT is intentionally dogfooding its own convention. The generic files under templates/ and examples/ teach other projects how to adopt the pattern, while this repository's own live shared memory is maintained in:

AGENTS.md — project-specific agent instructions;
docs/AI_CONTEXT.md — the current state of AI_CONTEXT itself;
docs/decisions/ — real decisions made while evolving the project;
docs/sessions/ — real development handoffs for future agents and contributors.

That makes this repository both the reference material and a working example. The first decision record documents why the project chose to self-host the pattern: 0001-dogfood-ai-context.md.

The problem

AI coding agents are increasingly capable of working for long periods on real repositories, but their conversational memory is not the repository's memory.

Important context can disappear when:

a context window is compacted or exhausted;
a new chat or agent session is started;
work moves from one AI product to another;
another developer or agent takes over;
a conversation contains the reason for a decision, but the code only contains the result;
an experiment failed in chat and a future agent unknowingly repeats it.

Source code answers what exists. It often does not answer why it exists, what was tried, what is currently broken, or what should happen next.

AI_CONTEXT externalizes that missing layer into ordinary Markdown tracked with the project.

The core idea

AI_CONTEXT separates project memory into three kinds of information.

1. Current state — `docs/AI_CONTEXT.md`

A short, living handoff document describing the project as it exists now.

It should answer:

What are we building?
What is the current architecture?
What works?
What is broken or unfinished?
What changed recently?
What is being worked on now?
What should happen next?
Which files matter most?

It is not a chronological diary. Keep it concise and rewrite stale sections as the project changes.

2. Durable decisions — `docs/decisions/`

Important architectural or design choices deserve a permanent explanation.

Each decision record captures:

the problem;
the chosen approach;
alternatives considered;
rationale;
consequences and tradeoffs.

This follows the well-established Architecture Decision Record (ADR) idea, adapted for AI-assisted development.

3. Session handoffs — `docs/sessions/`

Session journals preserve useful continuity from substantial work that does not belong in the permanent current-state document.

A good session record can capture:

the user's or team's goal;
what was investigated;
meaningful discoveries;
changes made;
tests and results;
failed approaches worth remembering;
unresolved issues;
the state in which the project was left.

Session journals should be created for meaningful work, not every chat or tiny edit.

Version-controlled memory

Because AI_CONTEXT lives in the repository, project memory becomes a first-class versioned artifact rather than an invisible side effect of a chat session.

Git automatically gives the shared memory many of the same properties as source code:

History — each commit preserves what the project's shared understanding looked like at that point in time.
Diffs — reviewers can see exactly how project state, assumptions, decisions, or next steps changed alongside the implementation.
Review — memory changes can be inspected in pull requests instead of being silently accepted because an AI said them.
Attribution — commit history and blame can help identify when a piece of context was introduced or changed.
Rollback — an incorrect or premature context update can be reverted like any other repository change.
Correlation with code — context can be committed alongside the code, configuration, or documentation that caused the project's understanding to change.
Historical reconstruction — checking out an older commit can reveal both the implementation and the shared project context that existed at that stage.

This creates a useful kind of memory archaeology: humans and agents can inspect not only what the project became, but how its shared understanding evolved.

For example, a commit that changes an authentication architecture can update both the implementation and docs/AI_CONTEXT.md. A later agent can inspect the diff and see that the code changed and that the project's authoritative description changed with it.

That also makes incorrect memory visible. If an agent marks a problem as solved when the code or tests do not support that claim, the context change appears in the same reviewable history as the rest of the work.

AI_CONTEXT turns project memory into a shared, auditable, version-controlled artifact of the repository.

Why not just save the whole AI chat?

Because raw chat history is usually the wrong abstraction for long-term engineering memory.

Raw transcripts are noisy, repetitive, expensive to reload into context, full of temporary speculation, likely to contain irrelevant tool output, potentially sensitive, tied to one product's conversation format, and poor at distinguishing current truth from ideas that were later rejected.

AI_CONTEXT stores the engineering result of the conversation, not a transcript of it.

Record conclusions, requirements, constraints, tradeoffs, experiments, failures, test results, and decisions.

Do not attempt to store hidden chain-of-thought or private internal reasoning traces.

Recommended authority order

When sources disagree, a useful default is:

1. Current code, configuration, tests, and observable runtime behavior
2. Accepted decision records
3. docs/AI_CONTEXT.md
4. Recent relevant session journals
5. Remembered or summarized chat context

Project-specific rules can override this, but explicitly defining an authority order prevents stale notes from silently becoming truth.

Agent-neutral by design

The shared memory files are intentionally independent of the tool that reads them.

Different agents can use their native project instruction mechanism as a thin adapter into the same context:

Agent / tool	Typical repository entry point	Role in AI_CONTEXT
OpenAI Codex	`AGENTS.md`	Tell Codex to read and maintain the shared context
Claude Code	`CLAUDE.md`	Point Claude at the same shared context and rules
Gemini CLI	`GEMINI.md`	Point Gemini at the same shared context and rules
ChatGPT Work	Startup prompt / `AI_CONTEXT_WORK.md`	Explicitly supply the shared instructions and task pointers
Other agents	Native instructions or initial prompt	Read the same `docs/` memory layer
Humans	README + Markdown	Read and edit the exact same project memory

The adapter file should remain small. The durable knowledge belongs in the shared files, not duplicated separately for each AI product.

Gemini CLI can also be configured to load alternate context filenames such as AGENTS.md, which can reduce adapter duplication in mixed-agent repositories.

Quick start

Copy the templates from this repository into an existing project:

project/
├── AGENTS.md                 # or another native agent entry point
└── docs/
    ├── AI_CONTEXT.md
    ├── decisions/
    │   └── 0001-example.md
    └── sessions/
        └── YYYY-MM-DD-topic.md

Start with the files in templates/, then add the appropriate adapter from examples/.

The most important instruction is roughly:

Before substantial work, read `docs/AI_CONTEXT.md` and any relevant
accepted decisions or recent session handoffs.

After substantial work, update those files when the project state,
important decisions, or useful continuation context changed.

That small feedback loop is the heart of the pattern.

Optional CLI — v0.1

AI_CONTEXT does not require a CLI. The Markdown convention above remains the source of truth and can always be adopted manually.

For convenience, v0.1 includes a small Python command that scaffolds the same structure in an existing Git repository. It has no runtime dependencies, makes no network calls, and does not invoke an LLM.

Until a package release is published, install it directly from GitHub:

python -m pip install "git+https://github.com/yoliverasPozo/AI_CONTEXT.git"

Then run this from anywhere inside the Git repository you want to initialize:

ai-context init

In an interactive terminal, the command offers optional agent adapters. You can also select them explicitly:

ai-context init --agents codex,claude
ai-context init --agents gemini
ai-context init --agents generic
ai-context init --agents none
ai-context init --coordination --agents codex
ai-context init --agents work

Adapter mapping:

Selection	File created
`codex`	`AGENTS.md`
`claude`	`CLAUDE.md`
`gemini`	`GEMINI.md`
`generic`	`AI_CONTEXT_PROMPT.md`
`work`	`AI_CONTEXT_WORK.md` plus shared coordination files

The core initialization always creates:

docs/
├── AI_CONTEXT.md
├── decisions/
└── sessions/

Useful safety options:

ai-context init --dry-run --agents codex
ai-context init --force --agents codex

--dry-run shows what would change without writing files. Existing AI_CONTEXT-managed files are never overwritten by default; --force must be supplied explicitly and should be used carefully.

After initialization, ask your chosen AI agent to inspect the repository and populate docs/AI_CONTEXT.md from the actual project state.

The design decision behind the CLI is recorded in 0002-python-cli-v0.1.md.

Optional agent coordination and ChatGPT Work

The coordination protocol adds practical task transfers:
owner/status, authorized scope, branch/revision, acknowledgment, test evidence,
and a concrete next action. It uses the existing session directory; the core
context, ADR, and session conventions remain valid without this extension.

--coordination adds docs/COORDINATION.md and docs/HANDOFF_TEMPLATE.md.
Selecting --agents work also installs the Work startup and return prompts
as AI_CONTEXT_WORK.md and includes those supporting files automatically.
Paste or attach the startup prompt explicitly; automatic loading is not assumed.
Give each session the repository, branch/commit or public PR, handoff path,
requested outcome, and authorized scope. Return the same pointers to the next
session, which verifies and acknowledges the result.

Check each session's actual capabilities. If it cannot write to the repository,
it can return a proposed handoff for an authorized writer to review and save.
GitHub access does not guarantee shared chat history or artifact access.

For populated projects, follow the manual additive adoption steps.
The initializer still refuses existing managed files; --force replaces them
and is not a safe migration mechanism. No credentials, private chat identifiers,
transcripts, or sensitive artifacts belong in public handoffs.

Suggested workflow

At the start of substantial work

Read the agent's repository instruction file.
Read docs/AI_CONTEXT.md.
Read relevant accepted decisions.
Inspect recent session journals if prior debugging or experimentation matters.
Inspect the actual repository before trusting documentation blindly.

During work

Treat the code and tests as the source of observable truth.
Preserve important user or product constraints.
Record meaningful failed experiments instead of letting future agents rediscover them.
Create a decision record when a choice will matter beyond the current task.

Before finishing

Run relevant validation and tests.
Update AI_CONTEXT.md if current state changed.
Add or update a session handoff if future continuation would benefit.
Add an ADR if a durable design decision was made.
Remove stale information instead of endlessly appending to the context file.
Commit context changes alongside the code they describe whenever practical.

After context loss or in a brand-new session

A fresh agent should be able to reconstruct the project by reading the repository rather than asking a human to retell the whole history.

A useful recovery instruction is:

Read the repository instructions, docs/AI_CONTEXT.md, relevant decisions,
and recent session notes. Inspect the current code and Git state, then
reconstruct what has already been completed, what remains unresolved, and
what the next logical step is before making changes.

What belongs in shared context?

Good candidates include project goals and non-obvious requirements, architectural boundaries, important invariants, compatibility requirements, deployment assumptions that materially affect development, accepted design decisions, known bugs and limitations, significant test results, failed approaches likely to be attempted again, migration state, active work and next steps, important file locations, and stakeholder requirements that directly affect the project.

Poor candidates include secrets or credentials, API keys and tokens, unrelated personal information, raw model chain-of-thought, full chat transcripts, every shell command ever run, obvious facts already clear from the code, speculative ideas that were never adopted, and huge pasted logs that can be stored elsewhere and referenced instead.

Security and privacy

A Git repository is a durable publishing and replication mechanism. Treat context files accordingly.

Never place secrets in shared AI context.

Avoid committing passwords, private keys, bearer tokens, API credentials, private customer data, sensitive personal information, or confidential conversation content that does not belong in source control.

For private machine-specific memory, use a local ignored file or the agent's private/user-level memory mechanism rather than the shared repository layer.

A useful rule is:

If it would be unsafe in the repository's README, it is probably unsafe in AI_CONTEXT.md.

Keep context bounded

More context is not automatically better context.

A good AI_CONTEXT.md should be a high-signal briefing, not an archive.

Prefer concise summaries, links to deeper records, current facts, explicit uncertainty, dated session records for historical detail, and one decision per ADR.

Avoid allowing AI_CONTEXT.md to grow forever. When something becomes historical, move the durable rationale into a decision record or leave the detail in a session journal and shorten the current-state summary.

Example

Imagine Agent A spends two hours debugging an authentication problem and discovers that requests fail because discovery and message calls use different credential paths.

Without shared context:

Agent A chat ends
      ↓
reasoning disappears
      ↓
Agent B starts later
      ↓
repeats the same investigation

With AI_CONTEXT:

Agent A
  ├─ fixes code
  ├─ updates AI_CONTEXT.md
  ├─ records the authentication decision
  └─ leaves a session handoff
             ↓
          Git repo
             ↓
      ┌──────┴──────┐
   Agent B         Human
      ↓               ↓
continues from      understands
known state         why it works

The repository becomes the continuity layer.

Repository contents

templates/AI_CONTEXT.md — living project-state template
templates/SESSION.md — substantial-work handoff template
templates/HANDOFF.md — optional explicit task-transfer template
docs/COORDINATION.md — shared agent coordination instructions
examples/CHATGPT_WORK.md — Work startup and return prompts
templates/ADR.md — lightweight decision-record template
examples/AGENTS.md — Codex / AGENTS-style adapter
examples/CLAUDE.md — Claude Code adapter
examples/GEMINI.md — Gemini CLI adapter
docs/ADOPTION.md — guidance for introducing the pattern to an existing project
docs/AI_CONTEXT.md — this repository's live current-state context
docs/decisions/ — this repository's real durable decisions
docs/sessions/ — this repository's real development handoffs
src/ai_context/ — optional CLI implementation
tests/ — CLI and resource-synchronization tests
pyproject.toml — Python package metadata and ai-context console entry point

Design principles

AI_CONTEXT is intentionally boring technology:

Plain Markdown — readable by humans and models.
Git-native — versioned with the work it explains.
Vendor-neutral — no dependency on a specific model or API.
Curated, not transcript-based — preserve useful engineering knowledge, not conversational noise.
Layered — current state, durable decisions, and historical handoffs serve different purposes.
Recoverable — a new agent should be able to continue after context loss.
Auditable — changes to project memory are reviewable like code.
Bounded — important context stays small enough to remain useful.
Security-aware — shared memory is not a secret store.
Human-compatible — the documentation remains useful even if no AI agent is involved.

Existing ideas this builds on

AI_CONTEXT combines several established practices rather than inventing a proprietary memory format: repository instruction files used by modern coding agents, Architecture Decision Records (ADRs), developer handoff notes, engineering journals, and docs-as-code.

Useful references:

OpenAI Codex: https://developers.openai.com/codex/
Claude Code: https://code.claude.com/docs/en/overview
Gemini CLI context files: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md
Architecture Decision Records: https://adr.github.io/

Status

AI_CONTEXT currently provides both the vendor-neutral Markdown convention and an optional v0.1 initializer CLI.

The CLI is intentionally small: it scaffolds the repository memory layer and optional agent adapters, but it does not generate project context with an LLM and is not required to use the convention.

Likely future additions include ai-context check, stale-context detection, context-size checks, additional agent/IDE adapters, optional machine-readable metadata, improved release/distribution options, and richer CI integration.

Contributions and real-world examples are welcome.

A one-sentence definition

AI_CONTEXT is a repository-native shared memory pattern that lets humans and different AI agents preserve and recover the current state, important decisions, and useful development history of a project without relying on any single chat session.