Context as Infrastructure¶

Why Your AI Needs a Filesystem, Not a Prompt¶

Jose Alekhinne / February 17, 2026

This post synthesizes a thread that has been running through every ctx blog post -- from the origin story to the attention budget to the discipline release. The thread is this: context is not a prompt problem. It is an infrastructure problem. And the tools we build for it should look more like filesystems than clipboard managers.

The Prompt Paradigm¶

Most AI-assisted development treats context as ephemeral:

1. Start a session.
2. Paste your system prompt, your conventions, your current task.
3. Work.
4. Session ends. Everything evaporates.
5. Next session: paste again.

This works for short interactions. For sustained development (where decisions compound over days and weeks) it fails in three ways:

It does not persist: A decision made on Tuesday must be re-explained on Wednesday. A learning captured in one session is invisible to the next.

It does not scale: As the project grows, the "paste everything" approach hits the context window ceiling. You start triaging what to include, often cutting exactly the context that would have prevented the next mistake.

It does not compose: A system prompt is a monolith. You cannot load part of it, update one section, or share a subset with a different workflow. It is all or nothing.

The Infrastructure Paradigm¶

ctx takes a different approach:

Context is not assembled per-session; it is maintained as persistent files in a .context/ directory:

.context/
  CONSTITUTION.md     # Inviolable rules
  TASKS.md            # Current work items
  CONVENTIONS.md      # Code patterns and standards
  DECISIONS.md        # Architectural choices with rationale
  LEARNINGS.md        # Gotchas and lessons learned
  ARCHITECTURE.md     # System structure
  GLOSSARY.md         # Domain terminology
  AGENT_PLAYBOOK.md   # Operating manual for agents
  journal/            # Enriched session summaries
  archive/            # Completed work, cold storage

• Each file has a single purpose;
• Each can be loaded independently;
• Each persists across sessions, tools, and team members.

This is not a novel idea. It is the same idea behind every piece of infrastructure software engineers already use:

The parallel is not metaphorical. Context files are infrastructure:

• They are versioned (git tracks them);
• They are structured (Markdown with conventions);
• They have schemas (required fields for decisions and learnings);
• And they have lifecycle management (archiving, compaction, indexing).

Separation of Concerns¶

The most important design decision in ctx is not any individual feature. It is the separation of context into distinct files with distinct purposes.

A single CONTEXT.md file would be simpler to implement. It would also be impossible to maintain.

Why? Because different types of context have different lifecycles:

Loading everything into every session wastes the attention budget on context that is irrelevant to the current task. Loading nothing forces the AI to operate blind.

Separation of concerns allows progressive disclosure:

Load the minimum that matters for this moment, with the option to load more when needed.

# Session start: load the essentials
ctx agent --budget 4000

# Deep investigation: load everything
cat .context/DECISIONS.md
cat .context/journal/2026-02-05-*.md

The filesystem is the index. File names, directory structure, and timestamps encode relevance. The AI does not need to read every file; it needs to know where to look.

The Two-Tier Persistence Model¶

ctx uses two tiers of persistence, and the distinction is architectural:

The curated tier is what the AI sees at session start. It is optimized for signal density:

• Structured entries,
• Indexed tables,
• Reverse-chronological order (newest first, so the most relevant content survives truncation).

The full dump tier is for humans and for deep investigation. It contains everything: enriched journals, archived tasks. It is never auto-loaded because its volume would destroy attention density.

This two-tier model is analogous to how traditional systems separate hot and cold storage. The hot path (curated context) is optimized for read performance -- measured not in milliseconds, but in tokens consumed per unit of useful information. The cold path (journal) is optimized for completeness.

Decision Records as First-Class Citizens¶

One of the patterns that emerged from ctx's own development is the power of structured decision records.

v0.1.0 allowed adding decisions as one-liners:

ctx add decision "Use PostgreSQL"

v0.2.0 enforced structure:

ctx add decision "Use PostgreSQL" \
  --context "Need a reliable database for user data" \
  --rationale "ACID compliance, team familiarity" \
  --consequences "Need connection pooling, team training"

The difference is not cosmetic. A one-liner decision teaches the AI what was decided. A structured decision teaches it why -- and why is what prevents the AI from unknowingly reversing the decision in a future session.

