Feature Request: Support non-versioned project-level context for Codex

Open 💬 2 comments Opened Aug 5, 2026 by jo-hnny

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Problem

Codex currently uses AGENTS.md as the primary mechanism for providing project-specific instructions and context.

However, AGENTS.md is usually part of the repository and tracked by Git. This makes it unsuitable for storing persistent project knowledge that should not change with branches or be committed into the repository.

Developers need a place to keep long-lived project understanding, such as:

Architecture overview
System design background
Domain knowledge
Historical decisions
Known issues
Development environment notes

This information is valuable for Codex but is different from repository contribution rules.

Proposed Feature

Introduce a first-class non-versioned project context mechanism.

Possible examples:

~/.codex/projects/<project-id>/
    context.md
    architecture.md
    decisions.md
    notes.md

or:

<project-root>/.codex/context/
    overview.md
    architecture.md
    decisions.md

Codex should automatically discover and load this context when operating inside the project.

Expected Model

Separate three types of context:

User preferences

Global coding preferences and workflow

Repository instructions (AGENTS.md)

Coding rules
Contribution requirements
Team conventions

Project context (new)

Architecture understanding
Historical decisions
Domain knowledge
Known tradeoffs

Why This Matters

Coding agents need persistent understanding of software systems, not only instructions.

Human developers maintain mental context about a project: why the architecture exists, which components are fragile, and what decisions were made previously. Codex should have a first-class way to maintain this knowledge without forcing developers to put everything into repository files.

Future Extensions

Potentially allow Codex to:

Generate project context after exploring a repository
Update project context as understanding evolves
Integrate this with future memory capabilities
Keep project knowledge independent from Git branches

This would make Codex significantly more effective for long-running projects and agent-driven development workflows.

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 22 days ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#36575

Powered by Codex Action

jo-hnny · 22 days ago

Additional use case: Multi-folder project context.

Codex now allows users to add multiple folders into a single project/workspace. However, the agent currently has limited knowledge about the relationship between these folders.

For example:

my-project/
├── frontend/
├── backend/
├── shared/
└── infrastructure/

A human developer understands:

frontend is a React application consuming APIs from backend
backend depends on models and utilities from shared
infrastructure contains deployment definitions for both services

But from the agent's perspective, these may look like independent folders without explicit relationships.

A non-versioned project context could describe this topology:

# Project Structure

This project contains four components:

- frontend:
  User-facing web application.
  Depends on backend APIs.

- backend:
  Main service implementation.
  Depends on shared libraries.

- shared:
  Common types and utilities shared by frontend/backend.

- infrastructure:
  Deployment and operational configuration.

Dependency relationship:

frontend -> backend -> shared
infrastructure -> frontend/backend

This would allow Codex to reason about changes across multiple folders and avoid treating them as unrelated repositories.

This is especially important for:

monorepos
microservice systems
full-stack applications
large enterprise projects
long-running agent-driven development workflows

This reinforces the need for a first-class project context model rather than only repository-level instructions.