DEV Community: Trent Brew

What I Learned Building a Knowledge Graph for AI Agents

Trent Brew — Fri, 07 Nov 2025 22:51:04 +0000

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/

I didn't like React so I made it more like Svelte

Trent Brew — Sat, 07 Jun 2025 21:29:21 +0000

As a Vue developer, learning React initially felt like a step backward. The boilerplate, the dependency arrays, the constant battle with the compiler—it all seemed unnecessarily complex. Vue's intuitive reactivity system just clicked with my mental model of how code should work. And when I discovered Svelte, with its elegant runes system, I found something even better.

But here's the thing: React isn't going anywhere. It's become the de facto standard for frontend development, backed by Meta and boasting the largest ecosystem of tools, libraries, and job opportunities. Theo explains this dynamic well in his video:

While I've grown more comfortable with React's patterns, I still find myself longing for Svelte's simplicity. There's something beautiful about how Svelte lets you write exactly what you mean, while React often feels like you're negotiating with the framework about your intentions.

So I did what any stubborn developer would do: instead of switching frameworks, I decided to bring Svelte's elegance to React. This is that experiment.

Svelte 5-Inspired Reactivity for Next.js Apps

Traditional React state management often involves hooks like useState and useEffect, leading to explicit dependency arrays and sometimes verbose code. While powerful, this can obscure the flow of reactivity and lead to subtle bugs if dependencies are missed.

React Runes aims to simplify this by introducing a "runes" system—familiar to Svelte developers—that provides:

Simplicity: A minimal API surface that's easy to grasp.
Ergonomics: Reactive values in your components with a single, intuitive $ hook.
Performance: Built on fine-grained reactivity principles, reducing unnecessary re-renders.
Clarity: Makes it explicit which values in your components are reactive.

How It Works: The Core Runes

React Runes provides three fundamental primitives: state, derived, and effect, along with a powerful $ hook.

state(initial): Creates a reactive state variable. When its value changes, anything depending on it automatically updates.
derived(fn): Defines a computed value. This function automatically re-runs whenever any of its dependencies (other runes) change, and its value is then updated.
effect(fn): Executes a side effect. The effect function runs whenever its dependencies change, and it can optionally return a cleanup function.

And then, there's the star of the show for React components:

$(rune) (The $ Hook): This Svelte-inspired hook is how you consume reactive runes directly within your React components. When you wrap a state or derived rune with $(...), your component automatically subscribes to its value and re-renders only when that specific rune's value changes.

Here’s a quick example:

import { state, derived, effect, $ } from 'react-runes'

const count = state(0)
const doubleCount = derived(() => count.value * 2)

effect(() => {
  console.log('Count changed:', count.value)
})

export default function Counter() {
  const countValue = $(count)
  const doubleValue = $(doubleCount)

  return (
    <div>
      <p>Count: {countValue}</p>
      <p>Double: {doubleValue}</p>
      <button onClick={() => (count.value += 1)}>Increment</button>
    </div>
  )
}

Notice how count.value and doubleCount.value are directly accessed within the derived and effect, and how $(count) and $(doubleCount) keep the Counter component reactive without explicit useState or useEffect calls for subscription.

Under the Hood

React Runes leverages zustand for its global state management. This allows for an efficient, centralized system to track all runes, manage their dependencies, and batch updates for optimal performance. When a state rune is updated, the system intelligently identifies and re-runs only the derived and effect runes that depend on it, propagating changes efficiently.

Vertical Slice Architecture

One of the philosophies behind React Runes is to encourage a "vertical slice" architecture. This means co-locating your component's UI, its reactive state (runes), and related logic within the same directory. This enhances discoverability and makes features more self-contained.

Limitations and Future

It's important to reiterate that React Runes is an experiment and not intended for production use. It pushes the boundaries of React ergonomics and explores alternative reactivity patterns. As such, some React tooling (like linting or auto-imports) may not fully recognize $ as a conventional hook.

This project is a playground for reactivity ideas within the React ecosystem. I invite you to explore the codebase, try it out, and share your feedback. Contributions, ideas, and discussions are always welcome.

Source Code: https://github.com/trentbrew/react-runes
NPM Package: https://www.npmjs.com/package/react-runes

Deploy PocketBase in 30 Seconds

Trent Brew — Mon, 20 Mar 2023 00:42:44 +0000

Just wanted to share this amazing tool called pockethost.io. It allows you to get your PocketBase instance up & running quickly without having to fiddle with Docker or provision your server. You just pick a unique name for your app and you're good to go with the click of a button 🚀

Big shout out to Ben, Oscar, Lucas, and Zach 💙

GitHub: github.com/pockethost

Using Notion as a Headless CMS with Nuxt

Trent Brew — Fri, 06 Jan 2023 20:58:38 +0000

Notion has become increasingly popular as a versatile tool for everything from taking notes to managing projects, and when combined with it's API we're able to automate workflows, create custom apps, and even use Notion as a headless CMS for websites and blogs.

