The brain behind

I have 7,000 prompts, 88,000 tool calls, and 46,000 file ops sitting in ~/.claude/projects/ right now. I'm never going to read any of them again. That annoyed me enough that I built a brain to do it for me.

It didn't start as a product. It started as a sentence I wrote down on May 14th because I was tired of forgetting my own projects — and because Andrej Karpathy had just posted about his own "second brain" concept and I wanted to build something in that direction, based on what I already had lying around: my Claude Code sessions.

(The prompt is verbatim — half Danish, half English, the way it was actually typed. Translation would have stripped the texture that made it land.)

That was it. No API. No schema. No graph. Just an idea that the way I actually work — vibe-coded, half-finished, ten projects open at once — could be the input to a process that quietly distilled it into the kind of artefacts real projects have: ADRs, feature specs, a wiki, a bad-habits report about myself.

Start vibe, go pro

Anyone who has vibed their way through six months of AI-assisted development already knows: you start WAY too many things. Most die. The few that survive grow from "one evening's nonsense" into "I use this every day" without any formal moment where you decided that's what it would be.

The problem isn't that you lack documentation. The problem is that you've written it — across Claude sessions, in commit messages, in half-edited markdown files — without it ever consolidating. It sits in ~/.claude/projects/ as JSONL from every session, every prompt and every tool call, but in a form nobody is going to read again.

Pks brain is the attempt to harvest that documentation without making you behave like you're working on a "real" project. You vibe. The brain crunches in the background. When I open a project again three weeks later there's actually something I can read — without me having to write it.

What pks brain became

The original idea settled into five phases, each with its own command and its own checkpoint so any phase can be re-run independently:

pks brain ingest   →  deterministic dump of every session JSONL into
                      compact firehoses (prompts, tools, files, errors)
pks brain extract  →  AI-generated markdown summary per session
                      (driven by an editable `brain-extract` skill)
pks brain synth    →  clustering: thematic groups across sessions
pks brain wiki     →  per-cluster wiki pages generated from synthesis
pks brain adr      →  architectural clusters distilled into ADRs

The phase split is deliberate. Deterministic ingest is cheap and runs in 1–2 seconds; the AI-driven phases cost tokens and run only when you ask. pks brain refresh chains them for a full pass; the rest of the time you just re-run the one phase you need.

Output lives in two places:

• The user-scoped cross-project firehose under ~/.pks-cli/brain/ — every session across every project as one long stream of rows. The shared engine room.
• Project-local synthesis artefacts under ./.pks/brain/ inside each git repo — the wiki, the ADRs, the feature specs for this project. The public room where synthesis lands.

In this repo right now I have around 7,000 prompts, 88,000 tool calls, and 46,000 file ops in the firehose, against 2,940 AI-generated session extracts. Half a year of vibe-work, ready to be read by a model that isn't me.

The pivot: it turned out to be a graph

I didn't know that on May 14th. It only became clear here at the end of May — after a week working with product-cli, which uses a typed node graph (Feature, ADR, TC, source files) to bind architecture together — that the brain had already been producing something nearly identical. Just without me calling it a graph.

Every row in files.jsonl is an edge: (session_id, tool_name, file_path, timestamp). Every row in prompts.jsonl is a node — the user prompt that drove the edges that followed. Use timestamps as the join axis between the two firehoses and you have a File↔Session graph with Prompt attribution. For free. Pre-computed. Ready to query.

Visually:

   ┌─────────────────────┐
   │  Session            │  one jsonl file per session in ~/.claude/projects/
   │  c848c842-d7c9-...  │  start time, project slug, git branch
   └──────────┬──────────┘
              │ contains
              ▼
   ┌─────────────────────┐
   │  Prompt             │  rows in prompts.jsonl
   │  "lets do a series  │  text, timestamp, isSlash, length
   │   for the pks brain"│
   └──────────┬──────────┘
              │ drove
              ▼
   ┌─────────────────────┐
   │  ToolCall           │  rows in tools.jsonl
   │  Write(...)         │  toolName, toolUseId, durationMs, isError
   └──────────┬──────────┘
              │ wrote | edited | read
              ▼
   ┌─────────────────────┐
   │  File               │  rows in files.jsonl
   │  da.md              │  filePath, op, success
   └─────────────────────┘

Forward is trivial. The interesting direction is reverse: I have a file and want to know what happened to it.

File: blog-posts/pks-brain/da.md
  │
  └─► ToolCalls that wrote/edited it
        │
        └─► Prompts that drove them (same session, ts ≤ tool-call.ts)
              │
              └─► Sessions where it happened
                   (with date, branch, primary session)

That's the entire query pks brain commit-plan runs: take the staged files, look them up in files.jsonl, find the prompts that drove the edits, return the grouped plan. It tells the commit-message writer why the changes happened — not just what changed.

Chapter 4 is about exactly that flip: how we took the graph layer — which had been there all along, built by ingest in two seconds — and used it to write commit messages that know why. When we moved pks brain commit-plan from re-scanning raw JSONL per file to reading the firehose directly, a commit-plan over 52 staged files went from ~200 seconds to 1.3 seconds. This post was written in the session where that flip happened.

The four chapters

1. The brain behind — this post. Why the brain exists, what it consists of, and how the graph emerged.
2. What the brain actually knows — a tour of the wiki output. What do the auto-generated pages look like, and how accurate are they when you set a wiki page next to the source code it was synthesised from?
3. The graph inside — the architecture in detail. Which nodes exist (Session, Prompt, ToolCall, File), which edges connect them, what's stored deterministically versus AI-generated.
4. From changed files to commit messages — how we join staged files against the graph to find the prompts that drove each change, and how we use them to write feat(blog): publish coolify-destinations-pr post-level commit messages automatically. Including why this only became usable when the graph replaced the scanner.

Who this is for

If you:

• use Claude Code actively and your ~/.claude/projects/ directory keeps growing
• wish you got something back from that work — beyond the code that's already in git
• have tried to "write ADRs after the fact" and discovered it never happens

… then this is for you. The brain isn't doing anything magical. It harvests what you've already produced, makes it searchable, and comes back once a day asking whether anything new happened.

What's sitting in your own ~/.claude/projects/ that you're never going to read again?