Skip to content

CreatmanCEO/ai-context-hierarchy

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
article
article
 
 
scripts
scripts
 
 
templates
templates
 
 
README.md
README.md
 
 

Repository files navigation

ai-context-hierarchy

A hierarchical context system for AI coding agents.

Your AI coding agent re-reads your entire codebase every session. It greps blindly, SSHs into servers to check configs, and asks you "which project?" for the 50th time. You spend half your context window just getting the agent oriented.

This repo is a fix. Three levels of context, loaded automatically:

Level 0: Project Map     — agent knows ALL your projects (always loaded, ~2KB)
Level 1: Project Detail  — architecture + key files (loaded when you mention a project)
Level 2: Source Files     — actual code (only when needed)

The agent navigates top-down instead of searching bottom-up.

The Problem

AI coding agents (Claude Code, Cursor, Codex, Gemini CLI) start every session blind:

  1. You ask about a project
  2. Agent greps your entire disk looking for it
  3. Reads 10-20 files to understand the architecture
  4. You correct it because it missed context
  5. Next session — repeat from step 1

If you have multiple projects, multiple servers, or code that lives on remote VPS — it gets worse. The agent SSHs into servers, reads configs, and burns through your context window before doing any actual work.

The Solution

A three-level hierarchy that mirrors how humans navigate codebases:

Level 0: Global Project Map (~2KB, always loaded)

A single file listing every project with its location, tech stack, and relationships:

## Project Map

| Project | Local path | VPS path |
|---------|-----------|----------|
| **Project A** (Telegram bot) | `~/projects/project-a/` | prod:/root/project-a/ |
| **Project B** (web app) | `~/projects/project-b/` | prod:/var/www/app/ |
| **Project C** (mobile) | `~/projects/project-c/` | — |

The agent reads this once and knows where everything lives. No grepping.

Level 1: Per-Project CLAUDE.md (~3-5KB, on demand)

Each project has its own context file with architecture, key files, deployment info:

# Project A — CLAUDE.md

## Status: LIVE
Bot: @my_bot | VPS: server-1 | Code: /root/project-a/

## Architecture
- bot.py — main handlers (~2450 lines)
- database.py — SQLite via aiosqlite
- payments.py — Telegram Stars + webhooks

## Commands
systemctl status my-bot
journalctl -u my-bot -f

Agent reads one file instead of exploring the entire project.

Level 2: Source Files (only when needed)

The agent only reads actual source code after consulting Levels 0 and 1. By then it knows exactly which file to read and why.

Level 1.5: Graphify Knowledge Graph (optional)

Run Graphify on a project to get an auto-generated code structure graph. The agent reads GRAPH_REPORT.md (~10KB) and navigates by structure instead of grepping:

pip install graphifyy
cd ~/projects/project-a
/graphify .
graphify claude install  # installs PreToolUse hook

Test Results

We tested with three query types across baseline (no context) vs hierarchy-equipped sessions:

T1: "What is the architecture of Project A?"

Baseline With Hierarchy
Behavior 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
Behavior 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
Behavior Reads files, SSHs into server Answers from memory
Tool calls 9+ 0
SSH required Yes No

T5: Claude Desktop (via Graphify MCP)

Asked about a different project in Claude Desktop with Graphify MCP connected:

  • 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 — all from the knowledge graph

Key Finding

The value isn't "10x token savings" — it's 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)
  • Actually gets more accurate answers (T2: found all projects vs missed one)

Setup Guide

Step 1: Create Level 0 — Global Project Map

Add to your agent's global instruction file:

Agent File
Claude Code ~/.claude/CLAUDE.md
Cursor .cursorrules
Codex AGENTS.md
Gemini CLI GEMINI.md
Copilot .github/copilot-instructions.md

Template (templates/level-0.md.template):

## Project Map (Level 0)

When asked about a project — read its CLAUDE.md first (Level 1), don't grep blindly.

### Projects
| Project | Local path (READ THIS FIRST) | Remote path |
|---------|------------------------------|-------------|
| **Project A** (description) | `~/projects/a/` | server-1:/root/a/ |
| **Project B** (description) | `~/projects/b/` | server-2:/var/www/b/ |

### Servers
| Name | IP | Role |
|------|-----|------|
| server-1 | x.x.x.x | Project A, monitoring |
| server-2 | y.y.y.y | Project B, database |

