Persistent project intelligence for AI coding agents.
ContextOS is an open-source context engineering system and Agent Skill that turns software repositories into durable memory for AI coding agents. Conversations are temporary; the repository is durable memory. By maintaining a structured, human-readable .context/ directory (INDEX, STATUS, CONSTRAINTS, PRD, ARCHITECTURE, PLAN, DECISIONS, HANDOFF), ContextOS preserves project truth across conversation restarts, context compaction, token limits, and model switches between Claude Code, Codex, and Cursor.
# 1. Scaffold .context/ directory in your repo:
# 2. Install ContextOS agent skill:
When AI coding agents build software, their memory is tethered to ephemeral chat transcripts. When you hit a token limit, conversation quota, or context compaction event, the agent suffers from context amnesia—forgetting which features were completed, reversing architectural choices, and breaking past test assumptions.
ContextOS turns the repository itself into the single source of truth. By persisting requirements, status, ADR decisions, and handoff notes inside a portable .context/ directory committed to Git, your project intelligence survives context compaction, session resets, and cross-model handoffs between Claude Code and OpenAI Codex.
ContextOS decouples the persistent memory specification from agent behaviors and entrypoints:
Plain Markdown in .context/. Readable by any human, agent, or CI test. Versioned directly in Git.
Teaches the agent when to compile prompts, update status, record decisions, or hand off without human babysitting.
CLAUDE.md and AGENTS.md remain lightweight entrypoints that point agents at .context/.
Each file serves a single high-signal role with clear lifecycle and context budgeting rules:
Tiny index map: explains what context files exist and when to read them so agents never load unnecessary context.
Objective, completed, in-progress, blocked, next exact action, honest validation results (unit/e2e/build), and git status.
Hard MUST and MUST NOT guardrails (e.g. backward compatibility, security rules, environment isolation).
Structured product requirements with stable IDs (AUTH-001, API-004) and testable acceptance criteria.
System component map, data flow pipelines, external dependencies, and runtime topology.
Phased implementation plan with strict exit criteria, validation gates, and requirement-traceability tables.
Durable Architectural Decision Records with explicit 'Do Not' guardrails to prevent subsequent agents from reversing choices.
Everything a new agent or model needs to resume cold: Next Exact Action, Do Not Redo, and known problems.
Substantial original user prompts (verbatim) alongside engineering-grade compiled execution specifications.
Superseded session notes, historical investigations, and large debug traces that should never clutter active context.
More context is not better context. Dumping entire project histories into LLM context windows causes attention dilution and hallucinations. ContextOS enforces strict token tiering:
Under 250 total lines. The immediate heartbeat read on every turn.
Only the code, test suite, and plan phase required for the active unit.
Loaded only when making architectural choices or checking schema rules.
Never loaded into active context unless explicitly requested by the user.
Converts vague user requests into verifiable engineering execution specs before touching code:
Switching models mid-project is just save here, rehydrate there. Nothing depends on a model "remembering" anything:
STATUS.md.HANDOFF.md with Next Exact Action and Do Not Redo.git commit.AGENTS.md natively, inspects STATUS.md, verifies tests, and continues without missing a beat.STATUS.md and HANDOFF.md upon completing tasks.DECISIONS.md.SessionStart hook to read CLAUDE.md → .context/INDEX.md, and resumes with full context.Run contextos health . anytime to get an unweighted, deterministic audit of your project memory. It flags memory decay before it harms agent performance:
Measures how recently STATUS.md was updated relative to active git commits.
Detects contradictory states, missing Next Actions, or stale blocker tags.
Verifies all required protocol files exist and contain non-placeholder content.
Guarantees always-loaded L0 files remain compact (< 250 lines) to avoid context bloat.
Ensures HANDOFF.md contains clear Next Action and Do Not Redo instructions.
| Coding Tool / Agent | Integration Mechanism | Support Tier | Notes |
|---|---|---|---|
| Claude Code | Agent Skill (skills/context-os/) + CLAUDE.md + Hooks | Full (Native) | Native router skill, SessionStart / PreCompact / PostCompact lifecycle hooks. |
| OpenAI Codex | AGENTS.md adapter (native open standard) | Full (Native) | Reads AGENTS.md at repo root pointing directly to .context/INDEX.md. |
| Cursor | AGENTS.md / .cursor/rules integration | Supported | Native AGENTS.md support or project rules importing .context/. |
| Gemini CLI / OpenCode | AGENTS.md / GEMINI.md adapter | Supported | Follows open AGENTS.md convention. |
| GitHub Copilot / Zed / Warp | AGENTS.md root instructions | Supported | Standard workspace agent instructions file. |
| Google Antigravity | Generic AGENTS.md adapter | Best-effort | Compatible with project prompt configuration. |
| Any Other AI Tool | Manual pointer to .context/INDEX.md | Manual | All protocol files are human-readable standard Markdown. |
ContextOS is built on strict engineering restraint:
All memory lives as human-readable Markdown inside your repository. No proprietary database binaries or lock-in.
The CLI makes zero network calls and collects zero analytics or crash reporting.
contextos validate scans memory files for high-confidence API keys, JWTs, and passwords before commits.
Conversations are temporary; the repository is durable memory. How ContextOS preserves PRDs, decisions, status, and handoffs across Claude Code, Codex, and context compaction using a portable .context/ protocol.