Hierarchical context layer on top of Graphify — multi-project navigation with conversation indexing

[CreatmanCEO]

Problem

Developers managing 10+ projects across multiple VPS servers hit a specific pain point that Graphify alone doesn't solve: project-level navigation. Graphify excels at code-level structure within a single project, but the agent still doesn't know which project to look at, where it's deployed, or what was discussed about it last week.

The result: every new session starts with the agent grepping the entire filesystem, SSHing into servers, and burning context before doing any real work.

Solution: Hierarchical Context on top of Graphify

We built a three-level context hierarchy where Graphify serves as Level 1.5:

Level 0: Global Project Map     — 2KB, always loaded, lists all projects with paths
Level 1: Per-project CLAUDE.md  — 3-5KB, architecture + deployment + recent changes
Level 1.5: Graphify GRAPH_REPORT — code structure graph (your tool!)
Level 2: Source files            — only when needed

The agent navigates top-down: project map → project context → graph → specific file.

What we added around Graphify

1. Level 0 project map in the agent's global instruction file — a table of all projects with local paths, VPS paths, and cross-project relationships. The agent reads this (~2KB) instead of grepping the disk.

2. Conversation indexing — a parser that converts Claude Code JSONL sessions and Claude Desktop exported chats into markdown with YAML frontmatter (date, project, topics, files touched). These become docs that Graphify can index, connecting conversations to code.

3. VPS sync command — pulls production code from remote servers to local mirrors, then runs graphify --update to keep the graph current.

4. Graphify MCP for Claude Desktop — added graphify.serve as an MCP server in Desktop config. Desktop automatically calls query_graph when asked about projects — no prompting needed.

Test Results

Tested across Claude Code (Opus 4.6, Sonnet 4.6, Haiku 4.5) and Claude Desktop (Opus 4.7):

Query	Without hierarchy	With hierarchy + Graphify
"Architecture of Project A?"	12 tool calls, reads 4+ files	1 tool call (reads CLAUDE.md)
"Which projects use LiteLLM?"	44 tool calls, missed 1 project	2 tool calls, found all 3
"Where is Project B deployed?"	9 tool calls + SSH	0 tool calls (answers from context)
Desktop: "Status of Project C?"	N/A	Auto-called query_graph twice, full answer

The key finding isn't token savings — it's that the agent stops being blind. It knows where to look instead of searching everywhere.

Working Code

Full implementation with templates, scripts, and multi-platform setup:
https://github.com/CreatmanCEO/ai-context-hierarchy

Includes:

• Level 0/1 templates for Claude Code, Cursor, Codex, Gemini CLI
• Claude Code JSONL session parser → markdown for Graphify indexing
• Claude Desktop export parser → markdown
• VPS sync command template

What Graphify Could Do Natively

Some things that would make this pattern easier to adopt:

1. Multi-project mode — graphify init --workspace that creates a Level 0 index across sibling project directories, with per-project graphs linked together.

2. Conversation ingestion — accept Claude Code .jsonl files as a doc type in the detect/extract pipeline. The YAML frontmatter format (date, project, topics, files_touched) maps directly to graph nodes and edges.

3. Remote source support — graphify add ssh://user@host:/path/ to index code living on remote servers without manual sync.

4. Compact report mode — a --summary flag that generates a 2-3KB executive summary instead of the full GRAPH_REPORT.md. For multi-project setups, the full report can be too large to load in context.

Happy to contribute PRs for any of these if there's interest.

Setup (5 minutes)

# 1. Install graphify
pip install graphifyy

# 2. Clone the hierarchy templates
git clone https://github.com/CreatmanCEO/ai-context-hierarchy

# 3. Copy Level 0 template to your agent's global instructions
#    (customize with your projects)

# 4. Add CLAUDE.md to each project (Level 1)

# 5. Run graphify on each project (Level 1.5)
cd ~/project-a && /graphify .
cd ~/project-b && /graphify .