### Navigation Rule
1. This file = project list (Level 0, always loaded)
2. Project CLAUDE.md = architecture (Level 1, read when entering project)
3. Source files = only when needed (Level 2)

**Rule:** go Level 0 → 1 → 2. Don't read source files without first reading project CLAUDE.md.

Step 2: Create Level 1 — Per-Project Context

In each project root, create a CLAUDE.md (or equivalent) with:

  • Current status (live/dev/paused)
  • Tech stack
  • Key files and what they do
  • Deployment info (VPS, service name, commands)
  • Recent changes

Template (templates/level-1.md.template):

# Project Name — CLAUDE.md

## Status: LIVE/DEV/PAUSED
Description. URL/bot handle. VPS and path.

## Architecture
- file.py — what it does
- other.py — what it does

## Deployment
- VPS: server-name (x.x.x.x)
- Service: project-name.service
- Logs: journalctl -u project-name -f

## Recent Changes
- 2026-04-15: Added feature X
- 2026-04-10: Fixed bug Y

Step 3 (Optional): Add Graphify for Code Navigation

pip install graphifyy
cd ~/projects/your-project

In your AI coding agent:

/graphify .

This creates graphify-out/GRAPH_REPORT.md — a structural map of your code. The agent reads it before grepping.

Install always-on hook (Claude Code):

graphify claude install

For other agents:

graphify cursor install
graphify codex install
graphify gemini install

Step 4 (Optional): Graphify MCP for Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "graphify": {
      "command": "python",
      "args": ["-m", "graphify.serve", "/path/to/graphify-out/graph.json"]
    }
  }
}

Desktop gets query_graph, get_neighbors, shortest_path tools — navigates the knowledge graph without touching files.

Step 5 (Optional): VPS Code Sync

If your production code lives on remote servers, create a sync command:

# /vps-sync (Claude Code command)

| Server | Remote path | Local mirror |
|--------|------------|-------------|
| server-1 | /root/project-a/ | ~/projects/a-vps/ |
| server-2 | /var/www/b/ | ~/projects/b-vps/ |

For each: ssh + tar + scp + extract to local. Replace if newer.

This keeps your local mirror in sync with production.

Step 6 (Optional): Conversation Indexing

Index your Claude Code sessions as searchable documents:

python scripts/parse-sessions.py

This parses JSONL session files into markdown with YAML frontmatter (date, project, topics, files touched). The agent can find what you discussed last week about a specific project.

File Structure

ai-context-hierarchy/
├── README.md                     # This file
├── templates/
│   ├── level-0.md.template       # Global project map template
│   ├── level-1.md.template       # Per-project context template
│   └── desktop-prompt.md         # Claude Desktop system prompt template
├── scripts/
│   ├── parse-sessions.py         # Claude Code conversation indexer
│   ├── parse-desktop-export.py   # Claude Desktop chat parser
│   └── vps-sync.md               # VPS sync command template
├── platforms/
│   ├── claude-code.md            # Setup for Claude Code
│   ├── cursor.md                 # Setup for Cursor
│   ├── codex.md                  # Setup for Codex
│   └── gemini-cli.md             # Setup for Gemini CLI
└── examples/
    └── multi-project-setup.md    # Real-world example (anonymized)

How It Works With Graphify

Graphify is a knowledge graph tool that turns your 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 (2KB) → Level 1 (5KB) → targeted read (1 file)
With Graphify:      Agent → Level 0 → Level 1 → GRAPH_REPORT → exact node

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

Platform Support

Platform Level 0 file Level 1 file Graphify hook MCP server
Claude Code ~/.claude/CLAUDE.md project CLAUDE.md PreToolUse Yes
Claude Desktop Project instructions — — Yes (graphify.serve)
Cursor .cursorrules .cursorrules alwaysApply rule Yes
Codex AGENTS.md AGENTS.md .codex/hooks.json Yes
Gemini CLI GEMINI.md GEMINI.md BeforeTool hook —
Aider CONVENTIONS.md CONVENTIONS.md — —
Windsurf .windsurfrules .windsurfrules — —

Contributing

This is a pattern, not a framework. If you've adapted it for a platform not listed above, PRs welcome.

License

MIT

About

A hierarchical context system for AI coding agents. Stop re-explaining your codebase every session. Works with Claude Code, Cursor, Codex, Gemini CLI.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages