DEV Community: Tyler H

Safe to Upgrade? — know before you bump: per-dependency upgrade verdicts with file:line evidence

Tyler H — Wed, 21 Oct 2026 19:46:48 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 3 — Slow and Steady.

What I Built

Dependency upgrades are the chore everybody puts off. Versions drift,
upgrading feels risky, so it waits — until a CVE or a forced major
version turns it into an emergency. The fear isn't wrong. One migration
guide, read carefully, takes real time. Fifteen of them is a day.

Safe to Upgrade? answers one question: does my code use any of the
APIs this upgrade removes? It answers with evidence:

It reads your package.json.
For each dependency, it pulls the breaking changes between your version and the target version, from the project's own migration guide or release notes.
An open-weight model extracts the removed and renamed APIs from that guide text. (Live run: Gemma 3 4B via Ollama — Runs 4–6 in EVALUATION.md.)
Deterministic code — never the model — searches your codebase for those exact APIs and gives one verdict per package:
- REVIEW — a removed API is used, with file:line evidence.
- SAFE — breaking-change data exists and none of its APIs are used.
- UNKNOWN — no breaking-change data. The tool says so instead of guessing. A dependency tool that bluffs is worse than no tool.

Dependabot and Renovate bump versions. A bump PR doesn't answer this
question. They'll open a PR that breaks you, or one that sits for a year
because checking it feels riskier than staying put. This is the step
before the bump: a verdict computed on your machine, from the guide
itself. Where the data doesn't exist, it says UNKNOWN and stops.

The model proposes. The code disposes. The model does the reading;
tested code owns the verdict.

Demo

Live demo: https://safe-to-upgrade-demo.onrender.com/ — the recorded
runs as a page, deployed on Render from this repo. The page says plainly
that its data is recorded, not a live backend.

What the demo shows, from a real run on the sample project:

Package	Upgrade checked	Verdict	Evidence
express	4.x → 5.x	REVIEW	`res.sendfile` used at `src/server.js:34`
react-router-dom	5.x → 6.x	SAFE	0 of 4 breaking APIs used
lodash	—	UNKNOWN	no data, not guessed

Code

tyy130 / safe-to-upgrade

Safe to Upgrade?

Nobody upgrades their dependencies because nobody wants to read fifteen changelogs. Safe to Upgrade? answers the only question that matters — "if I bump this package, does my code actually use anything that broke?" — with evidence, not vibes.

For each dependency in a repo's package.json, the tool takes breaking-change data for the target upgrade (API identifiers that were removed, renamed, or changed, each with a source URL), then deterministically searches the codebase for real usage of those identifiers and issues one verdict per package:

Verdict	Meaning
REVIEW	Breaking APIs are used — evidence is listed as `file:line` with the matched line
SAFE	Breaking-change data exists, and none of its APIs are used anywhere in the code
UNKNOWN	No breaking-change data for that package — the tool says so instead of guessing

Architecture: model proposes, code disposes

Extraction is the model's job. Reading a changelog or…

View on GitHub

How I Built It

verdict.py — the deterministic core (Python standard library only). Parses dependencies, then searches source files for each breaking API. Matching is careful about boundaries: dotted APIs match as literal member accesses with a trailing boundary, so app.delete does not match the removed app.del, and req.params does not match the removed req.param. Those two false positives are why this part is code and not a prompt.
breaking_data.json — curated breaking changes, every entry carrying its source URL: Express 4→5 (7 APIs, from the official Express 5 migration guide) and React Router 5→6 (4 APIs, from the official v6 upgrade guide).
extract_breaking.py — the extraction stage. Two paths, one rule:
- A model path (Ollama, strict JSON-only prompt) for when a local model is available.
- A deterministic heuristic fallback that finds API tokens near removal language in guide text.
- Both paths pass through a grounding check: any extracted API that doesn't appear verbatim in the source guide is dropped. The model can propose; it cannot invent.
fetch_changelog.py / browserbase_fetch.py — changelog fetching. Plain HTTP where it works; Browserbase for the guides that live outside GitHub Releases. The Browserbase path has a live run behind it: a real session was created through the API, and the Express guide was fetched through the Browserbase Fetch API (200, 211,507 characters — the same document the direct fetch produces).

What the evaluation actually showed

I ran the engine on a real open-source project
(gothinkster/node-express-realworld-example-app, 39 dependencies) and
then hand-checked its verdict with an independent plain-text search:

express: SAFE — and the hand-check agreed: zero true uses of the seven removed APIs.
The hand-check nearly produced a false alarm: a plain search for req.param lights up on req.params, which appears all over that codebase. The engine's boundary matching excluded every one. One miss like that in a real upgrade is how a tool loses trust.
The other 38 dependencies came back UNKNOWN. Coverage is the bottleneck, not the verdict logic: getting trustworthy breaking-change data for the long tail of packages. The number stays in because it's the honest state of the tool.

The extraction stage got the same treatment. On the real Express 5
guide, the heuristic recovered 7 of 7 curated APIs — from 24
candidates. Some of the extra 17 are genuine signature changes the
curated set omits; several are junk (res.status, example-code tokens).
Fed into the verdict engine raw, the heuristic data flags 8 uses in the
sample project where the curated data flags 1. Recall is easy;
precision is the work.

The model pass closed that gap on this guide. Gemma 3 4B proposed 10
entries; the grounding check kept all 10 (each appears verbatim in the
guide); after normalizing signature forms (res.send(obj, status) →
res.send), the model data flags exactly 1 use in the sample
project — the same res.sendfile call the curated data flags. Generated
data still isn't hand-verified the way the curated set is, so it stays
labelled as generated wherever it appears.

Then I ran the coverage pass the 38 UNKNOWNs were asking for:
extraction on the guides and release notes of every package in that
repo with a pending major — ESLint 9, Prisma 5, Prettier 3, Jest 30,
bcryptjs 3, body-parser 2, Nx 18. (Run 7 in EVALUATION.md.)

Two converted:

ESLint 8→9: SAFE, on the API axis. 11 candidates from the official migration guide; the real ones are rule-API removals (sourceCode.getComments, context.getSource). Grep confirms the repo uses none of them. Its actual v9 risk is the .eslintrc.json file v9 no longer reads — and a config file is not an API call. The matcher can't see it, and the verdict doesn't claim to.
Prettier 2→3: SAFE. The real v3 removals are the .sync APIs (prettier.resolveConfig.sync and friends) going async. The repo never calls the Prettier API at all. Grep confirms.

Two got rejected by inspection:

Jest 30. The extracted data claimed jest.spyOn was removed. It wasn't — the Jest 30 post presents it as a feature (the new using syntax). Bad data, thrown out.
Prisma 5. The candidates weren't Prisma Client APIs. And the repo does use PrismaClient (src/prisma/prisma-client.ts), so the engine's computed SAFE would have been a false all-clear on a package with a real upgrade surface. Inspection caught it. That check exists for exactly this.

Three produced nothing: bcryptjs (the break is ESM module shape,
described in prose), body-parser (behavior changes, prose), Nx
(release notes are feature lists). No API tokens, no data, still
UNKNOWN.

Final state of that repo: 3 verdicts out of 39, 36 UNKNOWN. The
UNKNOWNs were never one problem. They split into no pending major
(roughly half), changes shaped like config or prose that an API
matcher can't judge, and extractable API removals — the only bucket
this tool converts, and only when the extracted data survives
inspection. Two of the four datasets produced in this pass wouldn't
have.

What went wrong

