DEV Community: Bobby Hall Jr

I Let Grok Bot Apply to Software Engineering Jobs While I Was Sleeping

Bobby Hall Jr — Mon, 31 Aug 2026 02:59:50 +0000

At midnight, I gave Grok Bot a job.

Not a prompt.

A job.

Find software engineering roles that actually fit me, apply to the strongest matches, keep track of everything, and do it again in four hours.

Then I went to sleep.

That’s the part that got me.

For the last few years, we’ve been talking to AI.

Now we’re starting to assign work to it.

And after turning Grok Bot into an autonomous job-search agent, I think that distinction is much more interesting than another benchmark.

The Experiment
Grok Bot Feels Different Because It Has a Computer
I Didn't Tell It "Find Me Jobs"
The Scoring System Is What Makes This Useful
Memory Might Matter More Than the Model
The Scary Part Isn't Intelligence. It's Permissions.
Then I Scheduled It
This Is Bigger Than Grok Bot
My Grok Bot Review
Build an AI Employee for Your Business

The experiment

The idea was slightly unhinged:

Every 4 hours

Find new software engineering jobs
        ↓
Verify they're still open
        ↓
Compare them against my resume
        ↓
Score each opportunity
        ↓
Apply to the strongest matches
        ↓
Record what happened
        ↓
Repeat

Up to 10 applications per run.

But I added one important rule:

10 applications is a maximum, not a quota.

If there are three great jobs, apply to three.

If everything sucks, apply to zero.

I don’t want an AI desperately searching for application #10 and deciding that Senior Principal CUDA Kernel Wizard is probably close enough.

The objective isn't:

MAXIMIZE APPLICATIONS

It's:

MAXIMIZE INTERVIEW PROBABILITY

That completely changes how you design the agent.

Grok Bot feels different because it has a computer

Normally, building this myself would eventually become:

LLM
+
Playwright
+
Postgres
+
Cron
+
Session storage
+
Authentication
+
Retries
+
Monitoring
+
A weekend I'll never get back

Grok Bot removes a lot of that infrastructure.

It has an environment where the Bot can operate software, retain context, reuse skills, and run routines on a schedule. xAI defines a skill as reusable instructions for performing a task and a routine as the thing that tells a Bot when to run that workflow.

That means the interesting engineering problem becomes:

How do I define the job well enough for the agent to own it?

That's a very different problem.

I didn't tell it "find me jobs"

This was probably the biggest lesson.

A weak instruction looks like:

Find 10 AI engineering jobs
and apply to them.

That's not autonomy.

That's a spam cannon.

The actual prompt I used was much closer to an operating policy.

I've removed personal details and shortened it, but the important parts looked like this:

You are my autonomous job-search and application agent.

Your goal is to find high-quality jobs matching my resume
and submit applications to strong matches.

Do not merely recommend jobs.

Use the attached resume as the source of truth.
Never fabricate experience, qualifications, employers,
education, dates, accomplishments, or technical skills.

TARGET

Prioritize roles such as:

- AI/ML Engineer
- Applied AI Engineer
- LLM Engineer
- Agentic AI Engineer
- AI Product Engineer
- Machine Learning Engineer
- Full-Stack AI Engineer
- Backend Engineer working on AI infrastructure

Prefer recently posted opportunities.

For every job:

1. Confirm the role is still open.
2. Compare the requirements against my resume.
3. Check location and compensation.
4. Evaluate technical and experience alignment.
5. Score the job from 0-100.
6. Automatically apply to strong matches.
7. Save borderline matches for review.
8. Skip weak matches.

Never apply just to hit the application target.

Avoid duplicate applications.

Do not apply to more than a small number
of roles at the same company.

GUARDRAILS

Automatically answer ordinary questions only when
the answer is already known.

Pause for:

- uncertain information
- legal questions
- assessments
- references
- sensitive identity information
- financial information
- authentication or verification
- anything requiring information you cannot verify

Never invent an answer.

VERIFICATION

Do not mark an application as submitted until
you reach a real confirmation.

Track:

Company
Role
Match score
Application status
Confirmation
Notes
Recommended follow-up

Look at what that actually defines:

Goal
+
Context
+
Search strategy
+
Evaluation
+
Decision thresholds
+
Execution
+
Memory
+
Verification
+
Escalation
+
Guardrails

That's not really a prompt anymore.

It's closer to an agent specification.

And I think that's where prompting is heading.

We're moving from prompt engineering toward responsibility engineering.

The scoring system is what makes this useful

Finding jobs isn't difficult.

LinkedIn can find jobs.

Indeed can find jobs.

Google can find jobs.

The interesting question is:

Should I actually apply to this one?

So I made Grok evaluate every opportunity before acting.

My actual weighting was roughly:

Technical alignment           35
Relevant AI/ML work           25
Experience level              15
Location / work arrangement   10
Compensation / company        10
Mission / product              5
                              ──
                             100

Then:

75–100  → Strong enough to apply
65–74   → Save as secondary
<65     → Skip

Now the agent might discover 50 jobs and end up with:

50 discovered
↓
24 clearly irrelevant
↓
16 reasonable
↓
7 strong
↓
Apply to 7

That's success.

An autonomous agent without judgment is just a faster way to make bad decisions.

Memory might matter more than the model

Without state, four hours later the agent wakes up and goes:

Wow, this role at Stripe looks great.

Four hours later:

Wow, this role at Stripe looks great.

Four hours later:

Have I told you how passionate I am about Stripe?

Not ideal.

So the agent needs an application ledger.

Company
Role
Posting
Score
Date discovered
Date applied
Status
Confirmation
Notes
Follow-up

Before every application:

Have we already seen this?

Have we already applied?

Is this the same role under another URL?

Did a previous attempt fail?

If yes:

SKIP

This stuff is boring.

It's also the stuff that makes autonomous systems useful.

State.

Idempotency.

Verification.

Retries.

Audit trails.

Everyone wants to talk about how intelligent the model is.

I increasingly care about whether the system around the model is dependable.

The scary part isn't intelligence. It's permissions.

I'm perfectly comfortable letting an AI:

search for jobs
read job descriptions
rank opportunities
tailor an introduction
fill ordinary fields
track applications

Then the form asks:

Do you have a security clearance?

Have you signed a non-compete?

Provide your Social Security number.

Complete this recorded interview.

Please electronically sign here.

Nope.

My boundary is basically:

KNOWN + LOW RISK
        ↓
      HANDLE

UNCERTAIN
        ↓
       ASK

SENSITIVE
        ↓
       STOP

That's what good autonomy should look like.

Not:

Never bother me.

But:

Only bother me when human judgment is actually required.

xAI's own guidance for Grok Bot routines emphasizes approval boundaries, idempotent retries, reporting partial completion, and automating preparation before higher-impact execution.

That's the right direction.

Then I scheduled it

Once the workflow works, the last step is almost boring.

Every 4 hours:

Search.

Verify.

Evaluate.

Score.

Apply.

Record.

Escalate when needed.

And now something changes.

I'm not waking up every morning and typing:

Find me some new AI engineering jobs.

Instead:

12 AM → work
4 AM  → work
8 AM  → work
12 PM → work

The responsibility exists independently of the prompt.

That's the part I keep thinking about.

This is bigger than Grok Bot

Grok Bot isn't happening in isolation.

We're seeing the same pattern emerge across the industry.

ChatGPT Work can take a goal, operate across apps and files, stay with longer projects, produce finished work, and keep workflows moving through scheduled tasks.

Codex is pushing the same model into software engineering: give an agent a repository and a goal, let it build, refactor, test, review, and even take on scheduled background engineering work.

OpenAI is even introducing workspace agents designed around repeatable workflows that can run on schedules and act across tools with explicit permissions and approval checkpoints.

Different products.

Same direction.

OLD SOFTWARE

Human
 ↓
Instruction
 ↓
Software
 ↓
Result

is becoming:

AGENTIC SOFTWARE

Responsibility
+
Context
+
Memory
+
Tools
+
Schedule
+
Guardrails

        ↓

Continuous work

And that's a much bigger shift than "chatbots got smarter."

My Grok Bot review

Would I let Grok Bot blindly submit 60 job applications every day?

Absolutely not.

That's a fantastic way to become the first person automatically rejected by every startup in America before breakfast.

But would I let it continuously:

discover opportunities
eliminate bad matches
rank good ones
prepare applications
handle safe actions
verify submissions
remember everything
bring me the edge cases

Yes.

That's useful.

Really useful.

And the job-search experiment is almost beside the point.

The same architecture works for:

Sales prospecting

Lead qualification

Recruiting

Customer follow-up

Competitive research

Operations

Support

QA

Engineering maintenance

The pattern keeps showing up:

Context
+
Memory
+
Tools
+
A lane of responsibility
+
A schedule
+
Guardrails

We've spent years asking:

How smart can AI get?

I'm becoming more interested in another question:

How much responsibility can we safely give it?

Because once software can understand a goal, remember what happened, use tools, make bounded decisions, wake up on its own, and know when to ask for help...

We're not really talking about chatbots anymore.

We're talking about workers made of software.

Build an AI employee for your business

That's exactly the idea behind Roster.

Instead of wiring together models, memory, tools, schedules, and guardrails yourself, Roster is built around giving an AI employee a real lane of responsibility and letting it handle recurring work while bringing you the decisions that actually need a human.

If you have work in your business that happens again and again, try handing it to an AI employee.

Try Roster → get-roster.com

Your Code Knows What Changed. But Does It Know Why?

Bobby Hall Jr — Sun, 30 Aug 2026 13:38:31 +0000

AI can write a pull request in seconds.

But when that pull request touches a piece of code written three years ago, there is a much harder question:

Why does this code exist?

That answer might be buried across 47 commits, 12 pull requests, an old incident, a Slack conversation nobody remembers, and one engineer who left the company six months ago.

This is becoming one of the biggest problems in AI-assisted software engineering.

Because writing code is getting cheaper. Understanding code is not.

The Codebase Is Not the Whole System

Consider this:

if (user.isLegacy && !featureEnabled) {
  return fallback();
}

Looks suspicious.

Maybe it's dead code.

Maybe someone forgot to clean it up.

So an AI coding agent suggests:

- if (user.isLegacy && !featureEnabled) {
-   return fallback();
- }

The tests pass.

The PR looks clean.

You merge it.

Three hours later, production breaks for a subset of customers.

Now you're asking a very different question:

Who knew why that code was there?

The answer might have been hiding in the engineering history.

Git Knows What Changed

Git is incredible.

It can tell you:

What changed?
Who changed it?
When did they change it?

But those aren't always the questions engineers need answered.

We need:

Why did it change?

What problem was it solving?

What depends on it?

What happens if I change it?

Has this failed before?

Who understands this part of the system?

Was this introduced because of an incident?

What happened the last time someone touched it?

The problem isn't that this information doesn't exist.

It does.

It's just fragmented.

The Hidden Knowledge Graph Inside Every Codebase

Every engineering organization already has a graph.

They just don't usually call it one.

A pull request is connected to commits.

Commits are connected to files.

Files are connected to services.

Services are connected to deployments.

Deployments are connected to incidents.

Incidents are connected to fixes.

Fixes are connected to engineers.

Engineers are connected to decisions.

Decisions are connected to outcomes.

Like this:

                    ┌────────────┐
                    │   Issue    │
                    └─────┬──────┘
                          │
                       solved by
                          │
                          ▼
                    ┌────────────┐
                    │     PR     │
                    └─────┬──────┘
                          │
                       modified
                          │
                          ▼
                    ┌────────────┐
                    │    Code    │
                    └─────┬──────┘
                          │
                      depends on
                          │
                          ▼
                    ┌────────────┐
                    │  Service   │
                    └─────┬──────┘
                          │
                      affected
                          │
                          ▼
                    ┌────────────┐
                    │  Incident  │
                    └─────┬──────┘
                          │
                       caused
                          │
                          ▼
                    ┌────────────┐
                    │    Fix     │
                    └────────────┘

The valuable information isn't just the nodes.

It's the edges.

Why Relationships Matter

Suppose you're looking at:

checkout.ts

A traditional code search might tell you:

checkout.ts
├── imported by payment.ts
├── imported by cart.ts
└── imported by order.ts

Useful.

But an Engineering Graph could tell you:

checkout.ts
│
├── modified by PR #842
│     ├── solved issue #421
│     ├── reviewed by Maya
│     └── followed incident #91
│
├── depends on retry.ts
│     └── introduced after checkout timeout
│
├── affects payment-service
│
└── changed 7 times during payment incidents

Now you aren't just looking at code.

You're looking at the story of the code.

And that story can change the decision you make.

Give AI the Story, Not Just the Source File

This is where things get interesting.

Imagine asking an AI agent:

"Can I remove this retry?"

With only the source code, it might respond:

"The retry appears redundant and could potentially be removed."

That's not useful.

Now give it the engineering context:

retry.ts
   ↓
used by checkout.ts
   ↓
introduced in PR #842
   ↓
PR linked to checkout timeout #421
   ↓
incident #91 involved the same request path
   ↓
three subsequent PRs modified retry behavior

Now the answer could be:

"I would not remove it yet. This retry mechanism was introduced to address a checkout timeout and has been modified several times after production issues. I'd inspect incident #91 and the related PRs before changing it."

Same model.

Different context.

Better context → better reasoning.

That's the fundamental idea.

Let's Build One

You don't need a giant infrastructure project to understand the architecture.

Start with a tiny graph.

type NodeType =
  | "file"
  | "commit"
  | "pull_request"
  | "issue"
  | "service"
  | "incident"
  | "person";

type Relationship =
  | "MODIFIED"
  | "SOLVED"
  | "DEPENDS_ON"
  | "AUTHORED_BY"
  | "REVIEWED_BY"
  | "AFFECTED"
  | "CAUSED";

Our nodes:

type Node = {
  id: string;
  type: NodeType;
  name: string;
  metadata?: Record<string, unknown>;
};

And edges:

type Edge = {
  from: string;
  to: string;
  relationship: Relationship;
  metadata?: Record<string, unknown>;
};

Now we can represent:

const edges: Edge[] = [
  {
    from: "pr:842",
    to: "file:checkout.ts",
    relationship: "MODIFIED",
  },
  {
    from: "pr:842",
    to: "issue:421",
    relationship: "SOLVED",
  },
  {
    from: "file:checkout.ts",
    to: "file:retry.ts",
    relationship: "DEPENDS_ON",
  },
  {
    from: "incident:91",
    to: "service:checkout",
    relationship: "AFFECTED",
  },
];

That's already enough to start answering questions that plain text search struggles with.

The Agent Should Query the Graph Before It Acts

Now put an AI agent on top.

A traditional agent looks something like:

Goal
 ↓
Observe
 ↓
Decide
 ↓
Act
 ↓
Check
 ↓
Repeat

Useful.

But it starts every task with roughly the same level of ignorance.

Give it the graph:

                    ┌──────────────────────┐
                    │        Goal          │
                    └──────────┬───────────┘
                               ↓
                    ┌──────────────────────┐
                    │    Query Graph       │
                    └──────────┬───────────┘
                               ↓
                    ┌──────────────────────┐
                    │      Observe         │
                    └──────────┬───────────┘
                               ↓
                    ┌──────────────────────┐
                    │       Decide         │
                    └──────────┬───────────┘
                               ↓
                    ┌──────────────────────┐
                    │       Execute        │
                    └──────────┬───────────┘
                               ↓
                    ┌──────────────────────┐
                    │       Verify         │
                    └──────────┬───────────┘
                               ↓
                    ┌──────────────────────┐
                    │    Update Graph      │
                    └──────────┬───────────┘
                               │
                               └──────→ Next task

Now the agent doesn't just observe the repository.

It observes what happened before.

The Agent Can Learn Without Retraining

This distinction is easy to miss.

We normally think an AI system improves like this:

Better model
     ↓
More training
     ↓
Better weights
     ↓
Better performance

But agents have another path:

Better experience
       ↓
Better graph
       ↓
Better context
       ↓
Better decisions
       ↓
Better experience

The underlying model doesn't have to change.

The environment around the model improves.

That's powerful.

But There's a Catch

We shouldn't blindly turn agent activity into permanent knowledge.

Imagine an agent tries:

Increase retry count: 2 → 10

The test passes.

The agent records:

"10 retries fixes checkout."

Next week another agent sees that "knowledge" and does the same thing.

Now you've created a feedback loop that makes the system confidently worse.

That's why learning systems need evidence.

Knowledge Needs Evidence

Instead of:

Agent says it worked.

Store:

Code changed
    ↓