The agent now navigates your entire workspace without grepping blindly.

[aleksandarperak33-hub]

Nice approach — the hierarchical loading is smart. One thing I'd add: if you're parsing conversation histories anyway, structuring them as assets with stable URLs (instead of markdown files that need re-indexing) can simplify the graph updates. Each conversation becomes a node the agent can reference directly without reparsing JSONL or re-running Graphify on chat exports. We've been treating conversations as first-class artifacts — publish once, reference by ID, survives across sessions. Curious — have you tried something like https://tokenrip.com?ref=scribe? Would it fit your setup?

[safishamsi]

This is a fantastic writeup — the hierarchical context pattern makes a lot of sense for multi-project setups and the benchmark numbers are compelling. Linking your repo here for others: https://github.com/CreatmanCEO/ai-context-hierarchy

The four suggestions (multi-project mode, conversation ingestion, remote source support, compact report mode) are all on our roadmap for v5.0. Conversation ingestion in particular maps closely to what we are planning — treating JSONL sessions as first-class graph nodes is exactly the right framing.

Leaving this open as a feature tracking issue for v5.0.

[CreatmanCEO]

Thanks! Happy to hear these align with the v5.0 roadmap.

What I can contribute

Conversation ingestion — I already have working parsers for both Claude Code JSONL and Desktop export formats. They output markdown with YAML frontmatter (date, project, topics, files_touched). Happy to clean them up and submit a PR as a starting point for native implementation.

One thing we learned the hard way: Claude Code JSONL messages nest content inside msg.message.content, not msg.content directly. And content can be a string (user messages) or a list of blocks with type: text/tool_use/thinking (assistant messages). The first version of our parser returned empty files because it looked in the wrong place.

Lessons from building this

Some things we discovered during development that might inform v5.0:

1. GRAPH_REPORT.md size matters more than you'd think. We initially ran graphify on a 1,777-file workspace. The report was 145KB / 2,742 lines. Loading this in context defeated the purpose — the agent spent tokens reading the report instead of reading raw files. We ended up needing a separate "brain summary" at ~3KB. A --summary or --compact flag would solve this natively.

2. AST god nodes are noisy at scale. On a mixed-language workspace, the top god nodes were GET(), error(), info(), close() — generic method names connecting everything. The semantic nodes (actual project concepts) were buried. For multi-project setups, a semantic-only graph mode (skip AST, just extract concepts from docs) was far more useful as a navigation aid.

3. Per-project beats monolithic. Running graphify on the entire workspace produced 384 communities, most of them single-node isolates from old Desktop chat topics. Running on individual projects produced 19 focused communities with meaningful structure. The multi-project mode should probably generate per-project graphs with a lightweight cross-project index on top, not one massive graph.

4. The PreToolUse hook needs a global fallback path. If the user works from their home directory (not the project root), graphify-out/GRAPH_REPORT.md doesn't exist relative to cwd. The hook silently does nothing. A configurable search path (check cwd, then check known project directories) would help.

5. Lightweight extraction without LLM. For 366 Desktop conversations, we used keyword matching + YAML frontmatter parsing instead of subagent extraction — 366 nodes, 125 edges, zero tokens. For conversation files specifically, this regex/NLP approach might be better than full semantic extraction.

6. Windows graphify claude install fails on Cyrillic paths. UnicodeEncodeError: 'charmap' codec can't encode characters when the working directory contains non-ASCII characters (common on non-English Windows). We had to install the hook manually.

Priority suggestion

Compact report mode would be the quickest win for multi-project adoption. Right now, the choice is between "load the full report (expensive)" and "don't load it (agent is blind)." A 2-3KB summary per project would make the hierarchy pattern work out of the box.

Conversation ingestion would be second — it's the missing piece that connects "what we built" with "what we discussed about it."

Let me know which to tackle first and I'll start on a PR.