GitHub Releases is not where changelogs live. My first fetcher assumed releases would be there. For facebook/react it worked. For Express and React Router it returns 404 — they publish migration guides on their own sites. That failure is the reason the Browserbase fetch path exists: something has to go read the guide where it actually is.
Even the fetch redirects on you. The first Browserbase fetch of the Express guide came back 301 — the Fetch API returned the redirect instead of following it to the trailing-slash URL. One more step the pipeline has to handle explicitly.
The build VM couldn't run the model — and the first live run failed anyway. This environment has a few hundred MB of free memory, so the model run moved to a free Colab T4 GPU: Ollama + Gemma 3 4B, the real script, the real guide. Run one produced no usable model output at all ("no JSON array found in model output") and fell back to the heuristic. Instead of accepting that, I captured the model's raw answers: it wraps JSON in markdown fences; under Ollama's JSON mode it returns an object, not the array my parser demanded; and Ollama's default 4096-token context truncates a guide-length prompt. Fixed all three — JSON mode, num_ctx: 32768, a parser that accepts the shapes a 4B model actually returns — and re-ran: path used: model, 10 entries, 10 grounded, 0 dropped. The failure is Run 4 in EVALUATION.md. The fix is a commit.

Why Does Open Innovation Matter?

Three concrete reasons, specific to this tool:

Your codebase is the input. What's being analysed is your source code and your dependency list. With open-weight models running on your own hardware, none of it has to leave your machine to get a verdict. A closed model makes "should I upgrade?" cost you a copy of that fingerprint, sent to someone else's API.
The evaluation is reproducible. Because the model is open, anyone can re-run my extraction on the same guide and check my numbers — including the bad precision ones. A closed endpoint can change under you between the run and the write-up.
The guardrails are inspectable. The grounding check and the boundary matcher are small, readable, and in the repo. For a tool whose output is a safety claim ("SAFE"), being able to read exactly how that claim is produced is the feature.

The Lazy Payoff

The Express 5 migration guide is ~27,000 characters of prose. The React Router v6 upgrade guide is comparable. Doing this by hand for one package means reading the guide, listing the removed APIs, and then searching your codebase for each one — carefully, because of traps like req.param vs req.params. My estimate is ~30–45 minutes per package, done carefully. That's an estimate, not a stopwatch number.
The engine triaged all 39 dependencies of a real-world Express app in well under a second (0.08s on the fastest run I measured; ~0.2s on a loaded machine — and the verdicts reproduce exactly), with the evidence attached. It produces the same answer every time you run it.
On the real-world run: 39 dependencies, one command. Three verdicts I could act on after the coverage pass; 36 UNKNOWNs that show exactly where the remaining manual work is, instead of a vague feeling that everything might be broken.

My Agent Session

What I actually did on this, start to finish: picked the problem, set
the rule that generated data never gets trusted without a check, and
read every run before believing its output. The moment that sold me on
the design was the hand-check — a plain text search screamed that the
real-world app used a removed API, and the engine's boundary matching
showed it didn't (the req.params sweep above). The worst stretch was
the first Gemma run: a clean failure, no usable output, and nothing in
the logs said why — until I looked at the model's raw answers and
found three separate format problems, each with a concrete fix. The
full record of what was run, what broke, and where every number in
this post comes from is in the repo as EVALUATION.md.

Prize Categories

I'm entering the categories this project genuinely used:

Browserbase — a real session was created through the API and the Express migration guide was fetched through the Browserbase Fetch API during the build (EVALUATION.md, Run 3).
Gemma — Gemma 3 4B (open weights, via Ollama) is the model in the extraction stage, with a full live run logged (EVALUATION.md, Runs 4–6). The live run executed on a free Colab T4 because the build VM couldn't host the model; the same script runs on local hardware wherever Ollama does.
Render — the demo is deployed on Render: https://safe-to-upgrade-demo.onrender.com/

NeuroGuard: AI-Native Code Security Using Gemma 4's Glass-Box Thinking Mode

Tyler H — Wed, 13 May 2026 10:00:38 +0000