Unit tests passed
    ↓
Integration tests passed
    ↓
PR merged
    ↓
Deployment succeeded
    ↓
No incident followed

Now your graph can represent:

type Outcome = {
  status: "success" | "failure";
  confidence: number;
  evidence: string[];
};

For example:

const outcome: Outcome = {
  status: "success",
  confidence: 0.92,
  evidence: [
    "unit tests passed",
    "integration tests passed",
    "pull request merged",
    "deployment succeeded",
  ],
};

The system isn't just remembering.

It's remembering why it believes something.

That difference becomes enormous at scale.

Not Everything Is Knowledge

An agent might make 50 observations while solving one problem.

We shouldn't permanently promote all 50 into "truth."

There are levels:

Observation
     ↓
Evidence
     ↓
Repeated pattern
     ↓
Validated relationship
     ↓
Reusable knowledge
     ↓
Heuristic

For example:

Observation

checkout.ts imports retry.ts

Event

PR #842 modified checkout.ts

Outcome

Tests passed after the change.

Knowledge

checkout.ts frequently changes with retry.ts.

Heuristic

When checkout timeout tests fail,
inspect retry behavior first.

That's a much safer learning architecture than dumping every agent thought into a vector database.

And Failure Is Data Too

This might be the most underrated part.

Suppose an agent tries two approaches:

Task: Fix checkout timeout

Approach A
    ↓
FAILED

Approach B
    ↓
SUCCEEDED

A normal system might only remember B.

A learning system should remember both.

Task
│
├── attempted → Approach A
│                 └── FAILED
│
└── attempted → Approach B
                  └── SUCCEEDED

That's negative knowledge.

The next agent doesn't have to walk into the same wall.

It can know:

"This approach was already tried. It failed."

The graph remembers the dead ends.

This Isn't RAG

RAG is incredibly useful.

But RAG and an Engineering Graph solve different problems.

RAG asks:

What information is relevant to this question?

A graph can ask:

How are these things related?

Imagine asking:

Why is checkout.ts high risk?

A document retriever might find:

PR #842
PR #811
PR #743

A graph can reconstruct:

checkout.ts
│
├── modified by PR #842
│      ├── authored by Maya
│      └── reviewed by Bobby
│
├── related to retry.ts
│
├── affected checkout-service
│
└── connected to incident #91
       └── caused by previous checkout change

That's not just retrieval.

That's contextual reasoning over relationships.

And the two technologies work beautifully together:

                 User Question
                       ↓
              ┌────────────────┐
              │  Semantic Search│
              └───────┬────────┘
                      ↓
              Relevant entities
                      ↓
              ┌────────────────┐
              │ Graph Traversal│
              └───────┬────────┘
                      ↓
               Relationships
                      ↓
              ┌────────────────┐
              │      LLM       │
              └───────┬────────┘
                      ↓
             Evidence-backed answer

Now Scale It Beyond One Repository

This is where the idea gets really interesting.

Imagine your engineering graph continuously absorbs:

GitHub
   ↓
Commits
   ↓
Pull Requests
   ↓
Code
   ↓
Services
   ↓
Deployments
   ↓
Incidents
   ↓
Fixes
   ↓
Agent Experiences

Then add:

Jira
Slack
Confluence
Datadog
Architecture decisions
Human feedback

Eventually you're not building another code search engine.

You're building a living model of how the engineering organization works.

You can ask:

Why was this architecture chosen?

Who understands this service?

What usually breaks when we change it?

Which files are high risk?

What has already been tried?

Which engineers solved similar problems?

What happened after the last deployment?

What should an AI agent inspect before touching this service?

Those answers don't exist in any single system.

They emerge from the connections between systems.

The Real Opportunity

Here's the part I think matters most.

AI is making software creation dramatically faster.

That's great.

But it creates a new bottleneck:

understanding.

If AI can generate 10x more code, we need tools that help engineers understand 10x more software.

Otherwise we're just accelerating the production of systems nobody fully understands.

The next generation of engineering tools won't just answer:

"What does this code do?"

They'll answer:

"Why is it here, what does it connect to, what happened before, and what happens if I change it?"

That's a much harder problem.

And a much more valuable one.

The Four-Layer Architecture

I think the architecture eventually becomes surprisingly simple:

┌─────────────────────────────────────┐
│               AGENTS                │
│        Reason • Plan • Act          │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│              CONTEXT                │
│       Search • Retrieval • RAG       │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│        ENGINEERING GRAPH             │
│ Code • PRs • People • Incidents     │
│ Decisions • Dependencies • Outcomes │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│              EVIDENCE               │
│     GitHub • CI • Deployments       │
│      Observability • Humans         │
└─────────────────────────────────────┘

The model provides reasoning.

The tools provide action.

The graph provides memory.

Evidence provides trust.

Put those together and you get something much more interesting than an AI coding assistant.

You get an engineering system that can learn from the work it performs.

Software Should Explain Itself

The future of AI-assisted engineering isn't just about generating code faster.

It's about building systems that understand the software they're changing.

Every commit tells a story.

Every pull request adds context.

Every incident teaches something.

Every fix creates new knowledge.

Every engineer leaves behind experience.

The opportunity is to connect all of it.

Because your code already knows what changed.

Your Git history knows when.

Your team knows why.

The problem is that nobody has connected the three.

That's what Engineering Intelligence should do.

And that's what we're building with Helix: a living engineering graph that connects software, engineering activity, decisions, and evidence so humans and AI can understand what happened before deciding what happens next.

The goal isn't AI that confidently guesses.

The goal is AI that can show its work.

Your code has a history. Helix makes it understandable.

Connect your GitHub and see what your code knows.

Explore Helix →

How to Build an AI Employee With a Knowledge Graph (Not Just Another Agent)

Bobby Hall Jr — Fri, 28 Aug 2026 03:12:27 +0000

An AI agent can take an action. An AI employee needs to know what happens next.

Most AI agents look something like this:

Think → Act → Observe → Repeat

That's fine for short-lived tasks.

But an AI employee needs to work across hours, days, and weeks.

It needs to remember:

What happened
Who owns the work
What is waiting
What changed
What should happen next
When it should wake up
When a human needs to approve something

That's where graph engineering becomes interesting.

This is the architecture behind

Roster:
software that can own work the way an employee does, not just fire off a single tool call.

Events wake someone up. A graph holds state, ownership, and history.

The agent reasons, acts, writes the result back, then sleeps until the next event.

For Roster, the loop looks like this:

Event
  ↓
Graph
  ↓
Agent
  ↓
Action
  ↓
Graph Update
  ↓
Sleep
  ↓
Wake Again

Let's build a tiny version.

1. Model the Work
2. Build the Graph
3. Add Events
4. Build the Agent Loop
5. Add Scheduling
6. Build a Tiny AI Employee
7. Put It Together
8. The Bigger Idea

1. Model the Work

Imagine an AI employee called Maya.

Her job is simple:

Follow up with sales leads.

Her world contains:

Maya
  ↓ owns
Lead
  ↓ belongs_to
Company
  ↓ contacted
Email
  ↓ replied_to
Customer

We don't need a massive graph database.

We just need nodes and relationships.

2. Build the Graph

Here's a minimal TypeScript graph:

type Node = {
  id: string;
  type: string;
  data: Record<string, unknown>;
};

type Edge = {
  from: string;
  to: string;
  type: string;
};

class Graph {
  nodes = new Map<string, Node>();
  edges: Edge[] = [];

  addNode(node: Node) {
    this.nodes.set(node.id, node);
  }

  connect(from: string, type: string, to: string) {
    this.edges.push({ from, type, to });
  }

  neighbors(id: string) {
    return this.edges
      .filter((edge) => edge.from === id)
      .map((edge) => ({
        relationship: edge.type,
        node: this.nodes.get(edge.to),
      }));
  }
}

Now create Maya and a lead:

const graph = new Graph();

graph.addNode({
  id: "maya",
  type: "employee",
  data: {
    name: "Maya",
    role: "sales",
  },
});

graph.addNode({
  id: "lead-123",
  type: "lead",
  data: {
    company: "Acme",
    status: "qualified",
  },
});

graph.connect("maya", "owns", "lead-123");

Our graph now knows:

Maya ──owns──→ Lead #123

That's already more useful than two disconnected database records.

3. Add Events

Employees shouldn't constantly run.

Something should wake them up.

For example, Sarah replies to an email:

const event = {
  id: "event-1",
  type: "email.replied",
  data: {
    leadId: "lead-123",
    message: "Sounds interesting. Follow up next Tuesday.",
  },
};

Now we can find the employee responsible for that lead:

function findOwner(event: typeof event) {
  const leadId = event.data.leadId;
  return graph.edges.find(
    (edge) => edge.to === leadId && edge.type === "owns"
  )?.from;
}

const employeeId = findOwner(event);
console.log(employeeId);
// maya

We just answered:

Who should wake up?

The flow becomes:

Email Reply
    ↓
Event
    ↓
Find Lead
    ↓
Find Owner
    ↓
Wake Maya

4. Build the Agent Loop

Now we give Maya an actual agent loop.

async function runEmployee(employeeId: string, event: any) {
  const employee = graph.nodes.get(employeeId);
  const context = {
    employee,
    event,
    relationships: graph.neighbors(employeeId),
  };

  const decision = await agent(context);
  const result = await execute(decision);

  recordResult(employeeId, decision, result);
}

The important part is the sequence:

Wake
 ↓
Read Graph
 ↓
Reason
 ↓
Act
 ↓
Record

The graph gives the agent persistent context.

5. Add Scheduling

Now imagine Sarah says:

Follow up with me next Tuesday.

Maya shouldn't stay running until Tuesday.

She schedules a future event.

type Job = {
  employeeId: string;
  runAt: Date;
  event: any;
};

const jobs: Job[] = [];

function schedule(job: Job) {
  jobs.push(job);
}

Maya can schedule her next action:

schedule({
  employeeId: "maya",
  runAt: new Date("2026-09-01T09:00:00Z"),
  event: {
    id: "followup-1",
    type: "followup.due",
    data: {
      leadId: "lead-123",
    },
  },
});

Then Maya sleeps.

When the time arrives:

async function processJobs() {
  const now = new Date();
  for (const job of jobs) {
    if (job.runAt <= now) {
      await runEmployee(job.employeeId, job.event);
    }
  }
}

Now we have two ways to wake an employee:

Customer Reply ──────┐
                     │
Approval Granted ────┼──→ Wake Employee
                     │
Schedule Due ────────┘

6. Build a Tiny AI Employee

Now let's connect an LLM.

The agent gets the relevant graph context and decides what to do.

async function agent(context: any) {
  const prompt = `
You are Maya, a sales employee.
Your job is to follow up with leads.

Event:
${JSON.stringify(context.event)}

Graph:
${JSON.stringify(context.relationships)}

Decide the next action.
Return JSON:
{
  "action": "...",
  "reason": "...",
  "runAt": "..."
}
`;

  return llm.generateObject(prompt);
}

For Sarah's message, Maya might return:

{
  "action": "schedule_followup",
  "reason": "Sarah requested a follow-up next Tuesday.",
  "runAt": "2026-09-01T09:00:00Z"
}

Then we execute it:

async function execute(decision: any) {
  switch (decision.action) {
    case "schedule_followup":
      schedule({
        employeeId: "maya",
        runAt: new Date(decision.runAt),
        event: {
          id: crypto.randomUUID(),
          type: "followup.due",
          data: decision,
        },
      });
      return {
        success: true,
      };
    case "send_email":
      return sendEmail(decision);
    default:
      throw new Error(`Unknown action: ${decision.action}`);
  }
}

Finally, record what happened:

function recordResult(employeeId: string, decision: any, result: any) {
  graph.addNode({
    id: crypto.randomUUID(),
    type: "agent_action",
    data: {
      employeeId,
      decision,
      result,
      createdAt: new Date(),
    },
  });
}

Now the employee has memory.

Not necessarily memory as a giant conversation transcript.

Memory as state and relationships.

7. Put It Together

Let's walk through the entire workflow.

Sarah replies:

Sounds interesting. Follow up next Tuesday.

Email arrives

Gmail
  ↓
email.replied

Roster finds the relevant lead

Email
  ↓
related_to
  ↓
Lead #123

Roster finds the owner

Lead #123
  ↓
owned_by
  ↓
Maya

Maya wakes up

Maya
  ↓
Read Graph
  ↓
Understand Context

Maya reasons

Sarah wants a follow-up next Tuesday.

Maya schedules it

Task
  ↓
scheduled_for
  ↓
Tuesday 9:00 AM

Maya sleeps 💤
Tuesday arrives

Scheduler
  ↓
followup.due
  ↓
Wake Maya

Maya reads the graph

Maya
  ↓
Lead #123
  ↓
Sarah
  ↓
Previous Conversation

Maya sends the email

Maya
  ↓
send_email()
  ↓
Sarah

Graph updates

Task #123
status = completed

Email #43
status = sent

Lead #123
last_contacted = today

Then:

Maya
  ↓
Sleep

That's a tiny AI employee.

8. The Bigger Idea

The architecture is surprisingly simple:

                   ┌─────────────┐
                   │    Events   │
                   └──────┬──────┘
                          ↓
                   ┌─────────────┐
                   │    Graph    │
                   │             │
                   │ State       │
                   │ Relations   │
                   │ History     │
                   └──────┬──────┘
                          ↓
                   ┌─────────────┐
                   │ AI Employee │
                   └──────┬──────┘
                          ↓
                  ┌───────┴───────┐
                  ↓               ↓
                Tools         Scheduler
                  │               │
                  └───────┬───────┘
                          ↓
                        Events
                          │
                          └────→ Graph

The important part is the final arrow:

Agent
  ↓
Action
  ↓
Event
  ↓
Graph
  ↓
Next Decision

The agent changes the world.

The graph records the change.

The next time the employee wakes up, it doesn't start over.

It continues.

The Takeaway

I think the future of AI employees looks less like:

Prompt → LLM → Tool

and more like:

World
  ↓
Graph
  ↓
Agent
  ↓
Action
  ↓
Event
  ↓
Graph

The LLM provides reasoning.

The tools provide capabilities.

The scheduler provides time.

Events provide wake-ups.

The graph provides continuity.

That's the interesting part.

We're not just building agents that can do things.

We're building software that can own work.

That's what Roster is for.

Try Roster

If the same follow-ups, handoffs, and waiting loops keep eating your week, give them to an AI employee.

Try Roster →

The Graph That Learns: Building Self-Improving Agent Loops

Bobby Hall Jr — Wed, 26 Aug 2026 13:35:44 +0000

AI agents are getting very good at doing things.

They can read a ticket, modify code, open a pull request, query an API, send an email, and keep going until a goal is reached.

But there is a problem hiding underneath all of this:

Most agents don't actually get smarter from doing the work.

They execute a loop, finish the task, and forget what happened.

The next time the same problem appears, they start over.

That feels wrong.

A useful agent shouldn't just complete tasks.

It should accumulate knowledge about how to complete those tasks better.

This is where two ideas become extremely powerful when combined:

Agent loops provide action. Graphs provide memory.

And when the graph is updated by the agent's own experience, you get something much more interesting:

A self-improving system.

In this post, we're going to build a small version of that idea.

The Problem With Stateless Agents
An Agent Is a Loop
The Missing Piece: Memory
Why a Graph Works Better Than a Blob of Memory
Building a Tiny Engineering Agent
Step 1: Define the Graph
Step 2: Add Agent Experience
Step 3: Build the Agent Loop
Step 4: Let the Agent Learn
Step 5: Use Experience on the Next Run
The Self-Improving Loop
Why This Is Different From RAG
The Bigger Idea
Where This Goes Next
Final Thoughts

The Problem With Stateless Agents

Consider an engineering agent with this goal:

Fix the failing checkout test.

The agent might:

Read issue
    ↓
Inspect repository
    ↓
Find failing test
    ↓
Inspect implementation
    ↓
Modify code
    ↓
Run tests
    ↓
Fix failure
    ↓
Open pull request

Great.

But tomorrow another checkout test fails.

The agent starts from scratch.

It doesn't remember:

Which files mattered.
Which files were irrelevant.
Which tests were misleading.
Which solution worked.
Which solution failed.
Who reviewed the previous fix.
Which commands were useful.
Which dependency caused the original problem.

The agent has intelligence.

But it has no institutional memory.

That's a huge difference.

An Agent Is a Loop

At its simplest, an agent is not magic.

It's a loop:

Goal
 ↓
Observe
 ↓
Choose action
 ↓
Execute
 ↓
Check result
 ↓
Repeat

