# ai-context-hierarchy

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Validate](https://github.com/CreatmanCEO/ai-context-hierarchy/actions/workflows/validate.yml/badge.svg)](https://github.com/CreatmanCEO/ai-context-hierarchy/actions/workflows/validate.yml)
[![Featured in Graphify v5.0 roadmap](https://img.shields.io/badge/Graphify-v5.0%20roadmap-9d6cff)](https://github.com/safishamsi/graphify/issues/425)
[![Featured on Habr](https://img.shields.io/badge/Habr-article-77a2b6)](https://habr.com/ru/articles/1024878/)
[![Featured on dev.to](https://img.shields.io/badge/dev.to-article-0a0a0a)](https://dev.to/creatman/the-context-problem-nobody-talks-about-why-ai-coding-agents-waste-80-of-tokens-on-files-they-mp1)
[![Works with](https://img.shields.io/badge/Works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20Gemini%20CLI%20%C2%B7%20Claude%20Desktop-cc785c)](#platform-support)

🇬🇧 English · [🇷🇺 Русский](README.ru.md)

**A three-level context hierarchy for AI coding agents. Stop re-explaining your codebase every session. Featured in the [Graphify v5.0 roadmap](https://github.com/safishamsi/graphify/issues/425) by the Graphify maintainer.**

> Companion articles: [Habr (RU)](https://habr.com/ru/articles/1024878/) · [dev.to (EN)](https://dev.to/creatman/the-context-problem-nobody-talks-about-why-ai-coding-agents-waste-80-of-tokens-on-files-they-mp1)

![Three-level context hierarchy diagram](docs/diagram.svg)

---

## The problem

AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, Copilot) start every session blind. You ask about a project. The agent greps your entire disk looking for it. Reads ten files to understand the architecture. Misses context. SSHs into your VPS to read configs. Burns half your context window on reconnaissance before doing any actual work. Next session — repeat from step one.

If you have multiple projects, multiple servers, or code that lives on remote VPS, the cost compounds.

## The solution

Three levels of context, loaded top-down, mirroring how humans navigate a workspace:

```
Level 0:  Global project map     — ~2 KB, always loaded     (lists ALL projects)
Level 1:  Per-project context    — ~3–5 KB, on demand        (architecture of ONE)
Level 1.5: Graphify graph         — ~10 KB, optional          (code structure)
Level 2:  Source files           — only when needed
```

The agent navigates **down** from the project map to a specific file, instead of grepping **up** from the disk root. Same agent, same model — different time-to-answer.

> **External validation.** [Graphify v5.0 roadmap (issue #425)](https://github.com/safishamsi/graphify/issues/425) — Sash Hamsi (Graphify author) confirmed all four enhancement suggestions in this proposal are on the v5.0 roadmap, with conversation ingestion mapping directly to the parsing scripts in this repo.

## Test results

Three baseline-vs-hierarchy comparisons, run on Claude Code (Opus 4.6) over the same workspace.

### T1 — "What is the architecture of Project A?"

| | Baseline | With hierarchy |
|---|---|---|
| Behaviour | Greps filesystem, reads 4+ files | Reads 1 file (`CLAUDE.md`) |
| Tool calls | 12 | 1 |
| Quality | Correct but slow | Correct, immediate |

### T2 — "Which projects use LiteLLM?"

| | Baseline | With hierarchy |
|---|---|---|
| Behaviour | Scans entire disk, broke on permission prompt | Targeted grep in known project paths |
| Projects found | 2 of 3 (missed one) | 3 of 3 |
| Tool calls | 44 (before breaking) | 2 |

### T3 — "Where is Project B deployed? Service name? Logs?"

| | Baseline | With hierarchy |
|---|---|---|
| Behaviour | Reads files, SSHs into server | Answers from memory |
| Tool calls | 9+ | 0 |
| SSH required | Yes | No |

### T4 — Claude Desktop via Graphify MCP

Asked about a different project in Claude Desktop with Graphify exposed as an MCP server:

- Desktop **automatically called `query_graph` twice** without being told to.
- Retrieved deployment status, tech stack, last work session, test results.
- Zero file reads, zero SSH.

### Key finding

The value isn't *"10× token savings."* It's that **the agent stops being blind:**

- Knows project locations without searching.
- Reads 1 file instead of 10.
- Doesn't SSH into servers for info it already has.
- Finds cross-project patterns (shared libraries, infrastructure).
- Becomes **more accurate**, not just faster — T2 missed a project under baseline.

## Quick Start (10 minutes)

### 1. Create Level 0 — global project map

Add the project map to your agent's global instruction file:

| Agent | File |
|---|---|
| Claude Code | `~/.claude/CLAUDE.md` |
| Cursor | "Rules for AI" in Settings (or `.cursorrules` per-project) |
| Codex | `~/AGENTS.md` |
| Gemini CLI | `~/GEMINI.md` |
| Copilot | `.github/copilot-instructions.md` |
| Aider | `CONVENTIONS.md` |
| Windsurf | `.windsurfrules` |
| Claude Desktop | Project "Instructions" field |

Use [`templates/level-0.md.template`](templates/level-0.md.template) as a starting point.

### 2. Create Level 1 — per-project context

In each project root, create a `CLAUDE.md` (or platform equivalent) with status, stack, key files, deployment, recent changes. Use [`templates/level-1.md.template`](templates/level-1.md.template).

This repository **demonstrates the pattern on itself** — see [CLAUDE.md](CLAUDE.md) for a working Level 1 file.

### 3. (Optional) Add Graphify for Level 1.5

```bash
pip install graphifyy
cd ~/projects/your-project
graphify .                     # creates graphify-out/GRAPH_REPORT.md
graphify claude install        # installs PreToolUse hook
```

For other agents: `graphify cursor install`, `graphify codex install`, `graphify gemini install`.

### 4. (Optional) Conversation indexing

Index your Claude Code or Claude Desktop sessions as searchable markdown:

```bash
python scripts/parse-sessions.py            # Claude Code JSONL → markdown with YAML frontmatter
python scripts/parse-desktop-export.py      # Claude Desktop export JSON → markdown
```

The frontmatter format (`date`, `project`, `topics`, `files_touched`) maps directly to Graphify graph nodes — see [issue #425](https://github.com/safishamsi/graphify/issues/425) for the integration plan.

### 5. (Optional) VPS sync

If your production code lives on remote servers, see [`scripts/vps-sync.md`](scripts/vps-sync.md) for the slash-command template that pulls remote code to a local mirror so Graphify can index it.

## Platform support

Per-platform setup guides — open the file matching your stack:

| Platform | Level 0 file | Level 1 file | Hook | MCP | Setup guide |
|---|---|---|---|---|---|
| Claude Code | `~/.claude/CLAUDE.md` | project `CLAUDE.md` | `PreToolUse` | yes | [platforms/claude-code.md](platforms/claude-code.md) |
| Claude Desktop | Project Instructions | — | — | yes (`graphify.serve`) | [platforms/claude-desktop.md](platforms/claude-desktop.md) |
| Cursor | "Rules for AI" | `.cursorrules` | `alwaysApply` rule | yes | [platforms/cursor.md](platforms/cursor.md) |
| Codex | `~/AGENTS.md` | project `AGENTS.md` | `.codex/hooks.json` | yes | [platforms/codex.md](platforms/codex.md) |
| Gemini CLI | `~/GEMINI.md` | project `GEMINI.md` | `BeforeTool` hook | — | [platforms/gemini-cli.md](platforms/gemini-cli.md) |
| Aider | `CONVENTIONS.md` | `CONVENTIONS.md` | — | — | (PRs welcome) |
| Windsurf | `.windsurfrules` | `.windsurfrules` | — | — | (PRs welcome) |

## How it works with Graphify

[Graphify](https://github.com/safishamsi/graphify) is a knowledge graph tool that converts a codebase into a navigable graph. This project adds a **hierarchical layer on top:**

```
Without hierarchy:  Agent → grep everything → read 20 files → maybe find answer
With hierarchy:     Agent → Level 0 (2 KB) → Level 1 (5 KB) → targeted file read (1)
With Graphify:      Agent → Level 0 → Level 1 → GRAPH_REPORT → exact node
```

Graphify owns code-level navigation. This repo owns project-level navigation. Together they form a complete context hierarchy from "which project?" down to "which function?".

## Real-world example

[`examples/multi-project-setup.md`](examples/multi-project-setup.md) — anonymised Level 0 file from a 15-project, 4-VPS production workspace.

## File structure

```
ai-context-hierarchy/
├── README.md                     # this file
├── README.ru.md                  # Russian translation
├── CLAUDE.md                     # Level 1 for this repo (eats its own dog food)
├── LICENSE                       # MIT
├── CHANGELOG.md                  # versioned releases
├── docs/
│   └── diagram.svg               # the hero diagram
├── templates/
│   ├── level-0.md.template       # global project map
│   ├── level-1.md.template       # per-project context
│   └── desktop-prompt.md         # Claude Desktop system prompt
├── scripts/
│   ├── parse-sessions.py         # Claude Code JSONL → markdown
│   ├── parse-desktop-export.py   # Claude Desktop export → markdown
│   └── vps-sync.md               # /vps-sync slash-command template
├── platforms/
│   ├── claude-code.md
│   ├── claude-desktop.md
│   ├── cursor.md
│   ├── codex.md
│   └── gemini-cli.md
├── examples/
│   └── multi-project-setup.md    # anonymised real-world Level 0
├── article/
│   └── draft.md                  # source of the published articles
└── .github/workflows/validate.yml # CI: link checker, template validation
```

## Limitations

- The pattern is **a convention**, not enforcement. Agents *prefer* hierarchy when given but can still grep blindly if a prompt invites it. Pair with a hook (`graphify claude install`) for harder enforcement.
- Level 0 has a token budget. Beyond ~3 KB it starts displacing actual conversation context. Keep one row per project, two lines max.
- `parse-sessions.py` is read-only on `~/.claude/projects/` and writes to `~/conversations/claude-code/` by default. Adjust paths in the script if your layout differs.
- Conversation indexing is *not* automatic — it is a script you run. Hooking it to Claude Code's `Stop` event is straightforward (see [Claude Code Anti-Regression Setup](https://github.com/CreatmanCEO/claude-code-antiregression-setup) for hook patterns) but intentionally left out of this repo to keep it agent-neutral.
- The pattern does not solve **prompt injection** or **context contamination** from low-quality earlier turns. It is about navigation, not safety.

## Related

- [Graphify](https://github.com/safishamsi/graphify) — the knowledge graph tool that anchors Level 1.5. v5.0 roadmap includes native multi-project mode and conversation ingestion (per [issue #425](https://github.com/safishamsi/graphify/issues/425)).
- [Claude Code Anti-Regression Setup](https://github.com/CreatmanCEO/claude-code-antiregression-setup) — sister repo from the same author. Hierarchy gives the agent the *right* context; anti-regression configs prevent the agent from corrupting it.
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — curated skills, hooks, agents.

## Contributing

This is a pattern, not a framework. PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for priorities (sister setup files for Aider / Windsurf / new platforms, additional language-specific Level 1 templates, alternative conversation parsers).

## Author

**Nick Podolyak** — Python developer and digital architect at [CREATMAN](https://creatman.site)

- GitHub: [@CreatmanCEO](https://github.com/CreatmanCEO)
- Habr: [creatman](https://habr.com/ru/users/creatman/)
- dev.to: [@creatman](https://dev.to/creatman)

## License

[MIT](LICENSE) · Nick Podolyak