The Context Exchange Format (CEF) defines a small, portable, repository-local format for sharing concise project context between AI tools and models.

It exists to:

• transfer useful project understanding from one model or tool to another
• reduce the need to replay full chat history or scan an entire repository
• provide a bounded, structured context surface for consumption
• support both online and offline environments
• remain lightweight and tool-agnostic

CEF defines a reference-only context layer. It does not define execution workflow, task assignment, or agent orchestration.

CEF is not intended to be:

• a full documentation system
• a task or workflow engine
• a permissions framework
• a conversation transcript format
• a vendor-specific prompt format
• a complete representation of a repository

CEF should be:

• lightweight
• portable
• repo-native
• machine-readable
• usable offline
• safe for read-only consumers
• bounded in size and scope

Context should be concise, stable where possible, and easy to consume without special tooling.

A consumer is any model or tool that reads CEF to gain project context.

Consumers may be read-only or write-capable. Consumers must not assume write access.

A maintainer is any human, model, or tool that updates CEF contents.

Maintainer behavior is outside the scope of the reference format, except that maintained files should remain valid, concise, and internally consistent.

A context entry is a single atomic statement representing project understanding, accompanied by lightweight trust metadata.

A CEF package is the set of files that implement CEF for a project.

A repository’s local CEF package is the operational source of truth for AI context in that repository.

An optional external specification may define versioned semantics for CEF. Local operation must remain possible without network access.

In repository-based workflows, a local CEF package is conventionally stored in the .ai/ directory at the repository root.

Unless otherwise specified:

• .ai/ is the default CEF directory
• .ai/manifest.json is the CEF entrypoint
• consumers should treat .ai/ as the repository’s current CEF package

This mapping is a convention. CEF as a format is not limited to .ai/ and may be embedded or transported in other forms.

A compliant repository must contain a CEF package with the following files:

.ai/
  manifest.json
  version.json
  project.json
  context.json

Optional files may include:

.ai/
  constraints.json
  glossary.json
  unresolved.json

The manifest is the consumer entrypoint.

It defines:

• schema version
• local manifest version
• file references
• read order
• minimal loading and interpretation guidance

Consumers must read manifest.json first.

• identify local context files
• define read order
• provide lightweight loading guidance

• duplicate the contents of other files
• contain extensive behavioral instructions
• act as a workflow or task-definition file

The version file defines local version metadata for the CEF package.

It may include:

• spec identifier
• installed version
• expected manifest version
• optional update source
• optional update instructions

• communicate which version of CEF the repository uses
• support lightweight version checks
• support polite update notification

• replace manifest.json
• duplicate manifest semantics

The project file describes what the project is.

It should be concise and relatively stable.

It may include:

• project name
• project type
• purpose
• domain
• target audience
• stage or maturity

• orient new consumers quickly
• define the project at a high level

• contain execution plans
• contain chat transcripts
• replace full project documentation

The context file contains atomic context entries.

These entries represent established understanding another model or tool should know before assisting.

Each entry should be concise, atomic, and independently interpretable unless explicitly linked.

• capture context established by humans or prior models
• preserve useful project understanding across tools
• include lightweight trust signals

• become a dump of raw notes
• contain long mixed-topic summaries
• contain imperative instructions unless they are themselves part of the project context

Contains project constraints, boundaries, expectations, or rules that consumers should respect.

Contains important project-specific terms, acronyms, and definitions.

Contains open questions, ambiguities, or unsettled areas.

CEF is lightly structured.

Should include:

• schema_version
• manifest_version
• files
• read_order
• guidance

Should include:

• spec_id
• installed_version
• manifest_version

May include:

• update source
• update instructions
• notification preferences

Should include enough information to answer:

• what is this project?
• what is it for?

Should contain a list of entries.

Each entry should include:

• id
• statement
• confidence
• source_type

May include:

• source_summary
• category
• updated_at
• related_ids
• conflicts_with

Each context entry must represent one atomic statement.

Consumers should interpret entries as follows:

• entries are independent unless explicitly linked
• confidence indicates reliability, not importance
• source type indicates origin, not correctness
• omission does not imply falsehood
• low-confidence entries should not be treated as settled facts
• conflicting entries may coexist

Suggested confidence levels:

• high
• medium
• low

Suggested source types:

• human
• model
• codebase
• external

A compliant consumer should:

1. read .ai/manifest.json first
2. load files in the declared read_order
3. treat CEF as a bounded context summary, not complete project truth
4. interpret context.json entries atomically
5. use confidence and source metadata as trust signals
6. avoid assuming omitted information is false
7. avoid assuming write access
8. continue functioning in read-only mode if write access is unavailable

A read-only consumer may:

• use CEF for context
• suggest updates
• notify the user of version mismatches or newer versions

A write-capable consumer may additionally:

• offer to update local CEF files
• write or migrate files when appropriate

CEF supports stable local operation and optional remote update awareness.

• repositories must remain usable offline
• the local CEF package is the operational source of truth
• remote checks should be optional and non-blocking
• newer versions should trigger polite notification, not hard failure

Version updates are expected to be infrequent and primarily clarifying rather than breaking.

A compliant repository:

• includes the required CEF files
• keeps them valid and internally consistent
• keeps context entries atomic
• keeps the CEF package concise and bounded

A compliant consumer:

• reads manifest.json first
• respects read_order
• interprets files according to the standard
• functions correctly in read-only mode

Recommended, but not required:

• keep files small
• keep statements concise
• prefer many atomic entries over large summaries
• separate stable identity from dynamic understanding
• preserve trust metadata where possible
• avoid duplicating information across files

Possible future extensions may include:

• richer validation
• structured writeback conventions
• role-aware maintenance patterns
• more formal provenance
• optional tool adapters

These are out of scope for v1.

The Context Exchange Format (CEF) v1 defines a small, portable, reference-only context layer for repositories.

It enables systems to share concise project understanding without replaying full history, scanning entire repositories, or depending on a single tool vendor.

Core features:

• local manifest-driven loading
• lightweight version awareness
• atomic context entries
• trust-aware metadata
• offline-safe operation
• read-only compatibility by default