We can write that conceptually as:

while (!goalComplete) {
  const observation = observe();

  const action = decide(
    observation,
  );

  const result = execute(
    action,
  );

  check(result);
}

This is the core of an agent.

The model provides reasoning.

Tools provide capabilities.

The loop provides persistence toward a goal.

But there's another component we need.

Learning.

The Missing Piece: Memory

Imagine the agent completes a task.

Instead of simply returning:

Task complete.

it records what happened:

Task:
Fix checkout timeout.

Observation:
Checkout requests were being retried twice.

Action:
Changed retry behavior in checkout.ts.

Result:
Tests passed.

Related files:
payments.ts
retry.ts

Reviewer:
maya

Outcome:
Merged.

Now imagine that the next checkout problem occurs.

The agent can see this previous experience.

Instead of starting from zero:

What is checkout.ts?

it can start with:

Previous changes to checkout.ts indicate
that retry.ts and payments.ts are frequently
involved.

A previous fix modified retry behavior.

Let's inspect those relationships first.

That's a dramatically better agent.

But there is an important question:

How should we store the memory?

Why a Graph Works Better Than a Blob of Memory

You could dump everything into a document.

Something like:

Previous task:
Checkout timeout.

Files:
checkout.ts
payments.ts
retry.ts

People:
Maya
Bobby

Solution:
Changed retry behavior.

This works.

Until you have 10,000 tasks.

Then you have a giant pile of text.

The interesting information isn't just the facts.

It's the relationships.

For example:

Task
 │
 ├── affected → checkout.ts
 │                 │
 │                 └── related → retry.ts
 │
 ├── fixed-by → commit #823
 │
 ├── reviewed-by → Maya
 │
 └── resulted-in → merged PR

Now we have a graph.

And graphs give us something extremely useful:

Traversal.

We can ask:

What happened to this file?

Who worked on it?

Who reviewed those changes?

What other files changed with it?

Which previous tasks touched this area?

Which approaches worked?

Which approaches failed?

The agent doesn't need to remember everything.

It needs to know where to look.

Building a Tiny Engineering Agent

Let's build a small prototype.

Our agent will have one goal:

Investigate a failing test.

It will have four tools:

type Tool =
  | "search_code"
  | "read_file"
  | "run_tests"
  | "inspect_history";

And it will maintain a graph containing:

Task
File
Test
Change
Person
Outcome

Relationships will include:

AFFECTS
READ
MODIFIED
FIXED
FAILED
REVIEWED
RELATED_TO

The important part is that agent activity becomes graph data.

Step 1: Define the Graph

Create a simple graph implementation:

type NodeType =
  | "task"
  | "file"
  | "test"
  | "change"
  | "person"
  | "outcome";

type Relationship =
  | "AFFECTS"
  | "READ"
  | "MODIFIED"
  | "FIXED"
  | "FAILED"
  | "REVIEWED"
  | "RELATED_TO";

type Node = {
  id: string;
  type: NodeType;
  label: string;
  metadata?: Record<string, unknown>;
};

type Edge = {
  from: string;
  to: string;
  type: Relationship;
  metadata?: Record<string, unknown>;
};

Then:

class Graph {
  private nodes = new Map<string, Node>();
  private edges: Edge[] = [];

  addNode(node: Node) {
    this.nodes.set(node.id, node);
  }

  addEdge(edge: Edge) {
    this.edges.push(edge);
  }

  getNode(id: string) {
    return this.nodes.get(id);
  }

  neighbors(
    id: string,
    relationship?: Relationship,
  ) {
    return this.edges
      .filter((edge) => {
        if (edge.from !== id) {
          return false;
        }

        if (
          relationship &&
          edge.type !== relationship
        ) {
          return false;
        }

        return true;
      })
      .map((edge) => ({
        edge,
        node: this.nodes.get(edge.to),
      }))
      .filter(
        (result) => result.node !== undefined,
      );
  }
}

That's enough for our prototype.

We don't need Neo4j.

We don't need a distributed graph database.

We don't even need persistence yet.

We're trying to understand the architecture.

Step 2: Add Agent Experience

Now let's represent an experience.

type AgentExperience = {
  task: string;
  observations: string[];
  actions: string[];
  result: "success" | "failure";
  files: string[];
};

Suppose our agent successfully fixes a checkout problem.

We can record:

const experience: AgentExperience = {
  task: "Fix checkout timeout",
  observations: [
    "Requests were retried twice",
    "payments.ts was involved",
  ],
  actions: [
    "Inspected checkout.ts",
    "Inspected retry.ts",
    "Changed retry behavior",
    "Ran checkout tests",
  ],
  result: "success",
  files: [
    "checkout.ts",
    "retry.ts",
    "payments.ts",
  ],
};

Now turn that experience into graph nodes.

const taskId = "task:checkout-timeout";

graph.addNode({
  id: taskId,
  type: "task",
  label: experience.task,
});

for (const file of experience.files) {
  const fileId = `file:${file}`;

  graph.addNode({
    id: fileId,
    type: "file",
    label: file,
  });

  graph.addEdge({
    from: taskId,
    to: fileId,
    type: "AFFECTS",
  });
}

We have transformed an experience into structured memory.

Step 3: Build the Agent Loop

Now let's create the actual loop.

type AgentState = {
  goal: string;
  observations: string[];
  actions: string[];
  complete: boolean;
};

async function runAgent(
  goal: string,
  graph: Graph,
) {
  const state: AgentState = {
    goal,
    observations: [],
    actions: [],
    complete: false,
  };

  while (!state.complete) {
    const context =
      buildContext(state, graph);

    const decision =
      await decideNextAction(
        state,
        context,
      );

    state.actions.push(
      decision.action,
    );

    const result =
      await executeTool(
        decision.action,
        decision.input,
      );

    state.observations.push(
      result,
    );

    state.complete =
      await isComplete(
        state,
      );
  }

  return state;
}

This is a normal agent loop.

But notice this:

const context =
  buildContext(state, graph);

The graph is now part of the agent's observation system.

The agent doesn't just observe the repository.

It observes its accumulated experience.

That's the beginning of a self-improving agent.

Step 4: Let the Agent Learn

Now comes the interesting part.

When the task finishes, we update the graph.

function recordExperience(
  graph: Graph,
  state: AgentState,
) {
  const taskId =
    `task:${crypto.randomUUID()}`;

  graph.addNode({
    id: taskId,
    type: "task",
    label: state.goal,
  });

  for (const action of state.actions) {
    const actionId =
      `action:${crypto.randomUUID()}`;

    graph.addNode({
      id: actionId,
      type: "change",
      label: action,
    });

    graph.addEdge({
      from: taskId,
      to: actionId,
      type: "MODIFIED",
    });
  }

  const outcomeId =
    `outcome:${crypto.randomUUID()}`;

  graph.addNode({
    id: outcomeId,
    type: "outcome",
    label: state.complete
      ? "Success"
      : "Failure",
  });

  graph.addEdge({
    from: taskId,
    to: outcomeId,
    type: state.complete
      ? "FIXED"
      : "FAILED",
  });
}

Now the graph has changed because of the agent's experience.

That's the key.

The system isn't just reading a knowledge base.

The agent is writing back into it.

Step 5: Use Experience on the Next Run

Now let's say another task appears:

Fix checkout requests timing out.

Before deciding what to do, the agent queries the graph.

function findRelevantExperience(
  graph: Graph,
  query: string,
) {
  const tasks =
    graph.neighbors(
      "task:checkout-timeout",
    );

  return tasks;
}

In a real system, we'd use semantic search, graph traversal, or both.

The important concept is:

New task
   ↓
Find similar experiences
   ↓
Traverse relationships
   ↓
Build context
   ↓
Choose action

Now the agent can start with:

Previous experience:

checkout.ts
    ↓
retry.ts
    ↓
successful fix

Previous action:
Changed retry behavior.

Previous outcome:
Tests passed.

Potential next action:
Inspect retry.ts first.

The second agent doesn't need to rediscover everything.

It inherits the first agent's experience.

The Self-Improving Loop

We can now expand our original agent loop.

Instead of:

Goal
 ↓
Observe
 ↓
Act
 ↓
Check
 ↓
Repeat

we get:

                ┌───────────────────────┐
                │                       │
                ▼                       │
              Goal                     │
                │                       │
                ▼                       │
          Query the Graph              │
                │                       │
                ▼                       │
            Observe                    │
                │                       │
                ▼                       │
             Decide                    │
                │                       │
                ▼                       │
             Execute                   │
                │                       │
                ▼                       │
              Check                    │
                │                       │
         ┌──────┴──────┐                │
         │             │                │
       Failure       Success            │
         │             │                │
         └──────┬──────┘                │
                │                       │
                ▼                       │
          Update Graph ─────────────────┘

This creates an important feedback cycle:

Experience
    ↓
Graph
    ↓
Context
    ↓
Better decision
    ↓
New experience
    ↓
Graph

That is what I mean by a self-improving graph.

The graph becomes a record of what the system has learned by doing.

But There Is a Dangerous Problem

There is one thing we absolutely cannot do.

We cannot assume every experience is correct.

Imagine an agent tries this:

Action:
Increase retry count from 2 → 10

Result:
Test passed.

The agent records:

Increasing retries fixes checkout problems.

But maybe the test passed because the flaky test happened to pass.

Now we've poisoned the graph.

The next agent sees:

Historical knowledge:
Increasing retries works.

And repeats the mistake.

This is where verification becomes critical.

Evidence Before Learning

Instead of recording:

Agent says it worked.

we should record:

Agent changed code.
        ↓
Tests passed.
        ↓
Integration tests passed.
        ↓
Pull request merged.
        ↓
No incident occurred.

Confidence should increase as independent evidence accumulates.

For example:

type Outcome = {
  status: "success" | "failure";
  confidence: number;
  evidence: string[];
};

Then:

const outcome: Outcome = {
  status: "success",
  confidence: 0.92,
  evidence: [
    "unit tests passed",
    "integration tests passed",
    "pull request merged",
  ],
};

The graph should therefore store not just knowledge.

It should store:

knowledge + evidence + confidence.

That distinction becomes extremely important at scale.

Not All Memory Should Become Knowledge

Another subtle problem:

An agent might make 50 observations while solving a task.

Should all 50 become permanent memory?

Probably not.

We need to distinguish between:

Observation

Something the agent saw.

checkout.ts imports retry.ts

Event

Something that happened.

PR #842 modified checkout.ts

Outcome

Something that happened after an action.

Tests passed.

Knowledge

A relationship that is useful beyond the original task.

checkout.ts frequently changes with retry.ts

Heuristic

A generalized strategy.

When checkout tests fail with timeout errors,
inspect retry behavior first.

These are different levels of information.

A good learning system should progressively promote information:

Observation
    ↓
Evidence
    ↓
Repeated pattern
    ↓
Validated relationship
    ↓
Reusable knowledge

That's much safer than throwing every agent thought into a vector database and calling it memory.

Why This Is Different From RAG

RAG usually looks like:

Question
   ↓
Search documents
   ↓
Retrieve chunks
   ↓
Send chunks to model
   ↓
Generate answer

That's useful.

But it primarily answers:

What information is relevant?

A graph can answer a different question:

How are these things related?

Consider:

checkout.ts

A document search might retrieve:

PR #842
PR #811
PR #743

A graph can expose:

checkout.ts
   │
   ├── modified by → PR #842
   │                  │
   │                  ├── authored by → Maya
   │                  └── reviewed by → Bobby
   │
   ├── modified by → PR #811
   │                  │
   │                  └── related → retry.ts
   │
   └── modified by → PR #743
                      │
                      └── caused → checkout incident

Now the agent can reason over the structure.

RAG gives you relevant documents.

A graph can give you contextual relationships.

The two are not competitors.

They are extremely complementary.

The Graph Can Also Learn From Failure

This might be even more valuable than learning from success.

Suppose an agent tries:

Approach A

It fails.

Then:

Approach B

It succeeds.

We should record both.

Task
 │
 ├── attempted → Approach A
 │                 │
 │                 └── FAILED
 │
 └── attempted → Approach B
                   │
                   └── SUCCEEDED

Now future agents have something extremely valuable:

negative knowledge.

They don't just know what worked.

They know what was already tried.

That prevents agents from repeatedly walking into the same hole.

A More Advanced Agent Loop

Eventually, the architecture starts looking like this:

┌────────────────────────────────────┐
│              Agent                 │
│                                    │
│   Goal → Plan → Act → Verify      │
│              ↑         │            │
│              │         ▼            │
│          Context ← Experience      │
└───────────────┬────────────────────┘
                │
                ▼
       ┌─────────────────┐
       │ Engineering     │
       │ Graph           │
       ├─────────────────┤
       │ Code            │
       │ People          │
       │ PRs             │
       │ Tests           │
       │ Incidents       │
       │ Decisions       │
       │ Outcomes        │
       │ Evidence        │
       └─────────────────┘

The agent operates on the software.

The graph observes what happens.

The graph accumulates relationships.

The agent queries those relationships.

And the cycle continues.

The Interesting Part: The Agent Becomes Better Without Retraining

This is where things get really interesting.

We often think about an AI system improving through:

Better model
↓
More training
↓
Better weights

But an agent can also improve through:

Better experience
↓
Better graph
↓
Better context
↓
Better decisions

No model retraining required.

The underlying model can remain exactly the same.

What changes is the environment around the model.

This is an important distinction.

A powerful model with poor context can perform badly.

A slightly less capable model with excellent context, tools, memory, and verification can perform surprisingly well.

The Graph Becomes an Organizational Memory

Now take this idea outside of one agent.

Imagine a company where every engineering activity contributes to the graph:

GitHub
   ↓
Pull Requests
   ↓
Code Changes
   ↓
Reviews
   ↓
Deployments
   ↓
Incidents
   ↓
Fixes
   ↓
Agent Experiences

You eventually get something much larger than a dependency graph.

You get a model of how the organization actually operates.

You can ask:

Who understands this system?

Why was this architecture chosen?

What usually breaks when this service changes?

Which files are high-risk?

Which engineers have solved similar problems?

What approaches have already failed?

What changed after the last incident?

What should an agent inspect before modifying this service?

These questions aren't answered by source code alone.

They're answered by relationships across engineering history.

Where This Goes Next

The prototype we built is intentionally simple.

A production system could add much more.

Temporal Graphs

Relationships change over time.

Person A understood service X in 2024.
Person B became the primary contributor in 2026.

The graph needs to understand time.

Confidence

Not every relationship is equally trustworthy.

Observed directly
    ↓
High confidence

Inferred from repeated behavior
    ↓
Medium confidence

Model-generated hypothesis
    ↓
Low confidence

Agent Performance

The graph can track:

Agent
 ↓
Task
 ↓
Actions
 ↓
Outcome
 ↓
Time
 ↓
Cost
 ↓
Human review

Now you can measure which strategies actually work.

Human Feedback

A human might tell the agent:

Don't modify this service.
The dependency is intentional.

That becomes knowledge.

The graph gets better.

The next agent benefits.

Multiple Agents

Now imagine several specialized agents:

Code Agent
Security Agent
Testing Agent
Incident Agent
Documentation Agent

All contributing to the same graph.

One agent discovers something.

Another agent can use it.

That's when the graph becomes shared memory across an agent workforce.

The Bigger Idea

I think there is a fundamental shift happening in how we build software agents.

The first generation of agents was mostly about:

Can the model perform the task?

The next generation is about:

Can the system learn from performing the task?

Those are very different problems.

A single agent completing one task is useful.

An agent that improves the context available to the next agent is much more powerful.

And an organization where thousands of engineering actions continuously improve a shared knowledge graph starts to look like something new.

Not just an AI assistant.

Not just a chatbot.

Not just RAG.

A learning system.

The core architecture is surprisingly simple:

Agent
  ↓
Acts
  ↓
Produces evidence
  ↓
Updates graph
  ↓
Graph provides better context
  ↓
Agent makes better decisions
  ↓
Acts again

That's the loop.

And the loop is the product.

Final Thoughts

The biggest mistake we can make with AI agents is treating every task as an isolated conversation.

Software isn't isolated.

People aren't isolated.

Decisions aren't isolated.

Failures aren't isolated.

Everything is connected.

A pull request connects to files.

Files connect to services.

Services connect to incidents.

Incidents connect to fixes.

Fixes connect to engineers.

Engineers connect to decisions.

Decisions connect to outcomes.

And those relationships contain something incredibly valuable:

experience.

The job of a self-improving engineering system is to capture that experience, verify it, connect it, and make it available when the next decision needs to be made.

