SR-SI in practice: what a context document actually looks like — and what it replaced
-
Moe Hachem - April 13, 2026
I’ve described SR-SI in abstract terms across several posts. This one is concrete. What does the document actually contain, how is it structured, and what would be happening instead if it didn’t exist.
The problem it’s solving at the session level
Every AI development session has a startup cost. You open a new conversation — because the previous one is stale, or hit its context limit, or you’re picking up a different part of the codebase — and the AI knows nothing about your project. Not the architecture, not the decisions you made last week, not the conventions the codebase has been built around, not the constraints that ruled out the obvious solutions.
Without an index, you rebuild that context conversationally. You explain the structure. You paste in the relevant files. You remind the AI of the decision it helped you make on Tuesday. This takes time, and it scales badly — the more complex the project, the more context needs to be re-established, the higher the startup cost of every session.
With an index, the AI reads the document first. One to two minutes. Then it knows the architecture, the patterns, the decisions, the conventions. The session starts from shared context instead of from zero.
What the document actually contains
The shallow index is not documentation in the traditional sense. It’s not written for human readers — it’s written for AI agents, which means it prioritizes navigability and compression over readability.
A typical entry looks like this:
/src/features/auth/manager.py — Auth orchestration. Handles session lifecycle, token refresh, permission checks. Depends on: UserService, TokenStore. Do not add business logic here.
That’s one line. Path, purpose, dependencies, constraint. Everything an AI agent needs to orient itself to that file before deciding whether to open it.
The index also contains: the tech stack, recorded in a single block. The architectural patterns the codebase follows. Business rules that constrain implementation. Recent decisions and why they were made. Files that were moved or renamed in the last 30 days.
The whole document targets under 2,000 tokens for a standard project. For larger codebases, it splits into a master index and scoped sub-indices — the master acts as a navigation hub, each sub-index covers a discrete area of the codebase and loads only when relevant.
What it replaced across the five products I’ve built with it
In the third project where I first measured SR-SI rigorously — a codebase that grew to approximately 35,000 lines — the standard workflow had established a baseline of about 2.56 tokens per line of code to maintain architectural awareness. Without a maintained index, context degradation is a function of how fast the codebase is changing relative to how stale the AI’s orientation has become — not a fixed prompt threshold. The re-explanation overhead accumulates invisibly until it becomes the dominant cost of each session.
With SR-SI applied mid-project, the net token efficiency ratio dropped to 0.37 tokens per line of code — an 85.5% reduction — despite the codebase being nearly twice the size of the baseline projects. Zero re-explanations of established architecture across the remainder of the build. The index stayed current because updating it is part of the workflow, not an afterthought.
Across the five products I’m currently building in parallel — Gestalt, Protocol, Neon Oracle, Sila, and Olives — each has its own index. Switching between products doesn’t require rebuilding context from scratch. The index does the re-orientation. The session starts from a shared map rather than from a blank slate.
What the index replaced, concretely: the re-explanation overhead. Every session that would have started with “so the architecture is…” or “remember that we decided…” instead starts with “read the index and proceed.” The compounding benefit of that change across hundreds of sessions is what produces the efficiency numbers in the research paper.