This is infrastructure thinking: decisions are not notes. They are records with required fields, just like database rows have schemas. The enforcement exists because incomplete records are worse than no records -- they create false confidence that the context is captured when it is not.

The "IDE Is the Interface" Decision¶

Early in ctx's development, there was a temptation to build a custom UI: a web dashboard for browsing sessions, editing context, viewing analytics.

The decision was no. The IDE is the interface.

# This is the ctx "UI":
code .context/

This decision was not about minimalism for its own sake. It was about recognizing that .context/ files are just files -- and files have a mature, well-understood infrastructure:

• Version control: git diff .context/DECISIONS.md shows exactly what changed and when.
• Search: Your IDE's full-text search works across all context files.
• Editing: Markdown in any editor, with preview, spell check, and syntax highlighting.
• Collaboration: Pull requests on context files work the same as pull requests on code.

Building a custom UI would have meant maintaining a parallel infrastructure that duplicates what every IDE already provides. It would have introduced its own bugs, its own update cycle, and its own learning curve.

The filesystem is not a limitation. It is the most mature, most composable, most portable infrastructure available.

Progressive Disclosure for AI¶

The concept of progressive disclosure comes from human interface design: show the user the minimum needed to make progress, with the option to drill deeper.

ctx applies the same principle to AI context:

Each level trades tokens for depth. Level 1 is sufficient for most work: the AI knows the active tasks, the key conventions, and the recent decisions. Level 3 is for archaeology: understanding why a decision was made three weeks ago, or finding a pattern in the session history.

The explicit --budget flag is the mechanism that makes this work. Without it, the default behavior would be to load everything (because more context feels safer), which destroys the attention density that makes the loaded context useful.

The constraint is the feature. A budget of 4,000 tokens forces ctx to prioritize ruthlessly: constitution first (always full), then tasks and conventions (budget-capped), then decisions and learnings scored by recency and relevance to active tasks. Entries that don't fit get title-only summaries rather than being silently dropped.

The Philosophical Shift¶

The shift from "context as prompt" to "context as infrastructure" changes how you think about AI-assisted development:

The first column treats AI interaction as a conversation. The second treats it as a system -- one that can be maintained, optimized, and debugged.

Context is not something you give the AI. It is something you maintain -- like a database, like a config file, like any other piece of infrastructure that a running system depends on.

Beyond ctx: The Principles¶

The patterns that ctx implements are not specific to ctx. They are applicable to any project that uses AI-assisted development:

1. Separate context by purpose. Do not put everything in one file. Different types of information have different lifecycles and different relevance windows.

2. Make context persistent. If a decision matters, write it down in a file that survives the session. If a learning matters, capture it with structure.

3. Budget explicitly. Know how much context you are loading and whether it is worth the attention cost.

4. Use the filesystem. File names, directory structure, and timestamps are metadata that the AI can navigate. A well-organized directory is an index that costs zero tokens to maintain.

5. Version your context. Put context files in git. Changes to decisions are as important as changes to code.

6. Design for degradation. Sessions will get long. Attention will dilute. Build mechanisms (compaction, archiving, cooldowns) that make degradation visible and manageable.

These are not ctx features. They are infrastructure principles that happen to be implemented as a CLI tool. Any team could implement them with nothing more than a directory convention and a few shell scripts.

The tool is a convenience. The principles are what matter.

The Arc¶

This post is the architectural companion to the Attention Budget. That post explained why context must be curated (token economics). This one explains how to structure it (filesystem, separation of concerns, persistence tiers).

Together with Code Is Cheap, Judgment Is Not, they form a trilogy about what matters in AI-assisted development:

• Attention Budget: the resource you're managing
• Context as Infrastructure: the system you build to manage it
• Code Is Cheap: the human skill that no system replaces

And the practices that keep it all honest:

• The 3:1 Ratio: the cadence for maintaining both code and context
• IRC as Context: the historical precedent -- stateless protocols have always needed stateful wrappers

This post synthesizes ideas from across the ctx blog series: the attention budget primitive, the two-tier persistence model, the IDE decision, and the progressive disclosure pattern. The principles are drawn from three weeks of building ctx and 70+ sessions of treating context as infrastructure rather than conversation.

See also: When a System Starts Explaining Itself -- what happens when this infrastructure starts compounding in someone else's environment.