The model provides reasoning.

The tools provide action.

The graph provides memory.

The feedback loop provides improvement.

Put those four things together and you get something far more interesting than an agent that can execute a task.

You get an agent that can learn from doing the work.

Building Toward Engineering Intelligence

This is the idea behind Helix: an engineering intelligence layer that builds a living graph of your software, engineering activity, decisions, and evidence so AI can understand what happened before it decides what to do next.

If you're building AI agents for serious engineering work, see what Helix is building →

Build a Mini Engineering Graph With TypeScript and GitHub

Bobby Hall Jr — Mon, 24 Aug 2026 04:37:07 +0000

You inherit a codebase.

A file called checkout.ts is causing problems.

You ask three questions:

Why was this code changed?
Who actually understands it?
What other files usually change alongside it?

The answers probably exist somewhere in GitHub.

But they are scattered across pull requests, reviews, file histories, and people’s memories.

In this tutorial, we are going to connect those dots.

We will build a small TypeScript CLI that turns real GitHub pull requests into an engineering graph.

By the end, you will be able to run commands like these:

npm run dev -- vercel/ai
npm run dev -- vercel/ai pr 123
npm run dev -- vercel/ai experts "src/example.ts"
npm run dev -- vercel/ai related "src/example.ts"

No graph database.

No vector database.

No AI model required.

Just TypeScript, GitHub’s API, and one useful idea:

Engineering knowledge becomes more valuable when you preserve the relationships between the things your team already creates.

What We Are Building
Project Setup
Step 1: Define the Graph
Step 2: Build an In-Memory Graph
Step 3: Turn GitHub Activity Into Relationships
Step 4: Ask the Graph Useful Questions
Step 5: Build the CLI
Run the Project
Add a Test
What This Project Gets Right
Where It Breaks Down
Where AI Fits
Final Thoughts

What We Are Building

Our graph will contain four types of nodes:

Node type	Example
Repository	`vercel/ai`
Pull request	`#482: Improve streaming response handling`
File	`packages/ai/src/generate-text.ts`
Person	`bobbyhalljr`

We will connect them with four relationship types:

Relationship	Meaning
`BELONGS_TO`	A pull request belongs to a repository.
`AUTHORED`	A person created a pull request.
`MODIFIED`	A pull request changed a file.
`REVIEWED`	A person reviewed a pull request.

The interesting part is what those connections let us discover.

For example:

person → AUTHORED → pull request → MODIFIED → file

That path tells us who has direct experience changing a file.

This path tells us who reviewed the change:

person → REVIEWED → pull request → MODIFIED → file

And this path reveals files that changed together:

file ← MODIFIED ← pull request → MODIFIED → another file

That is graph engineering at its most practical.

We are not inventing new information.

We are making existing relationships visible.

Project Setup

You will need:

Node.js 18 or newer.
npm.
A public GitHub repository to analyze.
An optional GitHub token for a higher API rate limit.

Create the project:

mkdir mini-engineering-graph
cd mini-engineering-graph

npm init -y

npm install --save-dev typescript tsx @types/node

npm pkg set type=module
npm pkg set scripts.dev="tsx src/index.ts"
npm pkg set scripts.test="tsx --test src/graph.test.ts"

mkdir -p src

The project will contain these files:

src/types.ts
src/graph.ts
src/github.ts
src/queries.ts
src/index.ts
src/graph.test.ts

To analyze private repositories or increase your GitHub API allowance, configure a token:

export GITHUB_TOKEN="your_github_token_here"

Never commit your token or hardcode it into the application.

Public repositories work without one, but unauthenticated requests are limited to 60 requests per hour.

By default, our project analyzes up to 10 recently closed pull requests and makes up to 21 API requests:

One request to list pull requests.
One request per merged pull request to list changed files.
One request per merged pull request to list reviews.

Each CLI command rebuilds the graph, so repeated runs consume additional requests.

Step 1: Define the Graph

Create src/types.ts:

export type NodeType =
  | "repository"
  | "pull_request"
  | "file"
  | "person";

export type RelationshipType =
  | "BELONGS_TO"
  | "AUTHORED"
  | "MODIFIED"
  | "REVIEWED";

export type GraphNode = {
  id: string;
  type: NodeType;
  label: string;
  metadata: Record<string, unknown>;
};

export type Evidence = {
  source: "github";
  url: string;
  summary: string;
  observedAt: string;
};

export type GraphEdge = {
  from: string;
  to: string;
  type: RelationshipType;
  evidence: Evidence;
  metadata?: Record<string, unknown>;
};

export type GitHubUser = {
  login: string;
  html_url: string;
};

export type GitHubPullRequest = {
  number: number;
  title: string;
  body: string | null;
  html_url: string;
  created_at: string;
  updated_at: string;
  merged_at: string | null;
  user: GitHubUser | null;
};

export type GitHubFile = {
  filename: string;
  status: string;
  additions: number;
  deletions: number;
};

export type GitHubReview = {
  id: number;
  state: string;
  html_url: string;
  submitted_at: string | null;
  user: GitHubUser | null;
};

There are two important ideas here.

First, nodes and edges have different jobs.

A node represents something that exists:

{
  id: "person:bobby",
  type: "person",
  label: "bobby",
  metadata: {}
}

An edge represents a relationship:

{
  from: "person:bobby",
  to: "pr:acme/storefront#41",
  type: "AUTHORED"
}

Second, every edge includes evidence.

If our application claims someone authored or reviewed a change, we should be able to point to the GitHub artifact that supports that claim.

Without evidence, a graph can become a polished collection of guesses.

Step 2: Build an In-Memory Graph

Create src/graph.ts:

import type {
  GraphEdge,
  GraphNode,
  NodeType,
  RelationshipType,
} from "./types.ts";

export class EngineeringGraph {
  private readonly nodes = new Map<string, GraphNode>();
  private readonly edges = new Map<string, GraphEdge>();

  addNode(node: GraphNode): void {
    this.nodes.set(node.id, node);
  }

  addEdge(edge: GraphEdge): void {
    if (!this.nodes.has(edge.from) || !this.nodes.has(edge.to)) {
      throw new Error(
        `Both nodes must exist before adding ${edge.type}`,
      );
    }

    const key = `${edge.from}:${edge.type}:${edge.to}`;

    this.edges.set(key, edge);
  }

  getNode(id: string): GraphNode | undefined {
    return this.nodes.get(id);
  }

  getNodesByType(type: NodeType): GraphNode[] {
    return [...this.nodes.values()].filter(
      (node) => node.type === type,
    );
  }

  neighbors(
    nodeId: string,
    relationship: RelationshipType,
    direction: "outgoing" | "incoming" = "outgoing",
  ): Array<{ node: GraphNode; edge: GraphEdge }> {
    const matches: Array<{
      node: GraphNode;
      edge: GraphEdge;
    }> = [];

    for (const edge of this.edges.values()) {
      if (edge.type !== relationship) {
        continue;
      }

      const matchesDirection =
        direction === "outgoing"
          ? edge.from === nodeId
          : edge.to === nodeId;

      if (!matchesDirection) {
        continue;
      }

      const neighborId =
        direction === "outgoing"
          ? edge.to
          : edge.from;

      const node = this.nodes.get(neighborId);

      if (node) {
        matches.push({ node, edge });
      }
    }

    return matches;
  }

  stats() {
    return {
      nodes: this.nodes.size,
      edges: this.edges.size,
      pullRequests: this.getNodesByType("pull_request").length,
      files: this.getNodesByType("file").length,
      people: this.getNodesByType("person").length,
    };
  }
}

The most important method is neighbors().

It answers:

Which nodes are connected to this node by a specific relationship?

For example:

graph.neighbors(
  "pr:acme/storefront#41",
  "MODIFIED",
);

That returns files changed by the pull request.

Reverse the direction:

graph.neighbors(
  "file:acme/storefront:src/checkout.ts",
  "MODIFIED",
  "incoming",
);

Now you get pull requests that changed the file.

Same relationship.

Different direction.

Different question.

We also validate that both nodes exist before adding an edge.

A relationship pointing to a missing node is not useful context. It is a bug wearing a name tag.

Step 3: Turn GitHub Activity Into Relationships

Create src/github.ts:

import { EngineeringGraph } from "./graph.ts";

import type {
  Evidence,
  GitHubFile,
  GitHubPullRequest,
  GitHubReview,
  GitHubUser,
} from "./types.ts";

const API_BASE = "https://api.github.com";

async function github<T>(path: string): Promise<T> {
  const headers: Record<string, string> = {
    Accept: "application/vnd.github+json",
    "X-GitHub-Api-Version": "2026-03-10",
  };

  if (process.env.GITHUB_TOKEN) {
    headers.Authorization =
      `Bearer ${process.env.GITHUB_TOKEN}`;
  }

  const response = await fetch(
    `${API_BASE}${path}`,
    { headers },
  );

  if (!response.ok) {
    const remaining = response.headers.get(
      "x-ratelimit-remaining",
    );

    const detail = await response.text();

    throw new Error(
      `GitHub request failed (${response.status}). ` +
        `Remaining requests: ${remaining ?? "unknown"}. ` +
        detail,
    );
  }

  return (await response.json()) as T;
}

function addPerson(
  graph: EngineeringGraph,
  user: GitHubUser,
): string {
  const personId = `person:${user.login}`;

  graph.addNode({
    id: personId,
    type: "person",
    label: user.login,
    metadata: {
      url: user.html_url,
    },
  });

  return personId;
}

function evidence(
  url: string,
  summary: string,
  observedAt: string,
): Evidence {
  return {
    source: "github",
    url,
    summary,
    observedAt,
  };
}

export async function buildEngineeringGraph(
  repository: string,
  limit = 10,
): Promise<EngineeringGraph> {
  const graph = new EngineeringGraph();

  const repositoryId = `repo:${repository}`;

  graph.addNode({
    id: repositoryId,
    type: "repository",
    label: repository,
    metadata: {
      url: `https://github.com/${repository}`,
    },
  });

  const pulls = await github<GitHubPullRequest[]>(
    `/repos/${repository}/pulls` +
      `?state=closed` +
      `&sort=updated` +
      `&direction=desc` +
      `&per_page=${limit}`,
  );

  const mergedPulls = pulls.filter(
    (pull) => pull.merged_at && pull.user,
  );

  for (const pull of mergedPulls) {
    const author = pull.user!;
    const pullId = `pr:${repository}#${pull.number}`;

    graph.addNode({
      id: pullId,
      type: "pull_request",
      label: `#${pull.number}: ${pull.title}`,
      metadata: {
        number: pull.number,
        title: pull.title,
        body: pull.body,
        url: pull.html_url,
        mergedAt: pull.merged_at,
      },
    });

    graph.addEdge({
      from: pullId,
      to: repositoryId,
      type: "BELONGS_TO",
      evidence: evidence(
        pull.html_url,
        "Pull request belongs to repository",
        pull.updated_at,
      ),
    });

    graph.addEdge({
      from: addPerson(graph, author),
      to: pullId,
      type: "AUTHORED",
      evidence: evidence(
        pull.html_url,
        `${author.login} authored this change`,
        pull.created_at,
      ),
    });

    const [files, reviews] = await Promise.all([
      github<GitHubFile[]>(
        `/repos/${repository}/pulls/` +
          `${pull.number}/files?per_page=100`,
      ),
      github<GitHubReview[]>(
        `/repos/${repository}/pulls/` +
          `${pull.number}/reviews?per_page=100`,
      ),
    ]);

    for (const file of files) {
      const fileId =
        `file:${repository}:${file.filename}`;

      graph.addNode({
        id: fileId,
        type: "file",
        label: file.filename,
        metadata: {
          path: file.filename,
        },
      });

      graph.addEdge({
        from: pullId,
        to: fileId,
        type: "MODIFIED",
        evidence: evidence(
          `${pull.html_url}/files`,
          `${file.filename} was ${file.status}`,
          pull.updated_at,
        ),
        metadata: {
          status: file.status,
          additions: file.additions,
          deletions: file.deletions,
        },
      });
    }

    for (const review of reviews) {
      if (
        !review.user ||
        !review.submitted_at ||
        review.state === "PENDING"
      ) {
        continue;
      }

      graph.addEdge({
        from: addPerson(graph, review.user),
        to: pullId,
        type: "REVIEWED",
        evidence: evidence(
          review.html_url,
          `${review.user.login} submitted a ` +
            `${review.state} review`,
          review.submitted_at,
        ),
        metadata: {
          state: review.state,
        },
      });
    }
  }

  return graph;
}

There is a lot happening here, so let’s walk through the important parts.

Fetch Recently Closed Pull Requests

We start with:

const pulls = await github<GitHubPullRequest[]>(
  `/repos/${repository}/pulls` +
    `?state=closed` +
    `&sort=updated` +
    `&direction=desc` +
    `&per_page=${limit}`,
);

GitHub returns closed pull requests, including both merged and unmerged changes.

We only want changes that actually landed:

const mergedPulls = pulls.filter(
  (pull) => pull.merged_at && pull.user,
);

Because we filter after fetching, the final graph may contain fewer than the requested number of pull requests.

A production system would paginate until it collected the desired number of merged changes.

Create Author Relationships

For each pull request:

graph.addEdge({
  from: addPerson(graph, author),
  to: pullId,
  type: "AUTHORED",
  evidence: evidence(
    pull.html_url,
    `${author.login} authored this change`,
    pull.created_at,
  ),
});

The author is not merely a string attached to the pull request.

The author is a node with a relationship.

That means we can later ask:

Which other files has this person changed?

Or:

Which people have touched this part of the codebase?

The answers become graph traversals instead of one-off transformations.

Add Changed Files

Every changed file becomes its own node:

const fileId =
  `file:${repository}:${file.filename}`;

We include the repository in the identifier so files from different projects cannot collide:

file:acme/storefront:src/checkout.ts
file:acme/admin:src/checkout.ts

Same filename.

Different context.

Different node.

The edge stores additional metadata:

metadata: {
  status: file.status,
  additions: file.additions,
  deletions: file.deletions,
}

Later, we could use that information to distinguish a tiny documentation update from a substantial code change.

Add Review Relationships

Reviews tell us who examined a change, even when they did not author it.

That matters because the original author is not always the only person who understands a piece of code.

graph.addEdge({
  from: addPerson(graph, review.user),
  to: pullId,
  type: "REVIEWED",
  evidence: evidence(
    review.html_url,
    `${review.user.login} submitted a ` +
      `${review.state} review`,
    review.submitted_at,
  ),
});

Our graph deduplicates edges by their starting node, relationship type, and destination node.

If someone reviews the same pull request multiple times, the latest processed review replaces the earlier one.

That keeps the demo simple, but it also means we are not preserving the complete review timeline.

Step 4: Ask the Graph Useful Questions

Create src/queries.ts:

import { EngineeringGraph } from "./graph.ts";

export function explainPullRequest(
  graph: EngineeringGraph,
  repository: string,
  number: number,
) {
  const pullId =
    `pr:${repository}#${number}`;

  const pull = graph.getNode(pullId);

  if (!pull) {
    throw new Error(
      `Pull request #${number} was not found ` +
        `in the indexed history.`,
    );
  }

  return {
    title: pull.metadata.title,

    reason:
      pull.metadata.body ||
      "No pull request description was provided.",

    url: pull.metadata.url,

    authors: graph
      .neighbors(
        pullId,
        "AUTHORED",
        "incoming",
      )
      .map(({ node }) => node.label),

    reviewers: graph
      .neighbors(
        pullId,
        "REVIEWED",
        "incoming",
      )
      .map(({ node, edge }) => ({
        name: node.label,
        state: edge.metadata?.state,
      })),

    files: graph
      .neighbors(
        pullId,
        "MODIFIED",
      )
      .map(({ node, edge }) => ({
        path: node.label,
        additions: edge.metadata?.additions,
        deletions: edge.metadata?.deletions,
        evidence: edge.evidence.url,
      })),
  };
}