Submitted to the Build With Gemma 4 track of the Dev.to Google Gemma 4 Challenge.

TL;DR: I built neuroguard — a CLI that uses Gemma 4's ThinkingConfig(include_thoughts=True) API to stream the model's full cognitive trace in a split-pane terminal UI while it finds security vulnerabilities and produces a SAST-verified secure rewrite. Live demo → | Install: pip install neuroguard-ai | Source: github.com/tyy130/neuroguard-ai.

The Problem I Kept Running Into

security
Studies find the majority of AI-generated applications ship to production with OWASP Top 10 vulnerabilities. I've seen it firsthand. The worst cases aren't SQL injections from typos — they're hallucinated bypasses: an AI agent removes authentication middleware to resolve a compilation error, silently stripping the application of its entire security layer.

The frustrating thing is that a human reviewer wouldn't make this mistake, because they'd reason about what the code does before deleting it. The AI just optimized for "code compiles" without the security reasoning step.

The root cause is opacity. When a black-box LLM generates insecure code, you can't see why. You get the output without the reasoning. And without the reasoning, you can't tell if the model considered security at all — or silently decided to ignore it.

I wanted to fix that.

What Makes Gemma 4 Different

Two approaches existed before Gemma 4:

Hidden (OpenAI o1/o3): These models run a real reasoning process, but the trace is completely invisible. You get a reasoning_tokens count in the usage object, nothing else. You can't route it, log it, or build on top of it.
Inline text (local R1, prompted CoT): When you run a reasoning model locally — like R1 via Ollama — or prompt any model to think step by step, the reasoning ends up in the same string as the response, separated only by <think>...</think> tags. You can see it, but you have to parse it out. Tags can split across stream chunks, the model can reopen reasoning after </think>, and there's no API-level guarantee about the boundary.

Gemma 4 does something different. ThinkingConfig(include_thoughts=True) emits reasoning as structurally separate stream parts — each chunk carries a thought=True field. The reasoning and the response are separated at the API level, not by text parsing.

That API-level separation is what makes NeuroGuard possible. I can route thought parts to a left pane and response parts to a right pane in real-time, with no regex parsing, no risk of the boundary getting confused, no thought tokens leaking into the final output.

How NeuroGuard Works