With the help of tools like Nuxt, we can easily create dynamic websites and blogs that are powered by Notion. In this tutorial, we will explore how to use Notion as a headless CMS with Nuxt 3. We will cover setting up the Notion API, creating a database of images in Notion, and building a simple website that displays our content.

By the end of this tutorial, you should have a good understanding of how to use Notion as a headless CMS with Nuxt 3.

Step 1: Project Setup

Create a new Nuxt project and install dependencies:

npx nuxi init notion-cms -y && cd notion-cms && npm install

Run locally:

npm run dev

From here, we can begin configuring notion.

Step 2: Create Notion Database

Create a new Notion page. This page will house our image database:

Add an inline database called 'Images' using the gallery layout:

Next, we'll create a 'Files & media' property to upload an image:

We can set the gallery preview thumbnail to display the uploaded file:

Let's upload a few more for good measure:

Our database it looking great! However, we need to hook up the database to an integration before we can access it from the API.

Step 3: Create a new Notion Integration

Visit notion.so/my-integrations to create a new integration.

Once it's created, an 'Internal Integration Token' will be generated:

We'll need this token later on to access the database from the client, so we can copy and paste it somewhere secure for now.

I've named my integration 'CMS' with a custom thumbnail:

Set integration type as 'internal':

Since we only want to fetch images and not update or delete anything from the client, we'll just check 'Read Content':

Step 4: Connect Integration to Database

Head back to the database page we created in Step 2.

From here, we can click 'Add connections' where we'll find the 'CMS' integration we created in Step 3:

With that, we're all set on the Notion side. Let's switch gears and jump into the code.

Step 5: Setup Environment Variables

This is where our 'Internal Integration Token' from Step 3 comes in:

In the root of your nuxt project, create a .env file. This file will contain our internal integration token and the ID of the database we created in Step 2.

The ID of the database can be found in the URL:

NOTION_API_KEY should be set as the secret internal integration key.

Your .env file should look something like this:

Step 6: Nuxt Server Setup

Create a new file server/api/gallery.get.js:

The handler in this file will be called when the user hits the endpoint localhost:3000/api/gallery

Let's return the following dummy data to check if it's working:

// gallery.get.js

const test_data = [
  {
    id: 1,
    name: "item1",
  },
  {
    id: 2,
    name: "item2",
  },
  {
    id: 3,
    name: "item3",
  },
];

export default defineEventHandler(() => test_data);

We should be able to see the JSON response in the browser now 🙌🏾

From here, we can install the Notion client and begin making requests.

Step 7: Notion API Client Setup

Install the notion client:

npm install @notionhq/client

Let's pull in the environment variables for authorization and try fetching the database matching the ID in our .env:

// gallery.get.js

import { Client } from "@notionhq/client";

const notion = new Client({ auth: process.env.NOTION_API_KEY });
const image_database_id = process.env.NOTION_DATABASE_ID;

let payload = [];

async function getImages() {
  const data = await notion.databases.query({
    database_id: image_database_id,
  });
  return data;
}

getImages().then((data) => {
  payload = data.results;
});

export default defineEventHandler(() => payload);

Now when we visit localhost:3000/api/gallery, we can see the data returned from our Notion database ＼(￣▽￣)／

We don't need quite so much data though... we only care about the image url in this case, so let's isolate the data we need before sending back to the front-end:

Now we only receive the neccesary data from Notion:

Step 8: Render the Images

Finally, we can fetch the image URLs from the server and render them on the front-end ~ let's add a bit of styling as well:

// app.vue

<script setup>
const state = reactive({
  images: [],
});

const res = await fetch("http://localhost:3000/api/gallery");

res.json().then((images) => {
  console.log(images);
  state.images = images;
});
</script>

<template>
  <main>
    <h1>ヽ(♡‿♡)ノ</h1>
    <div v-for="(image, index) in state.images" :key="index">
      <img :src="image" />
    </div>
  </main>
</template>

<style>
* {
  font-weight: normal;
}
body {
  padding: 0;
  margin: 0;
  font-family: monospace;
  color: white;
}
h1 {
  position: absolute;
  margin-left: auto;
  margin-right: auto;
  top: 64px;
}
img {
  width: 200px;
  height: 200px;
  object-fit: cover;
  border-radius: 8px;
  cursor: pointer;
  transition: 600ms cubic-bezier(0.16, 1, 0.3, 1);
}
img:hover {
  transform: scale(1.1);
  box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.2);
}
main {
  display: flex;
  gap: 36px;
  align-items: center;
  justify-content: center;
  height: 100vh;
  width: 100vw;
  background: linear-gradient(black, #111);
}
</style>

We can now see the images rendered on the front-end:

Conclusion:

Notion is a powerful tool and works surprisingly well as a headless CMS.

My personal website is powered by Notion, and while there are some trade-offs, Notion has become my goto for projects requiring a light weight CMS.

I would love to try some alternatives so please let me know your favorite CMS for small-scale projects!

Full Source Code