export function findExperts(
  graph: EngineeringGraph,
  repository: string,
  path: string,
) {
  const fileId =
    `file:${repository}:${path}`;

  const changes = graph.neighbors(
    fileId,
    "MODIFIED",
    "incoming",
  );

  const people = new Map<
    string,
    {
      name: string;
      score: number;
      authored: number;
      reviewed: number;
      evidence: Set<string>;
    }
  >();

  for (const { node: pull } of changes) {
    for (const relationship of [
      "AUTHORED",
      "REVIEWED",
    ] as const) {
      const contributors = graph.neighbors(
        pull.id,
        relationship,
        "incoming",
      );

      for (const { node: person, edge } of contributors) {
        const existing = people.get(person.id) ?? {
          name: person.label,
          score: 0,
          authored: 0,
          reviewed: 0,
          evidence: new Set<string>(),
        };

        if (relationship === "AUTHORED") {
          existing.score += 3;
          existing.authored += 1;
        } else {
          existing.score += 1;
          existing.reviewed += 1;
        }

        existing.evidence.add(
          edge.evidence.url,
        );

        people.set(
          person.id,
          existing,
        );
      }
    }
  }

  return [...people.values()]
    .sort(
      (left, right) =>
        right.score - left.score,
    )
    .map((person) => ({
      ...person,
      evidence: [...person.evidence],
    }));
}

export function findRelatedFiles(
  graph: EngineeringGraph,
  repository: string,
  path: string,
) {
  const fileId =
    `file:${repository}:${path}`;

  const changes = graph.neighbors(
    fileId,
    "MODIFIED",
    "incoming",
  );

  const related = new Map<
    string,
    {
      path: string;
      sharedChanges: number;
      evidence: string[];
    }
  >();

  for (const { node: pull } of changes) {
    const changedFiles = graph.neighbors(
      pull.id,
      "MODIFIED",
    );

    for (const { node: file, edge } of changedFiles) {
      if (file.id === fileId) {
        continue;
      }

      const existing = related.get(file.id) ?? {
        path: file.label,
        sharedChanges: 0,
        evidence: [],
      };

      existing.sharedChanges += 1;

      existing.evidence.push(
        edge.evidence.url,
      );

      related.set(
        file.id,
        existing,
      );
    }
  }

  return [...related.values()].sort(
    (left, right) =>
      right.sharedChanges -
      left.sharedChanges,
  );
}

These three queries demonstrate why graphs are useful.

Question 1: Why Was This Changed?

The explainPullRequest() function combines:

Pull request title.
Pull request description.
Author.
Reviewers.
Changed files.
Links to supporting evidence.

An example response:

{
  "title": "Prevent duplicate checkout requests",
  "reason": "Checkout timed out because repeated requests saturated the payments API.",
  "url": "https://github.com/acme/storefront/pull/41",
  "authors": ["bobby"],
  "reviewers": [
    {
      "name": "maya",
      "state": "APPROVED"
    }
  ],
  "files": [
    {
      "path": "src/checkout.ts",
      "additions": 24,
      "deletions": 6,
      "evidence": "https://github.com/acme/storefront/pull/41/files"
    }
  ]
}

This does not magically recover a missing explanation.

If the pull request description is empty, the tool says so.

That honesty matters.

A system should not manufacture confidence when the source material does not support it.

Question 2: Who Understands This File?

The findExperts() function starts at a file.

It walks backward to pull requests that modified it.

From there, it finds people who authored or reviewed those pull requests.

We assign a simple score:

if (relationship === "AUTHORED") {
  existing.score += 3;
} else {
  existing.score += 1;
}

An authored change counts more than a review.

This is a heuristic, not an objective measure of expertise.

A thoughtful review may reveal deeper understanding than a rushed code change. Recency, change size, ownership, and familiarity with neighboring files would all improve the ranking.

But even this simple version answers a practical question:

Who should I talk to before touching this file?

Example:

[
  {
    "name": "bobby",
    "score": 4,
    "authored": 1,
    "reviewed": 1,
    "evidence": [
      "https://github.com/acme/storefront/pull/41",
      "https://github.com/acme/storefront/pull/40#review-2"
    ]
  },
  {
    "name": "maya",
    "score": 4,
    "authored": 1,
    "reviewed": 1,
    "evidence": [
      "https://github.com/acme/storefront/pull/41#review-1",
      "https://github.com/acme/storefront/pull/40"
    ]
  }
]

Every recommendation comes with evidence.

That is a better starting point than asking a model to guess who sounds qualified.

Question 3: What Else Changes With This File?

The findRelatedFiles() function looks for files modified in the same pull requests.

Example:

[
  {
    "path": "src/payments.ts",
    "sharedChanges": 2,
    "evidence": [
      "https://github.com/acme/storefront/pull/41/files",
      "https://github.com/acme/storefront/pull/40/files"
    ]
  }
]

If checkout.ts and payments.ts repeatedly change together, that is useful information.

But be careful:

Co-change is not the same thing as a proven dependency.

Two files can appear in the same pull request for many reasons.

They might share an architectural dependency.

They might belong to the same feature.

Or somebody might have bundled unrelated cleanup into one giant Friday-afternoon pull request.

The graph reveals a pattern.

Determining why the pattern exists requires additional evidence.

Step 5: Build the CLI

Create src/index.ts:

import {
  buildEngineeringGraph,
} from "./github.ts";

import {
  explainPullRequest,
  findExperts,
  findRelatedFiles,
} from "./queries.ts";

async function main() {
  const [
    repository,
    command,
    ...arguments_
  ] = process.argv.slice(2);

  if (
    !repository ||
    !/^[^/]+\/[^/]+$/.test(repository)
  ) {
    throw new Error(
      "Usage: npm run dev -- " +
        "owner/repository " +
        "[pr|experts|related] [value]",
    );
  }

  const requestedLimit = Number(
    process.env.PR_LIMIT ?? "10",
  );

  if (
    !Number.isInteger(requestedLimit) ||
    requestedLimit < 1 ||
    requestedLimit > 25
  ) {
    throw new Error(
      "PR_LIMIT must be an integer " +
        "between 1 and 25.",
    );
  }

  console.log(
    `Indexing recent merged pull requests ` +
      `from ${repository}...`,
  );

  const graph =
    await buildEngineeringGraph(
      repository,
      requestedLimit,
    );

  console.log(
    "Graph:",
    graph.stats(),
  );

  if (command === "pr") {
    const number = Number(
      arguments_[0],
    );

    if (
      !Number.isInteger(number) ||
      number < 1
    ) {
      throw new Error(
        "Provide a valid pull request number.",
      );
    }

    console.dir(
      explainPullRequest(
        graph,
        repository,
        number,
      ),
      { depth: null },
    );

    return;
  }

  if (command === "experts") {
    const path = arguments_.join(" ");

    if (!path) {
      throw new Error(
        "Provide a file path after experts.",
      );
    }

    console.dir(
      findExperts(
        graph,
        repository,
        path,
      ),
      { depth: null },
    );

    return;
  }

  if (command === "related") {
    const path = arguments_.join(" ");

    if (!path) {
      throw new Error(
        "Provide a file path after related.",
      );
    }

    console.dir(
      findRelatedFiles(
        graph,
        repository,
        path,
      ),
      { depth: null },
    );

    return;
  }

  if (command) {
    throw new Error(
      `Unknown command: ${command}. ` +
        `Use pr, experts, or related.`,
    );
  }

  const pulls = graph.getNodesByType(
    "pull_request",
  );

  if (pulls.length === 0) {
    console.log(
      "No merged pull requests were found " +
        "in the indexed history.",
    );

    return;
  }

  const latest = pulls[0];

  const changedFile = graph.neighbors(
    latest.id,
    "MODIFIED",
  )[0]?.node.label;

  console.log(
    "\nIndexed pull requests:",
  );

  for (const pull of pulls) {
    console.log(
      `- ${pull.label}`,
    );
  }

  console.log(
    `\nTry: npm run dev -- ${repository} ` +
      `pr ${latest.metadata.number}`,
  );

  if (changedFile) {
    console.log(
      `Try: npm run dev -- ${repository} ` +
        `experts "${changedFile}"`,
    );

    console.log(
      `Try: npm run dev -- ${repository} ` +
        `related "${changedFile}"`,
    );
  }
}

main().catch(
  (error: unknown) => {
    console.error(
      error instanceof Error
        ? error.message
        : error,
    );

    process.exitCode = 1;
  },
);

The CLI accepts a repository and an optional command:

npm run dev -- owner/repository

npm run dev -- owner/repository pr 123

npm run dev -- owner/repository experts "src/example.ts"

npm run dev -- owner/repository related "src/example.ts"

When you run the repository command without additional arguments, the application prints real pull request numbers and file paths you can use for the next command.

That saves you from guessing whether a file exists in the indexed history.

Run the Project

Try it against a public repository:

npm run dev -- vercel/ai

You should see output shaped like this:

Indexing recent merged pull requests from vercel/ai...

Graph: {
  nodes: 68,
  edges: 94,
  pullRequests: 8,
  files: 42,
  people: 17
}

Indexed pull requests:
- #12345: Improve streaming response handling
- #12344: Fix tool call parsing
- #12343: Update provider configuration

Try: npm run dev -- vercel/ai pr 12345

Try: npm run dev -- vercel/ai experts "packages/ai/src/example.ts"

Try: npm run dev -- vercel/ai related "packages/ai/src/example.ts"

Those pull request numbers and file paths are illustrative.

Your results will depend on the repository’s current history.

Use the exact commands printed by your own run.

To inspect more pull requests:

PR_LIMIT=20 npm run dev -- vercel/ai

If GitHub returns a rate-limit error, configure a token:

export GITHUB_TOKEN="your_github_token_here"

Then rerun the command:

npm run dev -- vercel/ai

For a personal repository:

npm run dev -- your-github-username/your-repository

You now have a small system that can tell you:

What changed.
Why the author said it changed.
Who authored the change.
Who reviewed it.
Which files were involved.
Which contributors know a file.
Which files frequently appear together.

Not bad for a few TypeScript files.

Add a Test

Create src/graph.test.ts:

import assert from "node:assert/strict";
import test from "node:test";

import {
  EngineeringGraph,
} from "./graph.ts";

import {
  findExperts,
} from "./queries.ts";

test(
  "ranks pull request authors above reviewers",
  () => {
    const graph = new EngineeringGraph();

    const evidence = {
      source: "github" as const,
      url: "https://github.com/acme/storefront/pull/12",
      summary: "Verified GitHub relationship",
      observedAt: "2026-08-20T12:00:00Z",
    };

    graph.addNode({
      id: "person:bobby",
      type: "person",
      label: "bobby",
      metadata: {},
    });

    graph.addNode({
      id: "person:maya",
      type: "person",
      label: "maya",
      metadata: {},
    });

    graph.addNode({
      id: "pr:acme/storefront#12",
      type: "pull_request",
      label: "#12: Improve checkout",
      metadata: {},
    });

    graph.addNode({
      id: "file:acme/storefront:src/checkout.ts",
      type: "file",
      label: "src/checkout.ts",
      metadata: {},
    });

    graph.addEdge({
      from: "person:bobby",
      to: "pr:acme/storefront#12",
      type: "AUTHORED",
      evidence,
    });

    graph.addEdge({
      from: "person:maya",
      to: "pr:acme/storefront#12",
      type: "REVIEWED",
      evidence,
    });

    graph.addEdge({
      from: "pr:acme/storefront#12",
      to: "file:acme/storefront:src/checkout.ts",
      type: "MODIFIED",
      evidence,
    });

    const experts = findExperts(
      graph,
      "acme/storefront",
      "src/checkout.ts",
    );

    assert.deepEqual(
      experts.map(
        ({ name, score }) => ({
          name,
          score,
        }),
      ),
      [
        {
          name: "bobby",
          score: 3,
        },
        {
          name: "maya",
          score: 1,
        },
      ],
    );
  },
);

Run the test:

npm test

Expected result:

✔ ranks pull request authors above reviewers
ℹ tests 1
ℹ pass 1
ℹ fail 0

This test does not call GitHub.

It builds a tiny graph directly and checks that our traversal and scoring behave as expected.

That separation matters:

GitHub ingestion gathers facts.
The graph stores relationships.
Query functions interpret those relationships.
Tests verify interpretation without depending on a network request.

What This Project Gets Right

Several architectural choices make this little project more useful than it might initially appear.

Relationships Are Explicit

We do not bury authorship inside an unstructured paragraph.

We represent it directly:

person → AUTHORED → pull request

That makes the relationship easy to query and explain.

Evidence Stays Attached

Every edge includes a source URL.

When the system recommends someone as a subject-matter expert, it can show the pull requests or reviews behind the recommendation.

That matters when engineers need to trust the result.

The Graph Can Grow

Today we have:

"AUTHORED"
"REVIEWED"
"MODIFIED"
"BELONGS_TO"

Tomorrow we could add:

"DEPENDS_ON"
"DEPLOYED"
"MENTIONED_IN"
"CAUSED"
"RESOLVED"
"OWNS"

The same graph structure can support much richer questions.

Storage Is an Implementation Detail

Our graph lives in memory.

That is appropriate for a small tutorial.

If the project grows, the same ideas can move into:

PostgreSQL.
A dedicated graph database.
A search index.
A hybrid system.

The core idea does not depend on a particular database.

Where It Breaks Down

This is a useful prototype.

It is not a production engineering intelligence platform.

Here are the obvious limitations.

It Rebuilds Everything on Every Run

Each CLI command fetches GitHub data again.

For repeated use, you would want:

Persistent storage.
Cached API responses.
Incremental updates.
GitHub webhooks.

It Only Fetches the First Page

We request up to 100 files and 100 reviews per pull request.

Larger pull requests would require pagination.

It Only Sees Recently Closed Pull Requests

The graph knows nothing about changes outside its indexed window.

If the original author changed a file two years ago, our default history probably will not find them.

It Does Not Understand Dependencies

Files changing together is a signal.

It does not prove that one file imports another, calls another, or will break when another changes.

A stronger version would parse:

Imports.
Function calls.
Service boundaries.
API contracts.
Deployment relationships.

It Does Not Model Permissions

Private repositories and sensitive engineering data require access controls.

A production graph must ensure users cannot discover information derived from artifacts they are not authorized to access.

It Does Not Preserve Every Review Event

Multiple reviews by the same person on the same pull request collapse into one relationship.

If review history matters, the graph should represent individual review events as their own nodes.

These limitations are not reasons to avoid building the prototype.

They show where a real product needs to go next.

Where AI Fits

You may have noticed something:

We built a useful intelligence layer without calling a language model.

That is intentional.

Language models are excellent at turning structured context into clear explanations.

They are less reliable when forced to reconstruct missing relationships from disconnected documents.

Once we have the graph, an AI layer can summarize evidence like this:

async function explainFile(
  repository: string,
  path: string,
) {
  const graph = await buildEngineeringGraph(
    repository,
  );

  const experts = findExperts(
    graph,
    repository,
    path,
  );

  const relatedFiles = findRelatedFiles(
    graph,
    repository,
    path,
  );

  const context = {
    file: path,
    experts,
    relatedFiles,
  };

  return {
    prompt: `
Explain what an engineer should know before modifying this file.

Use only the supplied evidence.

Clearly distinguish observed facts from inferred relationships.

Do not claim that files are dependencies merely because they changed together.

Context:

${JSON.stringify(context, null, 2)}
    `.trim(),
  };
}

This prepares a grounded prompt that you can send to whichever model provider your application uses.

The model does not need to invent who reviewed the file.

The graph already knows.

It does not need to guess which pull requests changed the file.

The graph already knows.

Its job becomes explaining connected evidence, not manufacturing context.

That is a much healthier division of labor.

Final Thoughts

The interesting part of graph engineering is not the graph itself.

It is what happens when disconnected engineering events become connected knowledge.

A pull request stops being just a pull request.

It becomes part of a chain:

Someone changed a file for a reason, another engineer reviewed it, and several other files were repeatedly involved in related changes.

Once those relationships exist, you can ask better questions.

You can onboard faster.

You can find the right person before making a risky change.

You can preserve context that would otherwise disappear into GitHub history.

And eventually, you can give AI systems something they usually lack:

A structured understanding of how the software actually fits together.

What critical engineering knowledge is your team losing right now? See what Helix reveals →

Graph Engineering: The Missing Architecture Behind Useful AI

Bobby Hall Jr — Fri, 21 Aug 2026 11:35:00 +0000

Most AI applications are built around a simple idea:

Give a model enough information, ask a good question, and hope it figures everything out.

Sometimes that works.

But once you start building agents, copilots, or enterprise AI products, you hit a predictable problem: the model can retrieve information, but it struggles to understand how that information fits together.

A pull request mentions a feature flag. A Slack thread explains why it exists. An incident reveals what happens when it fails. A Jira ticket documents the original requirement.

Individually, those artifacts are useful.

Together, they tell a story.

The problem is that most AI architectures treat them as isolated chunks of text.

Graph engineering is how we reconnect the story.