┌─────────────────────────────┬────────────────────────────┐
│  🧠 Gemma 4 Thinking        │  🔒 Secure Rewrite         │
│  ─────────────────────────  │  ─────────────────────────  │
│  ...the SQL query on line   │                             │
│  47 concatenates user input │                             │
│  directly. This is a        │                             │
│  classic injection vector.  │                             │
│  The fix is parameterized   │                             │
│  queries...                 │  from flask import Flask   │
│                             │  import sqlite3            │
│  ...the eval() on line 62   │                             │
│  executes arbitrary strings │  def get_user(user_id):    │
│  from the request body.     │      conn = sqlite3.connect│
│  This is RCE...             │      cursor.execute(       │
│                             │          "SELECT * FROM    │
│                             │           users WHERE      │
│                             │           id = ?", (id,))  │
└─────────────────────────────┴────────────────────────────┘
  Bandit: 4 findings → ✓ CLEAN (0 findings in rewrite)

The left pane streams as Gemma 4 reasons. The right pane fills in as it produces the secure rewrite. Bandit runs on the rewrite at the end and confirms the fix is real.

The Core API Call

response = client.models.generate_content_stream(
    model="gemma-4-31b-it",
    contents=[types.Content(role="user", parts=[types.Part(text=prompt)])],
    config=types.GenerateContentConfig(
        system_instruction=SYSTEM_PROMPT,
        thinking_config=types.ThinkingConfig(
            include_thoughts=True,
            thinking_budget=thinking_budget,  # scales with SAST severity
        ),
    ),
)

for chunk in response:
    for part in chunk.candidates[0].content.parts:
        if getattr(part, "thought", False):
            yield f"<think>{part.text}"   # → left pane
        elif part.text:
            yield part.text               # → right pane

That's it. No regex. No text parsing. The thought=True flag on stream parts is the entire separation mechanism.

Making the Thinking Load-Bearing

The key design decision was making the thinking trace load-bearing, not decorative. I inject SAST findings from Bandit/semgrep directly into the prompt before the model starts reasoning:

SAST pre-scan findings (ground truth — confirm or refute each in your reasoning):

  [HIGH] B608 hardcoded_sql_expressions — line 47
  [HIGH] B307 eval() — line 62
  [MEDIUM] B105 hardcoded_password_string — line 12

Now the model's thinking trace is explicitly reasoning about concrete, tool-verified findings. It can't skip them. It either confirms the finding and fixes it, or explains why it's a false positive. Either way, you have an auditable chain of evidence tied to specific lines.

The thinking budget scales automatically: 4096 + HIGH_count × 512 + MEDIUM_count × 256 tokens (capped at 16384). Files with more HIGH findings get proportionally deeper reasoning.

What It Looks Like in Practice

The built-in demo (demo/vuln_sample.py) is a Flask app with 5 intentional vulnerabilities:

# demo/vuln_sample.py — intentionally vulnerable

SECRET_KEY = "supersecret123"   # hardcoded secret

@app.route("/admin")            # no auth check
def admin_panel():
    return "Admin panel"

@app.route("/user")
def get_user():
    user_id = request.args.get("id")
    query = f"SELECT * FROM users WHERE id = {user_id}"  # SQL injection
    ...

@app.route("/eval")
def run_code():
    code = request.args.get("code")
    return str(eval(code))      # RCE

Running neuroguard review demo/vuln_sample.py:

Bandit finds 4 HIGH/MEDIUM findings in the original
Those findings are injected into the prompt
Gemma 4 streams its reasoning — you watch it identify the injection vector, explain the attack path, and reason through the fix
The secure rewrite uses parameterized queries, removes eval(), moves the secret to env vars
Bandit runs on the rewrite: 0 findings

The thinking trace is the proof of work. You don't have to trust the rewrite blindly — you can see the exact chain of reasoning that produced it.

SAST + LLM: Two Layers of Confidence

One thing I deliberately avoided was making this "just an LLM." Bandit (for Python) and semgrep/regex patterns (for JS/TS) run before the model sees the code. The findings are facts fed into the reasoning layer.

After the rewrite, they run again. The exit code is non-zero if the original had HIGH/MEDIUM findings — so in CI/CD, your pipeline fails on vulnerable code:

# .github/workflows/neuroguard.yml
- name: Security review
  run: neuroguard review src/ --format json
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

You can also get a Slack notification with Gemma 4's reasoning excerpt, post a GitHub PR comment automatically, or pipe JSON to any webhook:

neuroguard review app.py --notify-slack https://hooks.slack.com/...
neuroguard review app.py --format json | jq '.thinking' | head -20

The Architecture

neuroguard/
├── agent.py           # Gemma 4 streaming client — ThinkingConfig, retry/fallback
├── thinking_parser.py # Routes <think> parts to left pane, response to right
├── prompts.py         # Language-aware prompt + SAST findings injection
├── cli.py             # Typer CLI: review, install-hooks, --format json/text
├── integrations.py    # Slack Block Kit, webhook, GitHub PR comments
├── tools/
│   ├── sast.py        # Bandit wrapper → Python findings
│   └── js_sast.py     # semgrep + regex fallback → JS/TS findings
└── ui.py              # Rich split-pane Live layout (12fps)

Model fallback: If the 31B dense model hits a rate limit, NeuroGuard falls back to gemma-4-26b-a4b-it (MoE, ~4B active params) automatically. The demo never stalls.

Language support: Python, JavaScript, TypeScript, JSX, TSX.

Try It

pip install neuroguard-ai
export GEMINI_API_KEY=your_key   # free at https://aistudio.google.com/apikey

# against your own code
neuroguard review app.py

# against the built-in vulnerable demo
git clone https://github.com/tyy130/neuroguard-ai
cd neuroguard-ai
neuroguard review demo/vuln_sample.py

You'll see Gemma 4's full reasoning trace in real-time, then a clean, Bandit-verified secure rewrite.

Why This Matters Beyond the Demo

The shift happening in software development right now is that AI generates the first draft of most code. That's not going to stop. But "vibe coding" — accepting AI output without verification — is already producing an epidemic of OWASP vulnerabilities in production systems.

The answer isn't to distrust AI-generated code. It's to demand transparency from the model before you trust the output. Gemma 4's Thinking Mode makes that possible at the API level for the first time.

NeuroGuard is a concrete demonstration of what that looks like: the model can't silently delete an auth check if its reasoning is visible. The audit trail is the security control.

Apache 2.0. The Kaggle weights mean you can run this on-premise — no code ever leaves your network.

Links:

GitHub: github.com/tyy130/neuroguard-ai
PyPI: pypi.org/project/neuroguard-ai
Landing page: neuroguard-psi.vercel.appgemmachallenge

Notion Cortex: A Multi-Agent AI Research System Where Notion Is the Operating System

Tyler H — Tue, 31 Mar 2026 21:51:17 +0000

This is a submission for the Notion MCP Challenge

What I Built

Notion Cortex is a multi-agent AI research system that uses Notion as its operating system — not just an output destination, but the shared coordination layer where agents think, communicate, and await human approval.

Give it any topic, and five specialized AI agents fan out in parallel:

Scout agents (x5) research different angles simultaneously, extracting structured entities into a Knowledge Graph
Analyst cross-references all findings, identifies patterns and gaps
Synthesizer streams a structured synthesis directly into Notion as it thinks
Approval Gate pauses execution and waits for you to review in Notion — set Status to "Approved" to continue
Writer produces a publication-ready intelligence brief with headings, entity tables, and conclusions

Every agent's reasoning streams into its own Working Memory page in real time. You can literally watch them think in Notion.

$ notion-cortex "The rise of autonomous AI agents in software engineering"

🧠 Notion Cortex — starting run for: "The rise of autonomous AI agents..."

📋 Bootstrapping Notion workspace...
✅ Workspace ready (1.6s)

🧩 Decomposing topic into research angles...
   5 angles identified

🚀 Running 5 Scout agents (concurrency: 3)...
  ✅ Scout 1 done
  ✅ Scout 2 done
  ...

📊 All Scouts complete (103s). Running Analyst...
✅ Analyst done (31s)

🕸️  Computing knowledge graph relations...
✅ Relations linked (8s)

🔗 Running Synthesizer...
✅ Synthesis written (23s)

✍️  Running Writer...
✅ Writer done (43s)

🎉 Done in 229s! Intelligence brief: https://notion.so/...

Video Demo

The demo shows a complete run from notion-cortex "topic" through all 5 agent phases to the final intelligence brief in Notion.

Show us the code

GitHub: github.com/tyy130/notion-cortex

Architecture

src/
  index.ts              CLI entry point + setup wizard
  cleanup.ts            Archives all cortex-* databases for a fresh start
  orchestrator.ts       Pipeline coordinator
  llm.ts                Dual-provider streaming (OpenAI + Anthropic)
  streaming.ts          Token buffer → timed Notion block flush
  concurrency.ts        Write queue (p-limit) + exponential backoff retry
  types.ts              Zod schemas for all database entry types
  agents/
    scout.ts            Research + entity extraction via MCP
    analyst.ts          Cross-scout analysis + KG enrichment
    synthesizer.ts      Structured synthesis streamed to Working Memory
    writer.ts           Final brief written to Outputs database
  notion/
    bootstrap.ts        Idempotent 5-database workspace creation
    client.ts           Notion SDK singleton
    mcp-client.ts       Notion MCP server (stdio transport)
    task-bus.ts         Agent task queue CRUD
    working-memory.ts   Streaming page writer + content reader
    knowledge-graph.ts  Entity store with serialized upsert
    approval-gates.ts   Human-in-the-loop polling
    outputs.ts          Final page publisher
    markdown-blocks.ts  Markdown → Notion block converter
    utils.ts            Shared helpers

Key Technical Decisions

Serialized KG upsert: Parallel scouts can discover the same entity simultaneously. A pLimit(1) queue wraps the check-then-create operation, making the upsert atomic without a database lock.

Two-queue concurrency design: writeQueue (pLimit(3)) handles Notion API rate limiting. kgUpsertQueue (pLimit(1)) handles logical atomicity. Different concerns, different queues.

Idempotent bootstrap with archived filtering: bootstrapWorkspace searches for existing cortex-* databases and reuses them. It filters out archived databases (Notion's search API returns them by default) and uses databases.update to ensure schema migrations apply to pre-existing databases.

Dual-provider LLM abstraction: Supports OpenAI (default) and Anthropic with streaming and multi-turn tool-use loops. Switch with one env var.

55 tests across 13 files: Full coverage of the orchestrator pipeline, all agents, concurrency utilities, markdown converter, and Notion data layer.

Quick Start

git clone https://github.com/tyy130/notion-cortex.git
cd notion-cortex
npm install
notion-cortex setup    # interactive wizard
notion-cortex "your research topic"

How I Used Notion MCP

Notion isn't just where output ends up — it's the runtime substrate. The Notion MCP server (@notionhq/notion-mcp-server) runs as a stdio subprocess, giving Scout agents access to notion_search — they check what knowledge already exists in the workspace before extracting new entities, avoiding redundant work across runs.

Beyond MCP search, each database works as infrastructure through the Notion SDK:

1. Task Bus (agent coordination)

The orchestrator creates tasks, scouts claim them via assigned_agent, and status transitions (pending → active → done → blocked) drive the pipeline forward. This is a distributed task queue implemented entirely in Notion.

2. Working Memory (streaming scratchpad)

Each agent gets a dedicated Notion page. As tokens stream from the LLM, a timed buffer flushes them as paragraph blocks to the page every second. You can open a scout's Working Memory page and watch it think in real time.

3. Knowledge Graph (structured entity store)

Scouts extract entities (companies, products, trends, concepts) with claims, confidence levels, and source URLs. A serialized upsert queue (pLimit(1)) prevents duplicate entities when parallel scouts find the same thing. After the Analyst pass, computeAndStoreRelations scans all entities and auto-links them using Notion's relation property — if "GitHub Copilot" appears in another entity's claim, they get linked.

4. Approval Gates (human-in-the-loop)

Before the Writer runs, an approval gate creates a Notion database entry with status "Pending" and a link to the synthesis. The system polls with exponential backoff until you change the status to "Approved" or "Rejected" in Notion. This is genuine human-in-the-loop control — not a dialog box, but a Notion workflow.

5. Outputs (final deliverables)

The Writer converts its markdown output into native Notion blocks — headings, bullet lists, numbered lists, tables, code blocks, bold/italic, and links — using a custom markdownToNotionBlocks converter. The result is a proper Notion page, not a pasted text blob.

Final Thoughts

The most surprising thing about this project was how naturally Notion works as an agent coordination layer. Databases become task queues. Pages become working memory. Relations become a knowledge graph. Status properties become approval gates. It's not a hack — it's genuinely the right tool for this.

The human-in-the-loop approval gate is my favorite feature. Most agent systems are either fully autonomous or require you to babysit a terminal. With Cortex, you get a Notion notification, review the synthesis at your own pace, and approve when ready. The agents wait patiently.

MIT licensed. PRs welcome.