ai-context-hierarchy

🇬🇧 English · 🇷🇺 Русский

A three-level context hierarchy for AI coding agents. Stop re-explaining your codebase every session. Featured in the Graphify v5.0 roadmap by the Graphify maintainer.

Companion articles: Habr (RU) · dev.to (EN)

---

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) — 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 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.

This repository demonstrates the pattern on itself — see CLAUDE.md for a working Level 1 file.

3. (Optional) Add Graphify for Level 1.5

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:

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 for the integration plan.

5. (Optional) VPS sync

If your production code lives on remote servers, see 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 | | Claude Desktop | Project Instructions | — | — | yes (graphify.serve) | platforms/claude-desktop.md | | Cursor | "Rules for AI" | .cursorrules | alwaysApply rule | yes | platforms/cursor.md | | Codex | ~/AGENTS.md | project AGENTS.md | .codex/hooks.json | yes | platforms/codex.md | | Gemini CLI | ~/GEMINI.md | project GEMINI.md | BeforeTool hook | — | platforms/gemini-cli.md | | Aider | CONVENTIONS.md | CONVENTIONS.md | — | — | (PRs welcome) | | Windsurf | .windsurfrules | .windsurfrules | — | — | (PRs welcome) |

How it works with Graphify

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 — 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 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 — the knowledge graph tool that anchors Level 1.5. v5.0 roadmap includes native multi-project mode and conversation ingestion (per issue #425).
• Claude Code Anti-Regression 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 — curated skills, hooks, agents.

Contributing

This is a pattern, not a framework. PRs welcome — see 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

• GitHub: @CreatmanCEO
• Habr: creatman
• dev.to: @creatman

License

MIT · Nick Podolyak