What Is Graph Engineering?
Why Traditional RAG Hits a Ceiling
Graphs Preserve the Relationships AI Needs
Graph Engineering Is Not Just Picking a Graph Database
Building an Engineering Graph
- Define the Core Entities
- Define Relationships
- Attach Evidence to Relationships
- Model Time Explicitly
- Combine Graph Traversal With Semantic Search
Where Graph Engineering Becomes Valuable
- Engineering Intelligence
- AI Agents
- Customer Intelligence
The Hard Parts Nobody Puts in the Demo
- Entity Resolution
- Relationship Extraction
- Access Control
- Freshness
- Query Explosion
A Practical Starting Point
The Bigger Shift

What Is Graph Engineering?

Graph engineering is the practice of designing systems around entities and the relationships between them.

Instead of representing information as disconnected documents, you explicitly model the structure of a domain.

A graph contains:

Nodes: Things that exist, such as services, pull requests, incidents, engineers, and documents.
Edges: Relationships between those things.
Properties: Metadata describing nodes and edges.
Temporal context: Information about when relationships formed, changed, or expired.

For example:

type EngineeringNode =
  | { type: "service"; id: string; name: string }
  | { type: "pull_request"; id: string; title: string }
  | { type: "incident"; id: string; severity: string }
  | { type: "engineer"; id: string; name: string };

type EngineeringEdge = {
  sourceId: string;
  targetId: string;
  relationship:
    | "OWNS"
    | "MODIFIED"
    | "DEPENDS_ON"
    | "CAUSED"
    | "RESOLVED";
  createdAt: Date;
  confidence?: number;
};

These structures make relationships queryable.

Instead of asking:

Which documents mention the payments service?

You can ask:

Which recent changes affected services that depend on payments, and have any of those services been involved in incidents?

That is a different category of question.

It requires connected reasoning, not just text similarity.

Why Traditional RAG Hits a Ceiling

Retrieval-augmented generation typically follows this workflow:

Break documents into chunks.
Convert each chunk into an embedding.
Store embeddings in a vector database.
Retrieve chunks similar to the user’s question.
Pass those chunks to a language model.

This architecture is useful, especially when the goal is to find relevant passages.

But similarity is not the same thing as understanding.

Imagine asking:

Is it safe to remove this Redis cache?

A conventional RAG system might retrieve:

A pull request introducing Redis.
Documentation mentioning caching.
An incident involving timeouts.
A Slack discussion about checkout performance.

Those documents may contain the answer.

But the system still has to infer how they relate.

Did the cache prevent the timeout? Was the incident before or after Redis was introduced? Does checkout still depend on it? Did a later architecture change make it obsolete?

If those connections are not modeled, the language model has to reconstruct them from whatever happens to fit inside its context window.

Sometimes it gets there.

Sometimes it confidently tells you to delete production infrastructure.

That is not exactly the kind of excitement we want.

Graphs Preserve the Relationships AI Needs

Now imagine representing the same information as connected entities:

A pull request introduced the Redis cache.
The Redis cache supports the checkout service.
A timeout incident affected the checkout service.
The pull request responded to that incident.
The checkout service depends on the Payments API.
An engineer authored the original change.

In TypeScript, those connections might look like this:

const engineeringGraph = {
  nodes: [
    { id: "cache:redis-checkout", type: "cache" },
    { id: "service:checkout", type: "service" },
    { id: "service:payments", type: "service" },
    { id: "pr:482", type: "pull_request" },
    { id: "incident:52", type: "incident" },
    { id: "engineer:bobby", type: "engineer" },
  ],
  edges: [
    {
      source: "pr:482",
      relationship: "INTRODUCED",
      target: "cache:redis-checkout",
    },
    {
      source: "cache:redis-checkout",
      relationship: "SUPPORTS",
      target: "service:checkout",
    },
    {
      source: "incident:52",
      relationship: "AFFECTED",
      target: "service:checkout",
    },
    {
      source: "pr:482",
      relationship: "RESPONDED_TO",
      target: "incident:52",
    },
    {
      source: "service:checkout",
      relationship: "DEPENDS_ON",
      target: "service:payments",
    },
    {
      source: "engineer:bobby",
      relationship: "AUTHORED",
      target: "pr:482",
    },
  ],
};

The AI system no longer has to guess whether these artifacts are related.

The relationships are part of the data model.

It can traverse the graph, inspect the evidence, and produce an answer such as:

The Redis cache was introduced after checkout timeouts caused by repeated calls to the Payments API. Checkout still depends on the cache, and no later change has replaced that behavior. Removing it could increase latency and recreate the original failure condition.

More importantly, every part of that answer can point back to supporting evidence.

That is what makes a graph useful: not prettier storage, but better reasoning and explainability.

Graph Engineering Is Not Just Picking a Graph Database

One common mistake is treating graph engineering as a storage decision.

It is not.

You can represent graphs using:

PostgreSQL tables.
Recursive SQL queries.
Graph databases.
Search indexes.
Application-layer adjacency lists.
Hybrid architectures combining several approaches.

The hard part is deciding:

Which entities matter?
Which relationships are meaningful?
Where does each relationship come from?
How confident are we that it is correct?
How do we handle relationships that change over time?
How do we resolve duplicate identities across systems?
What evidence supports each connection?

A graph database does not answer those questions for you.

Graph engineering is the discipline of designing the answers.

Building an Engineering Graph

Let’s make this concrete.

Suppose you want to build an AI assistant that helps engineers understand an unfamiliar codebase.

Your data sources might include GitHub, Slack, Jira, deployment logs, and incident reports.

1. Define the Core Entities

Start with the objects engineers already reason about:

type NodeType =
  | "repository"
  | "file"
  | "service"
  | "pull_request"
  | "commit"
  | "deployment"
  | "incident"
  | "ticket"
  | "engineer"
  | "conversation";

Keep the initial schema narrow.

You do not need to model every conceivable object before the system becomes useful.

Pick the questions you want to answer first, then model the entities required to answer them.

2. Define Relationships

Relationships capture how engineering work actually happens.

type RelationshipType =
  | "AUTHORED"
  | "REVIEWED"
  | "MODIFIED"
  | "MENTIONS"
  | "DEPENDS_ON"
  | "DEPLOYED"
  | "TRIGGERED"
  | "RESOLVED"
  | "DISCUSSED_IN"
  | "IMPLEMENTS";

For example:

const relationships = [
  {
    source: "engineer:bobby",
    relationship: "AUTHORED",
    target: "pr:482",
  },
  {
    source: "pr:482",
    relationship: "MODIFIED",
    target: "service:checkout",
  },
  {
    source: "pr:482",
    relationship: "IMPLEMENTS",
    target: "ticket:ENG-913",
  },
  {
    source: "incident:52",
    relationship: "DISCUSSED_IN",
    target: "conversation:slack-incident-52",
  },
];

Now the assistant can connect a code change to its author, its business requirement, and the services it affected.

3. Attach Evidence to Relationships

Relationships should not exist simply because a model thought they sounded plausible.

A stronger graph stores evidence for every important edge.

type Evidence = {
  source: "github" | "slack" | "jira" | "deployment_log";
  reference: string;
  excerpt?: string;
  observedAt: Date;
};

type GraphRelationship = {
  sourceId: string;
  targetId: string;
  type: RelationshipType;
  confidence: number;
  evidence: Evidence[];
};

For example:

const deploymentIncidentRelationship: GraphRelationship = {
  sourceId: "deployment:2026-08-20-14-32",
  targetId: "incident:52",
  type: "TRIGGERED",
  confidence: 0.91,
  evidence: [
    {
      source: "deployment_log",
      reference: "deployments/2026-08-20-14-32",
      excerpt: "Checkout latency increased after deployment.",
      observedAt: new Date("2026-08-20T14:36:00Z"),
    },
    {
      source: "slack",
      reference: "incident-channel/message/8831",
      excerpt: "Errors started immediately after the checkout rollout.",
      observedAt: new Date("2026-08-20T14:38:00Z"),
    },
  ],
};

This matters because causation is often uncertain.

A deployment happening before an incident does not prove it caused the incident.

Good graph engineering distinguishes observation from inference and preserves confidence accordingly.

4. Model Time Explicitly

Software systems evolve.

An engineer who owned a service last year may not own it today. A dependency may have been removed. A workaround may no longer be necessary.

Without time, graphs become confidently outdated.

type TemporalRelationship = GraphRelationship & {
  validFrom: Date;
  validUntil?: Date;
};

This lets you ask questions such as:

const query = {
  question: "Who owned checkout when incident 52 happened?",
  at: new Date("2026-08-20T14:35:00Z"),
};

That is different from asking who owns checkout today.

The distinction matters during incident reviews, compliance investigations, and architecture analysis.

5. Combine Graph Traversal With Semantic Search

Graphs and vector search solve different problems.

Semantic search helps answer:

Which documents discuss checkout latency?

Graph traversal helps answer:

Which services depend on checkout, which deployments modified those services, and which incidents followed?

The strongest architecture often combines both.

async function answerEngineeringQuestion(question: string) {
  const semanticMatches = await vectorSearch(question);

  const entityIds = await extractEntities({
    question,
    documents: semanticMatches,
  });

  const graphContext = await graph.expand({
    nodeIds: entityIds,
    relationships: [
      "DEPENDS_ON",
      "MODIFIED",
      "TRIGGERED",
      "RESOLVED",
    ],
    maxDepth: 2,
  });

  const evidence = await rankEvidence({
    question,
    documents: semanticMatches,
    graph: graphContext,
  });

  return generateAnswer({
    question,
    graphContext,
    evidence,
    requireCitations: true,
  });
}

Semantic retrieval finds relevant information.

Graph traversal supplies structure.

The model turns both into an explanation.

Where Graph Engineering Becomes Valuable

Graph-based architectures are especially useful when the answer depends on relationships across multiple systems.

Engineering Intelligence

An engineering graph can connect:

Pull requests to tickets.
Deployments to incidents.
Services to dependencies.
Code ownership to subject-matter expertise.
Architecture decisions to the discussions that produced them.

That enables questions like:

Why does this service exist?

What might break if I change this function?

Who understands this part of the system?

Which release introduced the behavior customers are reporting?

This is the difference between searching your engineering history and actually understanding it.

AI Agents

Agents need more than a prompt and a toolbelt.

They need to understand:

Who owns a task.
Which systems they can access.
What dependencies block execution.
Which decisions require approval.
How prior actions affected the current state.

A graph can represent those relationships explicitly, allowing agents to operate within a defined business context.

type AgentContext = {
  employeeId: string;
  assignedWorkflows: string[];
  availableTools: string[];
  approvalPolicyId: string;
  relevantContacts: string[];
};

When this context comes from a graph, the agent can discover connections dynamically instead of relying on a giant, fragile system prompt.

For example:

async function buildAgentContext(employeeId: string) {
  const assignments = await graph.findNeighbors({
    nodeId: employeeId,
    relationship: "ASSIGNED_TO",
  });

  const tools = await graph.findNeighbors({
    nodeId: employeeId,
    relationship: "AUTHORIZED_TO_USE",
  });

  const approvalPolicies = await graph.findNeighbors({
    nodeId: employeeId,
    relationship: "GOVERNED_BY",
  });

  return {
    assignments,
    tools,
    approvalPolicies,
  };
}

The agent’s behavior now reflects relationships defined elsewhere in the system.

Change the graph, and the available context changes with it.

Customer Intelligence

A customer graph might connect:

Accounts.
Users.
Support tickets.
Product activity.
Contracts.
Renewal dates.
Sales conversations.

Now an AI assistant can explain not just that an account is at risk, but why:

This customer has an upcoming renewal, declining product usage, three unresolved support tickets, and a recent conversation expressing concern about reporting features.

That answer comes from relationships, not keyword overlap.

The Hard Parts Nobody Puts in the Demo

Graph engineering sounds clean on a whiteboard.

Production is messier.

Entity Resolution

The same person might appear as:

bobby@company.com
bobbyhalljr
Bobby Hall
@bobby

Are those the same person?

Sometimes yes. Sometimes absolutely not.

You need identity mapping, confidence scores, and correction mechanisms.

A basic identity model might look like this:

type IdentityRecord = {
  canonicalId: string;
  source: "github" | "slack" | "jira";
  externalId: string;
  email?: string;
  displayName?: string;
  confidence: number;
};

If identity resolution is wrong, every relationship downstream becomes less trustworthy.

Relationship Extraction

Some edges are explicit.

A GitHub API can tell you who authored a pull request.

Other edges require interpretation.

A Slack conversation might imply that a deployment contributed to an incident without ever stating it directly.

Those inferred relationships should be marked differently from directly observed facts.

type RelationshipOrigin = "observed" | "inferred";

type VerifiedRelationship = GraphRelationship & {
  origin: RelationshipOrigin;
  reviewedBy?: string;
};

Your users should be able to tell the difference between:

GitHub records Bobby as the author.

And:

The system inferred that this deployment contributed to the incident.

Those are not equally reliable claims.

Access Control

If an employee cannot access a private document, the AI system should not reveal information derived from that document through a graph traversal.

Permissions have to travel with the underlying data.

Otherwise, your intelligent knowledge layer becomes a very creative data leak.

type PermissionAwareEvidence = Evidence & {
  allowedUsers?: string[];
  allowedGroups?: string[];
  visibility: "public" | "internal" | "restricted";
};

function canAccessEvidence(
  evidence: PermissionAwareEvidence,
  userId: string,
  groups: string[],
): boolean {
  if (evidence.visibility === "public") {
    return true;
  }

  if (evidence.allowedUsers?.includes(userId)) {
    return true;
  }

  return (
    evidence.allowedGroups?.some((group) =>
      groups.includes(group),
    ) ?? false
  );
}

In a real system, permission checks should apply to nodes, edges, evidence, retrieval results, and generated answers.

Filtering only at the final step is not enough if restricted information influenced the output.

Freshness

A graph is only useful when it reflects reality closely enough for the decisions it supports.

That means designing for:

Incremental updates.
Deleted or changed source records.
Webhook ingestion.
Periodic reconciliation.
Relationship expiration.
Auditing and observability.

For example:

type GraphSyncEvent = {
  source: "github" | "slack" | "jira";
  eventType: "created" | "updated" | "deleted";
  entityId: string;
  occurredAt: Date;
};

async function handleGraphSync(event: GraphSyncEvent) {
  if (event.eventType === "deleted") {
    await graph.expireNode(event.entityId);
    return;
  }

  const sourceRecord = await fetchSourceRecord(
    event.source,
    event.entityId,
  );

  await graph.upsertNode(sourceRecord);
  await graph.refreshRelationships(sourceRecord);
}

The goal is not perfect real-time synchronization at all costs.

The goal is to keep the graph fresh enough for the decisions users make with it.

Query Explosion

Graphs can become expensive to traverse.

Following every relationship several levels deep can quickly produce huge, noisy neighborhoods.

Useful systems constrain traversal based on:

Relationship type.
Time window.
Confidence.
Permissions.
Query intent.
Maximum depth.

type TraversalOptions = {
  startingNodeIds: string[];
  relationshipTypes: RelationshipType[];
  maxDepth: number;
  minimumConfidence: number;
  createdAfter?: Date;
};

const options: TraversalOptions = {
  startingNodeIds: ["service:checkout"],
  relationshipTypes: [
    "DEPENDS_ON",
    "MODIFIED",
    "TRIGGERED",
  ],
  maxDepth: 2,
  minimumConfidence: 0.8,
  createdAfter: new Date("2026-01-01"),
};

More context is not automatically better context.

A useful graph answers the question without dragging the entire organization into the prompt.

A Practical Starting Point

If you are building an AI product today, you probably do not need to launch with an enterprise knowledge graph.

Start smaller.

Choose three questions your users actually care about.

For an engineering assistant:

Why was this code changed?
What systems depend on it?
Who can help me understand it?

Then model only the entities and relationships needed to answer those questions.

A simple PostgreSQL schema might be enough:

