What I Learned Building a Knowledge Graph for AI Agents

Avatar photoByAdil

AI assistants scrape through TODO files, commit messages, and scattered notes, trying to piece together what blocks a feature. They guess. They miss critical dependencies and recent decisions.

The fix: let agents query project knowledge like a database instead of parsing human prose.

Before: Context scattered across files 

# “What’s blocking the auth feature?”
# AI scrapes TODO.md, commit messages, Slack. Guesses. You verify manually.

After: Query the graph 

code-hq query 'FIND ?b WHERE urn:task:auth-123 dependsOn* ?b AND ?b.taskStatus != "Done"'
# → urn:task:db-456  (Setup database, assigned to Bob)

The core problems

  • Missing relationships: TODO lists describe tasks in isolation. Real work is about dependencies, ownership, and ripple effects.
  • Context brittleness: Rephrase a comment or move a task, and the AI’s understanding breaks. No stable way to reference project state.
  • Translation overhead: Humans use Markdown. Agents need structured data.

Solution: maintain two layers – one for humans (Markdown, UIs) and one for machines (structured graph). Keep them synchronized.

The approach

1) Everything as a graph

Projects aren’t lists – they’re webs of relationships. Represent everything as JSON-LD entities with clear connections: 

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@id": "urn:task:auth-123",
      "@type": "Task",
      "name": "Fix authentication bug",
      "taskStatus": "InProgress",
      "priority": "high",
      "assignee": { "@id": "urn:person:alice" },
      "dependsOn": [{ "@id": "urn:task:db-456" }],
      "dateModified": "2025-10-24T04:12:00Z"
    },
    {
      "@id": "urn:task:db-456",
      "@type": "Task",
      "name": "Setup database",
      "taskStatus": "Blocked",
      "assignee": { "@id": "urn:person:bob" }
    }
  ]
}

2) A query language for exploring relationships

A simple query language that traverses relationships and filters results: 

FIND ?t
WHERE
  ?t a Task ;
     dependsOn* ?b .
  ?b taskStatus != "Done" .
FILTER (?t = urn:task:auth-123)

3) CLI for humans

A CLI that handles the tedious parts: 

code-hq init
code-hq create task "Fix auth bug" --priority high --assignee trent
code-hq tasks --status blocked
code-hq people --role developer
code-hq show --view kanban

4) Generated views

Generate human-readable views from the structured data: 

# Tasks (Generated)

## In Progress
- Fix authentication bug (@trent, high)

## Blocked
- Setup database (@trent)

Humans use Markdown. Agents get structured data. Both stay synchronized through the CLI.

Migration

# Parse TODO.md → tasks with inferred priority/assignee/dependencies
code-hq import todo ./TODO.md

# Import GitHub issues (PLACEHOLDER: add repo)
code-hq import github --repo org/repo

# Keep files in sync (graph → Markdown views)
code-hq render --views kanban,timeline

Trade-offs

  • Authoring cost → CLI verbs (create, link, set) and smart importers make structured data feel natural
  • Schema drift → JSON-LD contexts with validation on write
  • Review friction → Small, machine-stable diffs in .code-hq/
  • Team adoption → Humans keep Markdown, agents get structure
  • VSCode only → Visualization layer depends on VSCode extension for now (web client coming soon): code-hq-vscode

Getting started

# Start with a simple graph
code-hq init

# Add a few tasks with relationships
code-hq create task "Test semantic workflows" --priority medium

# Query to understand the current state
code-hq query 'FIND ?t WHERE ?t a Task ; priority "high"'

# See it from a human perspective
code-hq show --view kanban

Architecture

┌─────────────────────────┐
│  CLI (Human Interface)  │  Simple commands that update understanding
└────────────┬────────────┘
             │
┌────────────▼────────────┐
│  Semantic Graph Layer   │  JSON-LD with clear relationships
└────────────┬────────────┘
             │
┌────────────▼────────────┐
│     Query Engine        │  TQL for exploring connections
└────────────┬────────────┘
             │
┌────────────▼────────────┐
│     Agent Workflows     │  Standup summaries, PR reviews, planning
└─────────────────────────┘

IDE Integration

Cursor

Add to .cursorrules: 

This project uses code-hq for task management.
Reference .code-hq/prompts/task-management.md for commands.
Always check existing tasks before creating duplicates.
Update task status when starting/finishing work.

Windsurf

Create .windsurf/workflows/codehq.md: 

---
description: code-hq commands reference
---
Read `.code-hq/prompts/_index.md` for overview.
See `.code-hq/prompts/task-management.md` for details.

Claude Code

Automatically sees .code-hq/prompts/ as context.
Ask: “How do I manage tasks in this project?”

What’s next

code-hq solves developer workflows. The next step is specialized AI agents for marketing, finance, and ops, all sharing the same knowledge graph. One source of truth for the entire company.

CodeHQ: The CLI

Source Code: https://github.com/trentbrew/code-hq
NPM Package: https://www.npmjs.com/package/code-hq

CodeHQ: The VSCode Extension

https://open-vsx.org/extension/codehq/codehq-vscode

TQL: The Query Language

Source Code: https://github.com/trentbrew/TQL

JSON-LD: JSON For Linked Data

Docs: https://json-ld.org/

Similar Posts