ai-context-standard

How can any AI assistant understand, remember, and collaborate on a software project without repeatedly rediscovering the same information?

Move project memory out of the AI and into the repository.

Claude, Cursor, ChatGPT, Codex, and Gemini each keep their own private memory of your project today. Switch tools and you lose context; run two tools on the same repo and their understanding drifts apart — each one re-derives the same architecture, the same conventions, the same "why" behind past decisions, from scratch, every session. This is the definitive spec and reference CLI for a fix: one shared, version-controlled, plain-text "project brain" that every AI tool reads and writes, checked into the repo alongside the code it describes.

                 Git Repository
                       │
         ┌─────────────┴─────────────┐
         │                           │
   .ai/project-memory.md       .ai/working-memory.md
         │                           │
         └─────────────┬─────────────┘
                       │
      ┌────────┬───────┼────────┬────────┐
      │        │       │        │        │
   Claude   Cursor   ChatGPT   Codex   Gemini

Every AI reads the same context before starting work, and updates it as part of normal work — the same way it updates code.

Quick start

git clone <this-repo>
cd ai-context-standard
npm install
npm link                 # makes the `aictx` command available locally

cd /path/to/your/project
aictx init           # scaffold .ai/ with the standard template files
aictx adapters        # generate CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/*
aictx refresh          # establish a change-detection baseline
aictx validate          # sanity-check .ai/context.yml

aictx init never overwrites existing files unless you pass --force, so it's safe to run in a project that already has some of these files.

Layout

.ai/
├── context.yml          # manifest — every AI tool reads this first
├── project-memory.md    # durable, slow-changing facts
├── working-memory.md    # short-lived, session-to-session scratch state
├── architecture.md      # how the system fits together
├── api.md                # API inventory — public interfaces
├── database.md            # schema notes (optional)
├── symbols.md               # narrative index of non-obvious symbols
├── symbols.json               # machine-readable symbol index
├── dependencies.json            # module/service dependency graph
├── decisions.md                   # ADR-style decision log
├── roadmap.md                       # what's planned / explicitly rejected
├── issues.md                          # known bugs and workarounds
├── glossary.md                          # domain terms
├── prompts.md                             # reusable task prompts
├── handoff.md                               # in-flight task state
├── state/index.json                           # incremental-refresh state
├── archive/                                     # retired/compressed memory
└── extensions/                                    # reserved plugin namespace

.ai/ is the canonical source. Tool-specific files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/aictx.mdc) are generated stubs that just point back at it — see Adapters.

The full standard — schema, conformance levels, and every concept below — is in docs/SPEC.md. This README is an overview, not the source of truth.

What's in the standard

v1.0.0 treats all of the following as first-class concepts. Some ship with working CLI tooling today; others ship as a fixed file format and contract that a future version can automate — see docs/SPEC.md for what "Specified" means and why that's a real, load-bearing status, not a placeholder.

| Concept | Status | |---|---| | Persistent project memory | Implemented | | Working memory | Implemented | | Incremental refresh (change detection) | Implemented — aictx refresh | | Machine-readable symbol index | Implemented — symbols.json | | Dependency graph | Implemented — dependencies.json | | Architecture map | Implemented | | API inventory | Implemented | | Decision log | Implemented | | Task handoff | Implemented | | Shared multi-AI session protocol | Implemented (as convention) | | Tool adapters | Implemented — aictx adapters | | Context manifest | Implemented — context.yml | | Memory compression & tiering | Specified (RFC) | | Model routing recommendations | Specified (RFC) | | Token optimization guidelines | Specified (RFC) | | Context lifecycle (discover→summarize→compress→archive→retrieve→update) | Partially implemented — see SPEC §5.16 | | Extension points / plugin architecture | Specified — reserved namespace, no runtime |

Conformance levels

Not every project needs every file. Three levels (full detail in docs/SPEC.md §2):

| Level | Requires | |---|---| | 1 — Core | context.yml, project-memory.md, working-memory.md, handoff.md | | 2 — Extended | + architecture.md, api.md, decisions.md, dependencies.json | | 3 — Full | + symbols.json, refresh state, token_budget / preferred_models |

Why markdown, not a database

There were several ways to build this; the table below is the design survey this project started from. Markdown plus one YAML manifest won because every current AI tool already parses plain text well, and a plain-text format needs no infrastructure to adopt.

| Approach | Trade-off | |---|---| | Shared markdown files (.ai/*.md) | Most portable — any tool that can read text can use it. What this project implements. | | Structured JSON/YAML | Machine-readable, good for data tools consume directly (dependencies.json, symbols.json, state/index.json). Used alongside markdown, not instead of it. | | AI context manifest (context.yml) | A config file naming where everything else lives, plus routing/budget hints. Adopted here as the required entrypoint. | | Task-oriented handoff file | Solves the specific "switch tools mid-task without losing state" problem. Adopted here as handoff.md. | | Git-based memory | Commit .ai/ updates alongside the code changes that motivated them, so history stays coherent. This is a practice, not a file — see below. | | Vector database (Qdrant/Chroma/LanceDB) | Scales to large codebases, but adds an indexing pipeline and a service to run. Worth layering on top of .ai/ for big monorepos, not a starting point. | | Knowledge graph | Makes impact analysis explicit (UserService → uses → UserRepository → writes → Database), but needs tooling to keep in sync. dependencies.json is a minimal, hand-maintained version of this. |

Git-based memory

Treat .ai/ updates as part of the commit that motivated them:

feat(auth):

- Add OAuth login
- Update architecture
- Update project memory
- Update API docs

The repository's history becomes part of the shared knowledge — not just what changed, but why the AI/human pair thought it mattered enough to record.

Adapters

Most tools already look for their own instruction file at the repo root. aictx adapters generates a thin pointer file for each one instead of duplicating content:

| Tool | File generated | |---|---| | Claude Code | CLAUDE.md | | Cursor | .cursor/rules/aictx.mdc | | Codex / generic agents | AGENTS.md | | Gemini | GEMINI.md |

Each pointer file just tells its tool to read .ai/ for project context. They're disposable — delete and re-run aictx adapters any time. Adding support for a new tool is a one-entry addition to the ADAPTERS array, not a spec change — see CONTRIBUTING.md.

CLI reference

| Command | What it does | |---|---| | aictx init [-d dir] [-n name] [--force] | Scaffold .ai/ with the standard template files | | aictx adapters [-d dir] [--force] | Generate tool-specific pointer files | | aictx refresh [-d dir] [--check] | Detect files changed since .ai/state/index.json was last written | | aictx validate [-d dir] | Check .ai/context.yml parses and every path it references exists |

Extension points

The standard grows without breaking existing adopters through two fixed rules rather than a plugin runtime: conforming tools must ignore unrecognized context.yml keys, and .ai/extensions/ is a reserved, purely-additive namespace for plugin- or project-specific files. Full rationale in docs/SPEC.md §6.

Status

Spec v1.0.0 — stable core, extensible by design (see docs/SPEC.md §7 for the versioning policy). The CLI's own npm version is independent and still early. This repo dogfoods itself — see its own .ai/ folder. Contributions and disagreement both welcome; see CONTRIBUTING.md.

License

MIT