CREATE TABLE graph_nodes (
  id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  properties JSONB NOT NULL DEFAULT '{}',
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE graph_edges (
  id TEXT PRIMARY KEY,
  source_id TEXT NOT NULL REFERENCES graph_nodes(id),
  target_id TEXT NOT NULL REFERENCES graph_nodes(id),
  relationship_type TEXT NOT NULL,
  confidence DOUBLE PRECISION NOT NULL DEFAULT 1.0,
  evidence JSONB NOT NULL DEFAULT '[]',
  valid_from TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  valid_until TIMESTAMPTZ
);

CREATE INDEX graph_edges_source_idx
  ON graph_edges (source_id);

CREATE INDEX graph_edges_target_idx
  ON graph_edges (target_id);

CREATE INDEX graph_edges_relationship_idx
  ON graph_edges (relationship_type);

With that foundation, you can begin querying direct relationships:

SELECT
  edge.relationship_type,
  target.id,
  target.type,
  target.properties
FROM graph_edges AS edge
JOIN graph_nodes AS target
  ON target.id = edge.target_id
WHERE edge.source_id = 'service:checkout'
  AND edge.valid_until IS NULL;

You can also explore dependencies recursively:

WITH RECURSIVE dependency_graph AS (
  SELECT
    source_id,
    target_id,
    relationship_type,
    1 AS depth
  FROM graph_edges
  WHERE source_id = 'service:checkout'
    AND relationship_type = 'DEPENDS_ON'
    AND valid_until IS NULL

  UNION ALL

  SELECT
    edge.source_id,
    edge.target_id,
    edge.relationship_type,
    dependency_graph.depth + 1
  FROM graph_edges AS edge
  INNER JOIN dependency_graph
    ON edge.source_id = dependency_graph.target_id
  WHERE edge.relationship_type = 'DEPENDS_ON'
    AND edge.valid_until IS NULL
    AND dependency_graph.depth < 3
)
SELECT *
FROM dependency_graph;

For production systems, add cycle detection and tenant-aware access controls before relying on recursive traversal.

You can build a surprising amount without introducing another database into your infrastructure.

The important thing is not whether you adopt a graph database on day one.

It is whether your architecture preserves the relationships your application needs to reason about.

The Bigger Shift

For years, software systems have been good at recording events.

A commit happened.

A ticket was created.

A deployment shipped.

An incident occurred.

But recording an event is not the same as understanding its significance.

The value emerges when those events are connected:

This deployment changed a service that depends on a fragile integration, which caused an incident similar to one that occurred six months ago, and the engineer who previously resolved it now works on another team.

That is the difference between stored information and operational understanding.

As AI systems become responsible for more meaningful work, that difference will matter more.

The future is not just models with larger context windows.

It is systems that understand what information means, how it relates, and why it matters.

That is graph engineering.

What critical engineering knowledge is your team losing right now? See what Helix reveals →

Building a Dynamic Prompt Engine for an AI SaaS - TaxJoy (Next.js + Vercel AI SDK)

Bobby Hall Jr — Sun, 27 Apr 2025 14:07:27 +0000

Building a Dynamic Prompt Engine for an AI SaaS (Next.js + Vercel AI SDK)

When we started building TaxJoy — an AI-powered tax assistant for CPAs — I thought prompt design would be simple.

It wasn’t.

As soon as we added multiple user types (CPAs and their clients), different workflows (intake forms, tax document summaries, audit checks), and various tones (professional, approachable, reassuring)…
one static system prompt quickly became a giant bottleneck.

That’s when we realized:

We needed a dynamic, scalable prompt engine.

Here’s how we designed and implemented it.

⸻

The Problem: Static Prompts Don’t Scale

In early versions of TaxJoy, our AI chat engine worked fine with a basic hardcoded system prompt.

But as features grew, real-world demands surfaced:

CPAs needed precise, technical responses.
Clients needed simpler, friendlier explanations.
Intake forms needed directive prompts (“Request W-2s, dependents, 1099s”).
Summarizations needed structured, analytical outputs.

One giant "catch-all" prompt?

Impossible to manage cleanly.

Every small change risked breaking something else.

⸻

The Solution: Dynamic Prompt Injection

We built a centralized Prompt Engine inside TaxJoy to dynamically generate prompts based on:

✅ User role (CPA or Client)

✅ Current intent (Chat, Fill Forms, Summarize, Validate)

✅ Optional tone (Approachable, Professional, Reassuring)

Every AI call dynamically injects a fresh, context-specific system prompt — based on clean, structured parameters.

Simple inputs → Controlled, scalable AI behavior.

⸻

System Architecture Overview

Directory Structure:

/app
  /api
    /chat
      route.ts
/lib
  /prompt-engine
    index.ts
    prompts.ts
/db
  schema.ts

High Level Flow:

Client or CPA interacts with AI assistant.
Frontend sends role, intent, and optional tone to backend /api/chat/route.ts.
Backend dynamically generates the system prompt using /lib/prompt-engine/index.ts.
Backend calls streamText() from Vercel AI SDK with the injected prompt.

Visual Diagram: (explained in text)

User (CPA or Client)
    ↓
Frontend (Next.js App Router)
    ↓
/api/chat/route.ts
    ↓
/lib/prompt-engine/index.ts → Generates prompt
    ↓
Vercel AI SDK → LLM Response

⸻

Implementation Details

1. Define Roles, Intents, and Tones

// /lib/prompt-engine/prompts.ts

export type Role = 'cpa' | 'client';
export type Intent = 'chat' | 'fill' | 'summarize' | 'validate';
export type Tone = 'approachable' | 'professional' | 'reassuring';

2. Generate Dynamic Prompts

// /lib/prompt-engine/index.ts

import { Role, Intent, Tone } from './prompts';

interface GeneratePromptParams {
  role: Role;
  intent: Intent;
  tone?: Tone;
}

export function generatePrompt({ role, intent, tone }: GeneratePromptParams): string {
  if (role === 'cpa') {
    switch (intent) {
      case 'fill':
        return "Assist the CPA by filling tax forms based on client data. Be precise and technical.";
      case 'summarize':
        return "Summarize uploaded tax documents for CPA review. Be structured and professional.";
      default:
        return "Answer CPA tax preparation questions clearly and concisely.";
    }
  }

  if (role === 'client') {
    switch (intent) {
      case 'fill':
        return "Guide the client through uploading and filling tax documents. Be friendly and reassuring.";
      case 'summarize':
        return "Summarize the client's documents in simple terms they can understand.";
      default:
        return "Answer client tax questions in an approachable, simple manner.";
    }
  }

  return "You are a helpful AI assistant guiding users through tax preparation.";
}

3. Inject Prompt During AI SDK Call

// /app/api/chat/route.ts

import { generatePrompt } from '@/lib/prompt-engine';

export async function POST(req: Request) {
  const { role, intent, tone, messages, model } = await req.json();

  const systemPrompt = generatePrompt({ role, intent, tone });

  const result = await streamText({
    model,
    system: systemPrompt,
    messages,
  });

  return new Response(result);
}

⸻

Why We Chose This Architecture

✅ Single source of truth for prompts — Easy updates without touching multiple places.
✅ Role/intent-driven control — Maintain high-quality responses across different workflows.
✅ Extensible — Easy to add new roles (e.g., "admin"), intents (e.g., "audit check"), or tones later.
✅ Scales cleanly — No brittle if/else chains scattered in business logic.

⸻

Challenges We Hit

Deciding how "granular" prompts should be per task (we kept it lean: 4 core intents to start).
Balancing human-readable prompt writing vs. overly abstract generation.
Dealing with context switching: sometimes CPAs shift roles mid-convo (solution: refresh prompt by intent per major tool call).

⸻

Lessons Learned

Treat prompts like software, not static content. Modular, version-controlled, testable.
Start lean, expand later. Role + intent solved 90% of problems. Tone handling came only after user feedback.
Prompt engineering is architecture, not just writing. Think scaling, not just "better words."

⸻

If You're Building an AI SaaS...

Whether it’s taxes, healthcare, legal, or customer support:

The smarter your prompt system architecture, the smarter your entire product feels.

Don’t treat your LLM like a magic black box.

Treat it like a smart intern who needs perfect instructions — customized for the user and the moment.

That’s what dynamic prompting unlocks.

⸻

Want to See This in Action?

We’re launching TaxJoy early access —
an AI-powered tax assistant helping CPAs save 40+ hours per month during tax season.

Follow my journey: https://linkedin.com/in/bobbyhalljr

Or DM me if you’re curious how we’re scaling AI workflows in production.

Mastering OpenAI’s new Agents SDK & Responses API [Part 1]

Bobby Hall Jr — Wed, 12 Mar 2025 01:53:05 +0000

Welcome to part 1

A few months ago, I was buried in a complex automation project, trying to make AI agents more independent. The problem? They needed too much hand-holding. Every action required a human prompt, making automation feel… not so automated.

Then OpenAI dropped their Agents SDK and Responses API—a game-changer for developers like me who want AI to actually do things instead of just responding passively. These tools give you the power to build autonomous, tool-using AI agents that can search the web, retrieve files, and even call external APIs without constant human input.

So, if you’ve been dreaming of building AI systems that can think and act independently, this guide is for you. Let’s break it all down.

What is OpenAI’s Agents SDK?

Think of the Agents SDK as a toolkit for building AI that can use tools and make decisions. It lets your AI agent:

✅ Perform multi-step tasks (without you holding its hand).

✅ Integrate with external tools (web search, API calls, databases).

✅ Autonomously decide which tool to use and when (based on context).

Example: Imagine you’re an accountant using an AI tax assistant. Instead of just answering questions, the AI could:

Pull real-time tax law updates from a government database.
Analyze financial statements by calling a bookkeeping API.
Generate reports based on the latest data.

Before the Agents SDK, making this happen was a mess of manual API calls and complex logic. Now? It’s built-in.

Getting Started with the Agents SDK

1. Install the SDK

First, clone the repo and install dependencies:

git clone https://github.com/openai/agent-sdk.git
cd agent-sdk
pip install -r requirements.txt

2. Set Up Your Agent

Define what tools your AI can use. Let’s say we want to enable web search and file retrieval:

from agent_sdk import Agent, WebSearchTool, FileRetrievalTool

search_tool = WebSearchTool(api_key="your_api_key")
file_tool = FileRetrievalTool()

agent = Agent(tools=[search_tool, file_tool])

Now your agent knows how to search the web and fetch documents.

3. Let It Make Decisions

Unlike traditional chatbots, this AI decides which tool to use based on user input:

def agent_task(query):
    result = agent.use_tool("web_search", query)
    return result

response = agent_task("Latest AI research papers")
print(response)

No manual intervention—just autonomous execution.

What is the OpenAI Responses API?

The Responses API is all about improving how AI interacts with users.

It lets your AI:

✅ Call functions dynamically (e.g., fetch weather updates, book appointments).

✅ Return structured responses instead of random text.

✅ Stream responses in real-time for a smoother user experience.

Think of it as giving your AI a better interface to talk to the world.

Building a Smarter AI with the Responses API

1. Set Up API Authentication

You’ll need your OpenAI API key:

import openai

openai.api_key = "your_api_key"

2. Define Functions Your AI Can Call

Let’s say we want the AI to fetch the weather when asked:

functions = [
    {
        "name": "get_current_weather",
        "description": "Retrieves the current weather for a specified location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g., San Francisco, CA.",
                },
            },
            "required": ["location"],
        },
    }
]

3. Make an API Request

Your AI will now recognize when it needs to call a function:

response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What’s the weather like in New York?"},
    ],
    functions=functions,
    function_call="auto",
)

4. Execute the Function When Called

If the AI determines it needs to fetch the weather, it will trigger the function:

if "function_call" in response["choices"][0]["message"]:
    function_name = response["choices"][0]["message"]["function_call"]["name"]
    arguments = response["choices"][0]["message"]["function_call"]["arguments"]

    if function_name == "get_current_weather":
        location = arguments.get("location")
        weather_info = get_current_weather(location)  # Custom function
        messages.append({"role": "function", "name": function_name, "content": weather_info})

        # Send updated response back to OpenAI
        response = openai.ChatCompletion.create(
            model="gpt-4",
            messages=messages,
        )

Now, instead of just saying “I don’t know”, your AI will fetch the latest weather and respond intelligently.

Why Does This Matter?

Before these updates, most AI systems were passive—they just answered questions based on text input. Now, with the Agents SDK and Responses API, you can build AI that actually takes action.

Real-World Use Cases

AI-Powered Accounting → Automate bookkeeping, fetch tax laws, and generate reports.
Customer Support → AI can call APIs to check order statuses or resolve support tickets.
Automated Research Assistants → Fetch the latest market trends, financial data, or legal updates.
AI Chatbots for Business → Let customers book appointments, check product availability, or retrieve invoices without human help.

This is the future of AI—AI that does, not just talks.

Final Thoughts: Why You Should Start Now

If you’re serious about building next-gen AI applications, learning to use OpenAI’s Agents SDK and Responses API is a must.

With these tools, you can:

✅ Make AI truly autonomous → No more manually triggering actions.

✅ Build AI-powered assistants → Capable of fetching, analyzing, and acting on real-world data.

✅ Create smarter, interactive apps → That can use tools, call APIs, and respond dynamically.

The best part? You can start right now.

🚀 Install the Agents SDK, experiment with the Responses API, and start building the future of AI.

https://openai.github.io/openai-agents-python/

Stay tuned for part 2

Want More AI Development Tips?

I write about AI agents, automation, and building next-gen AI-powered applications.

📩 Subscribe to my newsletter for deep dives, tutorials, and real-world AI implementation strategies.

https://bobbyhalljr.dev/newsletter

Building an AI Agent with LangGraph, TypeScript, Next.js, TailwindCSS, and Pinecone – Part 2

Bobby Hall Jr — Mon, 17 Feb 2025 21:06:35 +0000

Introduction

In Part 1, we built a simple AI-powered assistant using LangGraph, Next.js, TailwindCSS, and Pinecone. Our AI agent could process user queries, retrieve relevant knowledge from Pinecone, and generate responses using OpenAI’s GPT model.

Now, in Part 2, we’ll enhance our AI agent by adding multi-agent workflows, contextual memory, and real-time conversation capabilities. By the end of this tutorial, you’ll have a more advanced AI assistant that can handle ongoing interactions dynamically.

Enhancements & Features in Part 2

✅ Multi-Agent Workflow – Implementing additional AI agents for different tasks.

✅ Long-Term Memory – Storing past interactions in Pinecone for context-aware conversations.

✅ Real-Time Conversation UI – Improving the chat experience with live responses.

✅ API Call Capabilities – Allowing AI agents to fetch data from external sources.

Step 1: Implementing Multi-Agent Workflows with LangGraph

AI agents often need to delegate tasks to specialized agents. For example, one agent may handle general queries, while another focuses on document analysis or data retrieval.

1. Modify the AI Agent Workflow in LangGraph

Create a new file /lib/multiAgentGraph.ts:

import { OpenAI } from "openai";
import { Pinecone } from "@pinecone-database/pinecone";
import { Graph, Node, Edge } from "langgraph";

type AIContext = { query: string; response: string; memory: string[] };

const openai = new OpenAI(process.env.NEXT_PUBLIC_OPENAI_API_KEY!);
const pinecone = new Pinecone({
  apiKey: process.env.NEXT_PUBLIC_PINECONE_API_KEY!,
  environment: process.env.NEXT_PUBLIC_PINECONE_ENVIRONMENT!,
});

const aiGraph = new Graph<AIContext>();

// General Query Agent
const generalAgent = new Node(async (ctx) => {
  const response = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: ctx.query }],
  });
  ctx.response = response.choices[0].message.content;
});

// Memory Storage Agent
const memoryAgent = new Node(async (ctx) => {
  const vectorStore = pinecone.index(process.env.NEXT_PUBLIC_PINECONE_INDEX!);
  await vectorStore.upsert([{ id: Date.now().toString(), values: ctx.query }]);
  ctx.memory.push(ctx.query);
});

aiGraph.addNode("General Query Agent", generalAgent);
aiGraph.addNode("Memory Agent", memoryAgent);
aiGraph.addEdge(new Edge("Start", "General Query Agent"));
aiGraph.addEdge(new Edge("General Query Agent", "Memory Agent"));

export { aiGraph };

This setup ensures that every user query is processed by the General Query Agent and stored for future reference in Pinecone.

Step 2: Upgrading the API to Support Contextual Conversations

Update /pages/api/ask.ts to retrieve memory and allow AI to recall past interactions:

import { NextApiRequest, NextApiResponse } from "next";
import { aiGraph } from "../../lib/multiAgentGraph";
import { Pinecone } from "@pinecone-database/pinecone";

const pinecone = new Pinecone({
  apiKey: process.env.NEXT_PUBLIC_PINECONE_API_KEY!,
  environment: process.env.NEXT_PUBLIC_PINECONE_ENVIRONMENT!,
});

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== "POST") return res.status(405).json({ error: "Method Not Allowed" });

  const { query } = req.body;
  if (!query) return res.status(400).json({ error: "Missing query" });

  const vectorStore = pinecone.index(process.env.NEXT_PUBLIC_PINECONE_INDEX!);
  const previousContext = await vectorStore.query({ topK: 5, query });
  const memory = previousContext.matches.map((match) => match.id);

  const context = { query, response: "", memory };
  await aiGraph.run(context);

  return res.json({ response: context.response });
}

