Back to Blog
AI AgentsKnowledge GraphsMCPClaude Code

Graphify: Temporal Knowledge Graphs for Stateful AI Agents

How I built Graphify — a tool that turns any folder of code, docs, or notes into a navigable knowledge graph — and why temporal memory is the missing piece in most AI agent architectures.

4 min read

Graphify: Temporal Knowledge Graphs for Stateful AI Agents

Most AI agent sessions are amnesiac. Every conversation starts cold. The agent reads files, builds context, does work — and then that accumulated understanding evaporates. Next session, start over.

This is the core problem Graphify solves: persistent, queryable knowledge that survives across agent sessions.

Why Graph, Not Just RAG?

Retrieval-Augmented Generation (RAG) gets you the right chunks of text. But it doesn't tell you:

  • How concepts relate to each other
  • Which parts of a codebase are central vs peripheral
  • What changed between yesterday and today
  • How an explanation in a doc maps to a function in code

A knowledge graph preserves structure. RAG preserves content. You need both.

The Core Idea

Code + Docs + Notes + Papers
          ↓
    Entity Extraction
    (AST for code, LLM for docs)
          ↓
    Graph Construction
    (nodes = concepts, edges = relationships)
          ↓
    Community Detection
    (Louvain algorithm, coherence scoring)
          ↓
    Persistent graph.json
    → HTML visualization
    → Obsidian vault
    → MCP server for agents

Every edge is tagged as EXTRACTED (explicit in source), INFERRED (reasonable inference), or AMBIGUOUS (flagged for review). This honest audit trail means you always know what the graph found vs what it guessed.

Architecture: Claude Code + Graphify

In my workflow, Graphify runs as a subagent inside Claude Code:

graphify-invocation.ts
// Claude spawns a Graphify extraction subagent
Agent({
  description: "Extract knowledge graph from updated docs",
  subagent_type: "general-purpose",
  prompt: `
    You are a graphify extraction subagent.
    Files (chunk 1 of 3): [file list]
    
    Extract entities and relationships.
    Output valid JSON: { nodes, edges, hyperedges }
    Tag each edge: EXTRACTED | INFERRED | AMBIGUOUS
  `
})

Multiple subagents run in parallel — one per chunk of files — then merge their results.

Temporal Tracking

The "temporal" part matters. When you run Graphify again after changes, it:

  1. Checks which files changed since last run
  2. Re-extracts only those files (semantic cache for unchanged files)
  3. Diffs the new graph against the old one
  4. Shows you what concepts appeared, disappeared, or changed relationship
# Incremental update — only re-processes changed files
graphify /my-project --update
 
# Output:
# Cache: 47 files hit, 3 files need extraction
# New nodes: DatabaseConnection, QueryCache, HealthCheck
# New edges: 8
# Changed community: "Authentication" gained 3 nodes

MCP Server Mode

The most powerful use: expose your knowledge graph as an MCP server so AI agents can query it:

graphify-mcp-server.py
from mcp import Server, Tool
 
server = Server("graphify")
 
@server.tool("query_graph")
async def query_graph(question: str, mode: str = "bfs") -> str:
    """Answer questions using BFS/DFS graph traversal."""
    start_nodes = find_matching_nodes(question)
    subgraph = traverse(start_nodes, mode=mode, depth=3)
    return format_for_llm(subgraph)
 
@server.tool("shortest_path")  
async def shortest_path(source: str, target: str) -> str:
    """Find the conceptual path between two ideas."""
    path = nx.shortest_path(G, source_node, target_node)
    return explain_path(path)

Now any agent in your stack can ask "How does the authentication module relate to the session cache?" and get a graph-grounded answer — not a hallucination.

Results in My Workflow

Using Graphify across my projects:

  • 60–70% fewer re-reads — agents find what they need via graph query instead of re-scanning files
  • Surprising connections — the community detection regularly surfaces cross-file relationships I didn't know existed
  • Onboarding acceleration — new engineers run Graphify on a codebase and get a navigable map in minutes

The source is available on GitHub. If you're building stateful AI agents and want a persistent knowledge layer that doesn't require a vector database subscription — Graphify is worth a look.

Building AI tools and want to compare notes? Connect on LinkedIn.

All Posts