Now, our AI agent can retrieve previous interactions, making conversations more natural and contextual.

Step 3: Enhancing the Frontend UI for Real-Time Chat

We’ll modify our chat interface to display AI responses dynamically.

Update `pages/index.tsx`

import { useState } from "react";

export default function Home() {
  const [query, setQuery] = useState("");
  const [conversation, setConversation] = useState<{ user: string; ai: string }[]>([]);

  const handleSubmit = async () => {
    const res = await fetch("/api/ask", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query }),
    });
    const data = await res.json();
    setConversation([...conversation, { user: query, ai: data.response }]);
    setQuery("");
  };

  return (
    <div className="container mx-auto p-6">
      <h1 className="text-2xl font-bold">AI Agent Chat</h1>
      <div className="chat-box mt-4 p-4 border rounded">
        {conversation.map((msg, index) => (
          <div key={index} className="mt-2">
            <p className="text-blue-600">User: {msg.user}</p>
            <p className="text-gray-700">AI: {msg.ai}</p>
          </div>
        ))}
      </div>
      <input
        type="text"
        placeholder="Ask something..."
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        className="w-full p-2 border rounded mt-4"
      />
      <button onClick={handleSubmit} className="mt-4 bg-blue-500 text-white p-2 rounded">Ask</button>
    </div>
  );
}

Possible Enhancements:

✅ Implement external API integrations (e.g., fetching real-world data).

✅ Introduce multi-modal AI (support for images, voice, and documents).

✅ Deploy the AI agent on Vercel for production use.

✅ Improve UI/UX for a more interactive chat experience.

✅ Add personalized AI responses based on user profiles.

This AI-powered assistant is now ready for real-world applications like customer support, automation, and intelligent task execution. Ready to take it further? Let’s keep building! 💡

🔗 join the newsletter: https://bobbyhalljr.dev/newsletter

Building an AI Agent with LangGraph, TypeScript, Next.js, TailwindCSS, and Pinecone

Bobby Hall Jr — Sun, 16 Feb 2025 21:52:37 +0000

Introduction

AI agents are evolving beyond simple chatbots into powerful workflow orchestrators. In this guide, we'll build a fully functional AI agent using LangGraph, TypeScript, Next.js, TailwindCSS, and Pinecone for vector-based memory storage.

By the end of this tutorial, you'll have a working AI-powered assistant that can process user queries, retrieve knowledge from a Pinecone vector database, and dynamically generate responses.

Project Architecture

Tech Stack Overview

✅ LangGraph – To define AI workflows and agent orchestration.

✅ Next.js (TypeScript) – For the front-end and API layer.

✅ TailwindCSS – For UI styling.

✅ Pinecone – For vector-based memory storage and retrieval.

✅ OpenAI API – For LLM-based response generation.

Step 1: Setting Up the Project

1. Initialize the Next.js Project

npx create-next-app@latest ai-agent-app --typescript --tailwind --use-npm
cd ai-agent-app
npm install @pinecone-database/pinecone langgraph openai axios dotenv

2. Configure Pinecone for Vector Storage

Create a .env.local file and add:

NEXT_PUBLIC_OPENAI_API_KEY=your_openai_api_key
NEXT_PUBLIC_PINECONE_API_KEY=your_pinecone_api_key
NEXT_PUBLIC_PINECONE_ENVIRONMENT=your_pinecone_env
NEXT_PUBLIC_PINECONE_INDEX=your_pinecone_index

Step 2: Building the AI Agent Backend with LangGraph

1. Create LangGraph Workflow (`/lib/langgraph.ts`)

import { OpenAI } from "openai";
import { Pinecone } from "@pinecone-database/pinecone";
import { Graph, Node, Edge } from "langgraph";

type AIContext = { query: string; response: string };

const openai = new OpenAI(process.env.NEXT_PUBLIC_OPENAI_API_KEY!);
const pinecone = new Pinecone({
  apiKey: process.env.NEXT_PUBLIC_PINECONE_API_KEY!,
  environment: process.env.NEXT_PUBLIC_PINECONE_ENVIRONMENT!,
});

const aiGraph = new Graph<AIContext>();

// Define AI processing node
const aiNode = new Node(async (ctx) => {
  const vectorStore = pinecone.index(process.env.NEXT_PUBLIC_PINECONE_INDEX!);
  const results = await vectorStore.query({ topK: 5, query: ctx.query });

  const messages = [
    { role: "system", content: "You are an AI assistant." },
    { role: "user", content: `${ctx.query}\nRelevant Data: ${JSON.stringify(results)}` },
  ];

  const completion = await openai.chat.completions.create({
    model: "gpt-4",
    messages,
  });

  ctx.response = completion.choices[0].message.content;
});

aiGraph.addNode("AI Processing", aiNode);
aiGraph.addEdge(new Edge("Start", "AI Processing"));

export { aiGraph };

Step 3: Creating the Next.js API Route

Create a new API route in /pages/api/ask.ts:

import { NextApiRequest, NextApiResponse } from "next";
import { aiGraph } from "../../lib/langgraph";

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== "POST") return res.status(405).json({ error: "Method Not Allowed" });

  const { query } = req.body;
  if (!query) return res.status(400).json({ error: "Missing query" });

  const context = { query, response: "" };
  await aiGraph.run(context);

  return res.json({ response: context.response });
}

Step 4: Building the Frontend UI with TailwindCSS

Update the pages/index.tsx file:

import { useState } from "react";

export default function Home() {
  const [query, setQuery] = useState("");
  const [response, setResponse] = useState("");

  const handleSubmit = async () => {
    const res = await fetch("/api/ask", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query }),
    });
    const data = await res.json();
    setResponse(data.response);
  };

  return (
    <div className="container mx-auto p-6">
      <h1 className="text-2xl font-bold">AI Agent Chat</h1>
      <input
        type="text"
        placeholder="Ask a question..."
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        className="w-full p-2 border rounded mt-4"
      />
      <button onClick={handleSubmit} className="mt-4 bg-blue-500 text-white p-2 rounded">Ask</button>
      {response && <p className="mt-4 p-3 bg-gray-100 rounded">{response}</p>}
    </div>
  );
}

Final Steps: Running the AI Agent

1. Start the Next.js Server

npm run dev

2. Test the AI Agent

Open http://localhost:3000
Enter a query and see AI-powered responses with knowledge retrieval from Pinecone.

Conclusion & Next Steps

You now have a fully functional AI agent built with LangGraph, Pinecone, and Next.js! 🚀

Possible Enhancements:

✅ Add multi-agent workflows using LangGraph.

✅ Implement memory storage for better contextual conversations.

✅ Deploy to Vercel or a cloud-based API for scalability.

This AI-powered assistant can be extended to handle business automation, document analysis, and intelligent decision-making. Ready to take it further? Let’s build the future of AI together!

🔗 Stay updated with the latest AI projects—subscribe to my newsletter!

Here 👉🏽 https://bobbyhalljr.dev/newsletter

Random Image Generation and Caching in JavaScript

Bobby Hall Jr — Tue, 03 Dec 2024 03:26:06 +0000

Random Image Generation and Caching in JavaScript

In many web applications, it is common to display random images for various purposes such as placeholders, thumbnails, or visual content. However, generating random images for each request can be inefficient, especially if we want to reuse the same image multiple times. In this article, we'll explore how to generate random images efficiently using JavaScript and implement a caching mechanism to avoid redundant API calls.

The `getRandomImage` Function

The getRandomImage function is a utility function that generates a random image URL based on the provided width, height, and random ID. Let's take a closer look at how this function works:

const imageCache = {};

const getRandomImage = (width, height, randomId) => {
  const cacheKey = `${width}_${height}_${randomId}`;

  if (imageCache[cacheKey]) {
    return imageCache[cacheKey];
  }

  const imageUrl = `https://picsum.photos/${width}/${height}?random=${randomId}`;
  imageCache[cacheKey] = imageUrl;

  return imageUrl;
};

Let's break down the code step by step:

We create an empty object called imageCache to serve as our cache for storing the generated image URLs.
The getRandomImage function takes three parameters: width, height, and randomId. These parameters allow us to control the dimensions and uniqueness of the random image.
Inside the function, we generate a unique cache key by concatenating the width, height, and randomId values. This key will be used to store and retrieve the image URL from the cache.
We check if the image URL corresponding to the cache key already exists in the cache. If it does, we simply return the cached image URL instead of generating a new one.
If the image URL is not found in the cache, we proceed to generate a new URL using the picsum.photos API. This API provides random images of various dimensions based on the specified width, height, and random ID.
The newly generated image URL is then stored in the cache using the cache key for future use.
Finally, we return the generated image URL.

Benefits of Caching

Implementing a caching mechanism in the getRandomImage function offers several advantages:

Efficiency: By caching the image URLs, we avoid making redundant API calls for the same combination of width, height, and random ID. This improves the overall performance of our application and reduces unnecessary network requests.
Reuse: The caching mechanism allows us to reuse the same random image multiple times without regenerating a new image URL every time. This is particularly useful when displaying the same image across different sections or components of our application, promoting consistency and reducing unnecessary overhead.
Consistency: When the same combination of width, height, and random ID is encountered again, the function retrieves the image URL from the cache, ensuring consistency in the displayed images throughout the application.

Conclusion

In this article, we explored how to generate random images efficiently in JavaScript using the getRandomImage function. By implementing a caching mechanism, we can avoid redundant API calls and improve the performance of our web applications. The caching mechanism offers benefits such as improved efficiency, image reuse, and consistency. Feel free to adapt and incorporate the getRandomImage function into your projects to enhance the generation of random images.

Full Code:

const imageCache = {};

const getRandomImage = (width, height, randomId) => {
  const cacheKey = `${width}_${height}_${randomId}`;

  if (imageCache[cacheKey]) {
    return imageCache[cacheKey];


 }

  const imageUrl = `https://picsum.photos/${width}/${height}?random=${randomId}`;
  imageCache[cacheKey] = imageUrl;

  return imageUrl;
};

Remember to adapt the function and caching mechanism to suit your specific requirements and adjust the caching strategy if needed.

Subscribe to my newsletter where you will get tips, tricks and challenges to keep your skills sharp. Subscribe to newsletter

The Psychology Behind UI Design: Crafting Engaging User Experiences (Part 2)

Bobby Hall Jr — Mon, 08 Jan 2024 18:31:06 +0000

The Psychology Behind UI Design: Crafting Engaging User Experiences (Part 2)

Welcome back to our exploration of the captivating world of UI psychology. In this continuation, we will delve even deeper into the intricacies of user behavior and how UI design can shape and influence these interactions.

Microinteractions: The Subtle Art of Delight

Microinteractions are the small, often overlooked details that can make a big difference in user experience. Think about the satisfying "ping" sound when sending a message or the subtle color change when toggling a switch. These microinteractions contribute to user satisfaction and a sense of accomplishment.

// Code Example: Adding a microinteraction with JavaScript
const button = document.getElementById('submit-button');
button.addEventListener('click', () => {
  button.classList.add('clicked');
});

Personalization for a Tailored Experience

Personalization is a powerful psychological tool. Consider a music streaming app that curates playlists based on individual preferences. By providing a tailored experience, users feel a deeper connection with the application.

// Code Example: Personalizing recommendations in JavaScript
const userPreferences = getUserPreferences();
const recommendedSongs = getPersonalizedRecommendations(userPreferences);

Visual Storytelling in UI Design

Humans are wired to respond to stories. Visual storytelling in UI design involves using images, illustrations, or even animations to convey a narrative. Imagine an onboarding process that guides users through a story, making the learning experience more engaging and memorable.

<!-- Code Example: Using illustrations for visual storytelling -->
<div class="onboarding-step">
  <img src="onboarding-illustration.jpg" alt="Onboarding Illustration">
  <p>Follow the path to unlock exciting features!</p>
</div>

Social Proof: Building Trust Through Design

Integrating social proof elements, such as user reviews or testimonials, establishes trust. A travel website showcasing positive feedback and ratings encourages users to explore destinations with confidence.

<!-- Code Example: Displaying user reviews -->
<div class="user-review">
  <p>"Amazing experience! ⭐⭐⭐⭐⭐"</p>
  <p>- HappyTraveler123</p>
</div>

User Feedback and Iterative Design

Creating a feedback loop with users is crucial for continuous improvement. Features like tooltips or error messages guide users and provide real-time feedback, ensuring a smoother and more intuitive experience.

// Code Example: Implementing tooltips with JavaScript
const tooltipElement = document.getElementById('tooltip');
element.addEventListener('mouseover', () => {
  tooltipElement.style.display = 'block';
});

The Impact of Page Load Times on User Perception

User patience has its limits. Slow-loading pages can lead to frustration and a negative perception of your application. Optimizing images, leveraging browser caching, and minimizing server requests are key strategies for improving load times.

<!-- Code Example: Optimizing images for faster loading -->
<img src="optimized-image.jpg" alt="Optimized Image">

A/B Testing: Data-Driven Design Decisions

A/B testing involves comparing two versions of a design to determine which performs better. By collecting data on user interactions, designers can make informed decisions, refining and optimizing UI elements based on user preferences.

<!-- Code Example: Implementing A/B testing with analytics -->
<script>
  // Track user interactions and send data to analytics platform
  function trackInteraction(interactionType) {
    // Implementation details
  }
</script>

In conclusion, UI psychology is a multifaceted discipline that incorporates a myriad of elements, each playing a vital role in shaping user experiences. By delving into the intricacies of micro interactions, personalization, visual storytelling, social proof, feedback loops, page load times, and A/B testing, designers can craft interfaces that not only meet but exceed user expectations.

Embark on a journey to master the art of UI Psychology in development.

Sign up for my mini-course and you will learn how to:

Transform your interfaces into compelling user experiences.
Craft interfaces that resonate with your users.
Tailor your interfaces to user preferences.
Learn the art of creating adaptive UIs with UI Psychology.
Transform your interfaces with intuitive interactions
Master the art of gesture-based UI design.
Create interfaces that adapt to user behavior.

Enroll in my mini-course and you will learn the secrets of crafting contextual UIs with UI Psychology.

DEV Community: Bobby Hall Jr

I Let Grok Bot Apply to Software Engineering Jobs While I Was Sleeping

Table of Contents

The experiment

Grok Bot feels different because it has a computer

I didn't tell it "find me jobs"

The scoring system is what makes this useful

Memory might matter more than the model

The scary part isn't intelligence. It's permissions.

Then I scheduled it

This is bigger than Grok Bot

My Grok Bot review

Build an AI employee for your business

Your Code Knows What Changed. But Does It Know Why?

The Codebase Is Not the Whole System

Git Knows What Changed

The Hidden Knowledge Graph Inside Every Codebase

Why Relationships Matter

Give AI the Story, Not Just the Source File

Let's Build One

The Agent Should Query the Graph Before It Acts

The Agent Can Learn Without Retraining

But There's a Catch

Knowledge Needs Evidence

Not Everything Is Knowledge

Observation

Event

Outcome

Knowledge

Heuristic

And Failure Is Data Too

This Isn't RAG

Now Scale It Beyond One Repository

The Real Opportunity

The Four-Layer Architecture

Software Should Explain Itself

Your code has a history. Helix makes it understandable.

How to Build an AI Employee With a Knowledge Graph (Not Just Another Agent)

Table of Contents

1. Model the Work

2. Build the Graph

3. Add Events

4. Build the Agent Loop

5. Add Scheduling

6. Build a Tiny AI Employee

7. Put It Together

8. The Bigger Idea

The Takeaway

Try Roster

The Graph That Learns: Building Self-Improving Agent Loops

Table of Contents

The Problem With Stateless Agents

An Agent Is a Loop

The Missing Piece: Memory

Why a Graph Works Better Than a Blob of Memory

Building a Tiny Engineering Agent

Step 1: Define the Graph

Step 2: Add Agent Experience

Step 3: Build the Agent Loop

Step 4: Let the Agent Learn

Step 5: Use Experience on the Next Run

The Self-Improving Loop

But There Is a Dangerous Problem

Evidence Before Learning

Not All Memory Should Become Knowledge

Observation

Event

Outcome

Knowledge

Heuristic

Why This Is Different From RAG

The Graph Can Also Learn From Failure

A More Advanced Agent Loop

The Interesting Part: The Agent Becomes Better Without Retraining

The Graph Becomes an Organizational Memory

Where This Goes Next

Temporal Graphs

Confidence

Agent Performance

Human Feedback