If you've been through this, you know. If you haven't, this is your preview.

Why All This Machinery Exists

Before walking through what happened, it helps to understand why Google's OAuth setup is the way it is.

When any application — including an AI agent — wants to access your Gmail, Google Drive, or Google Calendar, it needs to prove two things: who it is, and that you've consented to give it access. Google handles both through OAuth 2.0, and the infrastructure for that lives in Google Cloud Platform.

Here's how the pieces fit together:

GCP Project — The container for everything. Your OAuth app lives inside a project. If you don't have one, you need to create one before you can do anything else.

OAuth Consent Screen — The configuration that defines your 'app' — its name, the scopes it requests, and whether it's in Testing or Production mode. This is what you see when Google asks you to grant access.

OAuth Client — The actual credentials — a client ID and client secret — that your application uses to identify itself when requesting tokens. There can be multiple clients under one project.

None of this is Hank-specific or OpenClaw-specific. This is just how Google works for any third-party application that wants to access user data. The friction is real, and it's intentional — Google is protecting people from apps that request broad access without accountability.

For a personal AI assistant that only you use, it's a lot of ceremony for what feels like a simple thing. But it's a one-time setup, and once it's done it stays done — mostly.

The gog CLI and the Auth Flow

Hank uses a CLI tool called gog to interact with Google Workspace — Gmail, Calendar, Drive, Contacts, Sheets, and Docs. Once it's configured, it's straightforward: gog calendar events returns events, gog gmail send sends email, and so on.

The initial setup requires running gog auth add with your Google account email and the services you want to authorize. The experience here depends on where your agent is running.

If your agent runs locally on your machine, gog auth add opens a browser window automatically. The whole flow is seamless — sign in, approve, done.

If your agent runs on a remote server (which is my setup — Hank lives on a GCP VM), you need the --remote flag. This is where it gets interesting, and also where the agent can actually participate in the process.

When I ran into this, I didn't SSH into the server and run commands myself. I asked Hank to do it. The agent ran:

gog auth add agent-workspace@gmail.com --remote --step 1 \
  --services gmail,calendar,drive,contacts,docs,sheets

Step 1 generates an authorization URL and prints it — Hank sent it to me via Telegram. I opened the URL in my local browser, signed in, approved the permissions, and Google redirected me to a callback URL like http://127.0.0.1:<port>/oauth2/callback?code=.... The page fails to load because nothing is listening on that port locally. That's expected. I copied the full URL from the address bar and sent it back to Hank, who then ran step 2:

gog auth add agent-workspace@gmail.com --remote --step 2 \
  --auth-url 'http://127.0.0.1:<port>/oauth2/callback?code=...'

Hank extracted the authorization code from the URL, gog exchanged it with Google for an access token and a refresh token, and stored the refresh token on the server. The whole thing happened in the chat — no SSH session, no terminal on my end.

This is one of the better examples of what it actually feels like to work with an agent rather than just at it. The agent does the technical lifting; you handle the one thing only you can do (authenticate as yourself in a browser).

The 7-Day Expiry Nobody Tells You About

A few days after getting everything working, Hank's Google Workspace access stopped working entirely. The error was:

oauth2: "invalid_grant" "Token has been expired or revoked."

invalid_grant is vague. It could mean you revoked access, the token hasn't been used in six months, you changed your password, or a few other things. It doesn't tell you which one.

After some digging, the answer was in Google's OAuth documentation — buried in some common errors doc:

A Google Cloud Platform project with an OAuth consent screen configured for an external user type and a publishing status of 'Testing' is issued a refresh token expiring in 7 days.

There it is. When your OAuth consent screen is in Testing mode, Google intentionally expires refresh tokens after 7 days. The intent is to prevent developers from leaving half-built apps with long-lived tokens floating around. It's a reasonable policy. It's also not well-advertised, and invalid_grant gives you no indication that this is what happened.

Here's the thing that trips people up: if you're a developer, you probably already know that access tokens are short-lived — they expire in about an hour and get refreshed automatically. Refresh tokens are supposed to be the long-lived part. That's true in Production. In Testing, the refresh token itself expires in a week whether you do anything or not.

If you're not a developer, here's the simpler version: there are two types of tokens involved. One is like a day pass — it expires quickly and gets renewed automatically. The other is like a key — it's supposed to last a long time. In Testing mode, Google makes that key expire after 7 days as a safety measure. Once it expires, you have to go through the whole authorization flow again.

The Fix: Publish to Production

The solution is to move the OAuth consent screen from Testing to Production. In Google Cloud Console, this is in the Audience section of the Google Auth Platform.

Publishing to Production removes the 7-day limit. The refresh token becomes long-lived. You re-authenticate once, and you don't have to do it again unless something changes.

The natural concern when you see "Publish app" is: does this make my app public? Does Google need to review it? Is there a cost?

Does it make the app public? — It makes the consent screen technically reachable by other Google accounts, but no one can access your data without you explicitly authorizing them. In practice, it's your private app that only you use.

Does Google need to review it? — Verification is required if you want to remove the 'unverified app' warning for other people who authorize your app. For a personal app that only you use, you can skip verification entirely — you'll see the warning when you re-auth and click through it once.

Is there a cost? — Publishing to Production is free. Formal verification itself is also free for most scope types — though apps requesting certain restricted scopes may require a third-party security assessment that has a cost. For a personal single-user app where you skip verification, none of this applies.

There's one additional thing worth knowing: Google can reclassify scope risk ratings over time. If a scope you're using gets upgraded to a more restricted tier, you'd receive email notifications and a grace period. Your app continues to work in the meantime. It's worth being aware of, not worth worrying about.

What the Unverified App Warning Actually Looks Like

When you re-authenticate after publishing to Production, you'll see a Google warning screen: "Google hasn't verified this app." It looks alarming if you're not expecting it.

This warning appears because the app requests sensitive OAuth scopes (Gmail, Calendar, Drive) and hasn't gone through Google's verification process. The warning exists to protect people from malicious third-party apps. For your own personal app, it's just noise.

To proceed: click Advanced, then "Go to [your app name] (unsafe)". Complete the permissions grant normally. You'll only see this when you re-authenticate, not on every API call.

The Full Fix

1. Publish the OAuth consent screen from Testing to Production in Google Cloud Console

2. Ask Hank to generate a fresh auth URL via gog auth add --remote

3. Open the URL in the browser, complete the flow, send the callback URL back

4. Verify with a test email

After that, calendar events worked again and the morning brief started including today's schedule. The root cause — Testing mode's 7-day token expiry — was something we hadn't encountered before. It's a subtle policy that produces a generic error message.

If you're setting up any application that uses Google OAuth and you expect it to run unattended for more than a week, publish to Production before you ship. You'll save yourself the debugging session.

Tools: gog CLI · Google Cloud Platform · OAuth 2.0

Originally published at https://www.paulbrennaman.me/lab/google-oauth-agent-access

Then I checked the improvement sprint that runs at 10 AM. Same error. Same result.

Two cron jobs down in the same morning window, both for the same reason, neither of which I knew about until I went looking. That's the kind of failure that makes you want to build something.

The First Instinct: A Watchdog Cron Job

The obvious first move was a watchdog. A separate cron job that runs at 6:30 AM, checks if today's daily note exists, and reruns the daily-note job if it doesn't. Simple. Targeted. Done in five minutes.

We built it. It worked. And then we immediately talked ourselves out of it.

The problem with a dedicated watchdog cron job is that it only watches one thing. As soon as I add another cron job I care about — and I keep adding them — I have to remember to also add a watchdog for it. The watchdog and the watched job have to stay in sync forever. That's maintenance overhead that compounds quietly in the background until the day you forget and it bites you.

There's also a subtler issue: a watchdog cron job is a fixed solution to a dynamic problem. It checks for a specific file. If the failure mode changes — different job, different error, different recovery path — the watchdog doesn't adapt. You'd need to rewrite it.

What About Model Fallback?

Before scrapping the watchdog entirely, I wanted to understand why the overload error didn't trigger a fallback to a different model. OpenClaw supports model fallback via agents.defaults.model.fallbacks — if a provider fails, it moves to the next model in the list.

Reading the docs carefully, fallback triggers on: auth failures, rate limits (HTTP 429), and timeouts that exhausted profile rotation. The overload error is an HTTP 529 — a server-side capacity error, not a rate limit. The docs are explicit: "other errors do not advance fallback."

HTTP 429 — Rate Limited — Your request was rejected because you've exceeded your quota. Fallback fires.

HTTP 529 — Overloaded — The provider's infrastructure is at capacity. Classified as 'other error.' Fallback does not fire.

This is an important distinction. Model fallback is not a general resilience mechanism — it's specifically for auth and rate limit scenarios. If you're counting on fallback to protect you against provider outages or capacity crunches, you're going to be surprised the first time one happens.

Model fallback is still worth configuring. It just doesn't solve the overload case.

Failure Alerts: The Fast Layer

The first concrete fix was simple: turn on failure alerts for every critical job. OpenClaw supports --failure-alert on cron jobs — when a job errors, it sends a Telegram message immediately.

openclaw cron edit <id> \
  --failure-alert \
  --failure-alert-after 1 \
  --failure-alert-channel telegram \
  --failure-alert-to <chat-id>

This doesn't prevent failures. It just means I know within seconds instead of hours. That's valuable on its own — if I'd had failure alerts this morning, I would have seen the overload error before I'd even finished my first cup of coffee and could have manually triggered a retry.

Failure alerts are the fast layer. They're reactive, not preventive. But awareness is the prerequisite for everything else.

The Better Answer: Heartbeat Health Check

The real fix came from stepping back and asking a better question. I already have a heartbeat system — a periodic poll that runs every 30 minutes and checks on things. The heartbeat reads HEARTBEAT.md and follows instructions. It's already running. It already has judgment. It already knows how to message me.

Why add a dedicated watchdog cron at all?

Instead, we added a cron health check section to HEARTBEAT.md. Every heartbeat, Hank runs openclaw cron list --json — which returns every cron job with its last run status — and checks for failures. If a job errored and was scheduled to have run today, Hank decides what to do:

Transient error (overload, timeout, network) — Retry immediately via openclaw cron run. Then message Paul with what happened and that it's been re-triggered.

Non-transient error (edit conflict, script failure, logic error) — Don't retry blindly. Message Paul with the error and an assessment of what went wrong. Offer to investigate.

Already retried recently — Check heartbeat-state.json. If a retry happened less than 2 hours ago, skip — don't hammer a failing job.

The key detail: openclaw cron list --json returns all jobs. Not a hardcoded list — everything. Every cron job I ever add is automatically covered by the health check with zero changes to HEARTBEAT.md. The watchdog scales with the system.

Pros and Cons

This approach has real advantages, but it's worth being honest about the tradeoffs.

✅ Pro — Self-scaling — New cron jobs are covered automatically. No watchdog to create, no list to maintain.

✅ Pro — Faster recovery — Heartbeat runs every 30 minutes. A dedicated 6:30 AM watchdog only helps once a day.

✅ Pro — Intelligent triage — Heartbeat can distinguish transient from non-transient errors and respond differently to each.

✅ Pro — One place to maintain — All recovery logic lives in HEARTBEAT.md, not scattered across N watchdog cron jobs.

⚠️ Con — Same provider dependency — The heartbeat runs on the same Anthropic model that might be overloaded. If the outage is widespread, the heartbeat itself could be affected.

⚠️ Con — Adds complexity to the heartbeat — HEARTBEAT.md is already doing a lot — weather, calendar, WHOOP, news. Adding cron health checks makes it longer and heavier.

⚠️ Con — Triage can be wrong — The heartbeat classifies errors before retrying — transient gets retried, non-transient gets escalated. But automated classification isn't perfect. A logic error that surfaces as a generic failure message could get misread as transient and retried when it shouldn't be. To be fair, a dedicated watchdog cron would have the same problem — this is a limitation of automated error triage in general, not specific to the heartbeat approach.

The single-provider dependency is the one I think about most. If Anthropic has a broad outage and both the cron job and the heartbeat are hitting the same endpoint, the heartbeat can't save what it can't reach. In practice, the failure alerts are the safety net for that scenario — I'd see the alert on my phone even if the heartbeat couldn't process it.

What We Shipped

By the end of the conversation, three things were in place:

Failure alerts — All critical cron jobs now alert immediately on the first error. Fast awareness layer.

HEARTBEAT.md cron health check — Every heartbeat checks all cron jobs, retries transients, escalates non-transients, tracks retries in heartbeat-state.json.

The watchdog cron job we initially built got deleted. The heartbeat does the job better.

The Bigger Pattern

What I keep finding with this system is that the instinct to build a dedicated tool for every specific problem is usually wrong. The better move is to extend the ambient infrastructure that already exists.

A watchdog cron job is specific. The heartbeat is general. General wins, because the problem space always expands.

The same logic applies to model fallback. It's tempting to treat it as a resilience catch-all — configure it and assume you're covered. But fallback is a specific mechanism for specific failure modes. Understanding exactly what it protects against (rate limits, auth failures) and what it doesn't (overload, logic errors) is what lets you build the right supplementary layers around it.

Automation is only as reliable as your understanding of its failure modes.

Tools: OpenClaw · Telegram · HEARTBEAT.md · openclaw cron

Previous post: My AI Sends Me a Morning Brief →

Originally published at https://www.paulbrennaman.me/lab/cron-health-watchdog

The Problem: Information Is Scattered

I have a lot of data sources I care about in the morning. Weather (I'm in Atlanta — storms appear out of nowhere). Calendar. WHOOP. Cloud costs from experiments I'm running. Tech news I want to stay current on. And I've been building content for this site, so I need a constant drip of ideas.

Before this system, checking all of those things meant opening five different apps, losing five minutes, and still probably missing something. The goal was simple: one message, everything that matters, waiting for me before I start my day.

The Architecture: HEARTBEAT.md

The core of the system is a file called HEARTBEAT.md in my AI workspace. OpenClaw runs a periodic heartbeat poll on a schedule — roughly every 30 minutes — and when Hank receives it, he reads HEARTBEAT.md and follows whatever instructions are there.

That file is a living document. I can edit it at any time to change what Hank checks, how often, and what thresholds trigger a message versus staying silent. It's the configuration layer for my ambient intelligence system — and it's just Markdown.

What Goes Into the Brief

🌤️ Weather — Two Modes

Weather runs in two modes. The first is a storm alert: every heartbeat, Hank checks the forecast for my ZIP code and sends a Telegram message only if severe weather is arriving in the next two hours. No sunny-day noise. Just the alert when it matters.

The second is the morning brief, which runs once per day between 7:30–9:00 AM. This one includes current conditions, the full day forecast with hourly breakdowns, high/low temps, and rain probability. I use wttr.in for the current snapshot and Open-Meteo for the structured hourly data.

📅 Calendar

Hank pulls today's events from Google Calendar via the gog CLI — a Google Workspace tool I have wired into my workspace. Every event gets its time, name, and location if present. If the calendar is empty, it says so. No hallucinating fake events.

🏋️ WHOOP Recovery Data

I built a custom WHOOP skill for Hank earlier this month. The morning brief uses it to pull yesterday's recovery score and day strain (final values, not mid-day estimates) and today's sleep performance. If WHOOP hasn't finished processing overnight data yet, it skips gracefully instead of erroring.

What makes this useful beyond raw numbers: Hank knows my health context. I'm on a statin, which inhibits CoQ10 production. That matters specifically after heavy strength training — leg days in particular hit me with more DOMS than they otherwise would, and recovery scores in the days after tend to run suppressed as a result. A 52% recovery the morning after a hard leg session reads differently than a 52% recovery on a rest day. Hank knows the difference, and reads the numbers against my personal baseline rather than a generic one.

💰 GCP Cost Summary

I run experiments on Google Cloud, and cloud costs have a way of quietly accumulating. Every morning brief includes yesterday's spend by service and a month-to-date total, pulled directly from BigQuery billing export. If any single service spent more than $1, it gets flagged. It's a tiny budget gate that has caught runaway experiments more than once.

📰 AI / Tech News

Hank runs a few web searches — AI news, startup funding, tech headlines — and summarizes the top 3–5 stories with source links. This isn't curated or filtered through any RSS magic. It's just a model that knows what I care about, doing a quick scan and pulling signal from noise. Good enough for a morning digest; not a replacement for deep reading.

💡 Content Ideas for This Site

Every brief includes 2–3 content ideas for this site, each with a full draft outline or script. These get saved to a dated Obsidian note automatically — so even if I don't act on them today, they accumulate into a backlog I can pull from later. The brief just shows a one-line teaser and the note path.

✅ Tasks

Hank reads yesterday's and today's Obsidian daily notes and extracts anything that looks like a task — checkboxes, bullets tagged TODO, action items. They show up at the bottom of the brief as a quick "don't forget" list. Not a full task management system, just a surface-level scan that catches the obvious things.

State Tracking: heartbeat-state.json

The system tracks what's already been sent to avoid duplicates. A small JSON file — memory/heartbeat-state.json — records timestamps for the last morning brief, the last storm alert, and other one-per-day actions. Before sending anything, Hank checks this file. It's low-tech, but it works.

Quiet Hours

The system respects boundaries. No messages before 7 AM or after 9:30 PM on weekdays, 10 PM on weekends. If a heartbeat fires during quiet hours, Hank acknowledges it and goes back to sleep. The goal is ambient intelligence, not ambient noise.

What I'd Add Next

A few things on the backlog:

• Job search digest — new listings matching my criteria, pulled from saved searches

• GitHub activity summary — any PRs, CI failures, or stale branches across my repos

• Stock/market summary for a watchlist (simple, not financial advice)

• Weekly rollup — a Friday summary of the week's briefs, wins, and open threads

The Bigger Picture

What I've built here isn't particularly novel — people have been building morning dashboards and digest bots for years. What's different is the substrate. I'm not maintaining a cron script that hits a bunch of APIs. I have an assistant that understands my context — my health situation, my job search, my projects, my preferences — and applies that context to every piece of information it surfaces.

The configuration is just Markdown. Changing what the brief covers means editing a file, not touching code. That's the part that actually feels like the future.

Tools: OpenClaw · Telegram · wttr.in · Open-Meteo · Google Calendar · WHOOP · BigQuery · Obsidian

Originally published at https://www.paulbrennaman.me/lab/morning-intelligence-brief

Why Not Just Use Obsidian Sync?

Obsidian Sync is great on paper — real-time, encrypted, works across all your devices. But it's a closed system. There's no API, no way for a server-side process to access your vault. Everything lives in Obsidian's own sync infrastructure, and the only clients are the Obsidian apps themselves.

I also realized I was paying for Sync across three devices, but only ever using it on one — my laptop. I have Obsidian on my phone but basically never open it. I use Apple Notes on iOS instead. Once I understood that git could replace the cross-device sync for my actual usage pattern, canceling Sync was an easy call.

The Stack We Used

obsidian-cli — A Go CLI by yakitrak that lets you search, create, move, and delete notes from the command line. We built it from source after auditing the code — no network calls, clean dependency list.

Obsidian Git plugin — A community plugin that auto-commits and pushes your vault to a GitHub repo on a schedule. Set it to 5 minutes and forget it.

Private GitHub repo — The sync layer. Free, unlimited private repos, and git history is actually better version tracking than Obsidian Sync's history.

Auditing obsidian-cli

Before installing anything that touches my notes, I wanted to verify it wasn't making any outbound network calls. The concern: a malicious CLI could silently exfiltrate note contents.

We cloned the repo and ran a grep across all Go source files for any HTTP, network, or URL imports:

grep -rn "http\|net\.\|url\." --include="*.go" pkg/ cmd/ main.go

The only hit was url.PathEscape in the URI builder — used to construct obsidian:// URIs that open the local Obsidian app. No HTTP clients, no outbound connections. The dependency list confirmed it: just a CLI framework, a fuzzy finder, some YAML/TOML parsers, and terminal UI libraries. Clean bill of health.

We also built it from source rather than using the prebuilt Homebrew binary — the compiled binary might not match the audited source if the author's release pipeline got compromised. Building from source closes that gap. Since it's a Go project with vendored dependencies, it's one command:

go build -o $(which obsidian-cli) .

Pushing the Vault to GitHub

On my laptop, I initialized a git repo inside the vault folder and pushed it to a new private GitHub repo:

git init
echo ".obsidian/workspace.json" >> .gitignore
git add .
git commit -m "initial vault commit"
gh repo create obsidian-vault --private --source=. --push

Then installed the Obsidian Git community plugin, set auto-commit interval to 5 minutes, and enabled pull on startup. The plugin handles everything from there — commit, push, pull, all automatic.

One thing worth noting: we added .DS_Store to .gitignore early. Mac metadata files have no business in a git repo.

Connecting obsidian-cli on the Server

The CLI expects Obsidian's config file (obsidian.json) to exist — normally written by the Obsidian desktop app to track vault locations. Since the server doesn't have Obsidian installed, we created a minimal stub to satisfy it:

# ~/.config/obsidian/obsidian.json
{
  "vaults": {
    "abc123": {
      "path": "/path/to/repos/obsidian-vault",
      "ts": 1709078400000,
      "open": true
    }
  }
}

obsidian-cli set-default "obsidian-vault"
# Default vault set to: obsidian-vault

After that, obsidian-cli list returned all my notes. Hank can now search, read, and create notes from the server side.

Reorganizing into PARA

Before setting up any automation, I wanted to get the vault organized. Twenty-something notes scattered across a flat folder isn't a knowledge system — it's a pile.

We adopted the PARA method (Tiago Forte): four buckets that sort everything by actionability.

Projects/ — Active work with a finish line. Job search, timeshare sale.

Areas/ — Ongoing responsibilities. Home Depot history, tech setup.

Resources/ — Reference by topic. Cloud architecture, general notes.

Archive/ — Anything inactive. Old daily notes, completed projects.

Hank mapped all 20+ existing notes to the right buckets, moved them using git mv (which preserves history), and pushed the reorganized vault in a single commit. We also added a PARA Guide.md at the vault root with a plain-English decision tree for where new notes should go.

Daily Notes Automation

I keep a running daily note — one file per day where I jot things throughout the day. The naming convention is YYYY-MM-DD.md, which sorts chronologically in any file browser.

Rather than creating each day's note manually, we set up two cron jobs:

6:00 AM ET — Create today's note — Creates YYYY-MM-DD.md in the Daily Notes/ folder with a blank template (Notes, Tasks, Journal sections), commits, and pushes. The note is ready before I'm awake.

6:30 AM ET — Archive old notes — Keeps only the 3 most recent daily notes in the active folder. Anything older moves to Archive/Daily Notes/. Notes don't get deleted — they just graduate out of the active view.

Obsidian Git pulls the new note down to my laptop automatically on startup (or within 5 minutes), so it's just there when I open Obsidian.

Yesterday's Notes in the Morning Briefing

Hank already sends me a morning briefing — weather, calendar events, anything worth knowing before the day starts. We extended it to include a summary of the previous day's note.

Each morning, before sending the report, Hank reads yesterday's YYYY-MM-DD.md. If there's real content beyond the blank template headings, it gets summarized and appended to the report under a "📓 Yesterday's Notes" section. If the note was empty, that section is skipped.

If anything in the note looks like it belongs in a permanent PARA file — a reference worth keeping, a project update, a contact — the briefing includes a nudge asking whether to file it. No automatic filing without approval.

What We Learned

Audit before you install — Reading the source before running it cost 10 minutes and gave real confidence. For a tool with read/write access to all your notes, that's time well spent.

Build from source when you can — The Homebrew tap had v0.2.3. Building from the audited source got us v0.3.1 — newer, and we know exactly what's in it. The update alias makes staying current low-effort.

Git is a better sync layer than you'd expect — Obsidian Sync's killer feature is real-time cross-device sync. If you're not actually using multiple devices, git + Obsidian Git gives you history, a remote backup, and programmatic access — for free.

Structure before automation — Automating a disorganized vault would have just automated the mess. Getting PARA set up first meant the daily note job had a sensible place to put things from day one.

Tools: Obsidian · obsidian-cli · Obsidian Git · GitHub · OpenClaw cron

Method: PARA (Tiago Forte)

Originally published at https://www.paulbrennaman.me/lab/obsidian-ai-setup

The Blind Spot

OpenClaw's memory_search tool does semantic search over MEMORY.md and memory/**/*.md. It can also be configured to index additional paths via memorySearch.extraPaths — we already had ours pointed at the PARA directories (knowledge/areas, knowledge/resources, knowledge/projects). But that only picks up .md files. JSON is invisible by design.

So we had two parallel systems that didn't talk to each other. The .md files were searchable. The items.json fact store — which had all the structured, atomic, lifecycle-tracked facts — was not. The only way to query it was to call scripts/facts.py directly, which only runs when explicitly called. Spontaneous recall through memory_search was completely blind to it.

We could have patched it quickly — generate a flat facts.md rendering of all active facts, let memory_search pick it up. But that would have been the wrong call. Instead of patching, we asked the better question: what should the structure actually look like?

Rethinking the Structure

The original PARA layout was flat. Each top-level directory had one items.json:

knowledge/areas/items.json      # all area facts, mixed together
knowledge/projects/items.json   # all project facts, mixed together
knowledge/resources/items.json  # all resource facts, mixed together

This worked fine for the engine — it could iterate everything. But it didn't reflect how PARA is actually supposed to work. Real PARA systems have nested structure: areas like Career, Finances, Health. Projects like Job Search, Personal Website. Resources like Contacts, How-To Reference.

Flattening everything into one file per PARA directory was convenient for the first implementation, but it was the wrong shape. And it's why facts couldn't be rendered into something memory_search could use — a flat dump of 27 mixed facts isn't a useful document for semantic search. It has no structure, no coherence, no reason for related things to be near each other.

The Design We Settled On

One subdirectory per topic. Each subdirectory gets two files: items.json for metadata, index.md for human-readable content plus a rendered facts section.

knowledge/areas/career/
    items.json    # career facts metadata
    index.md      # career context + rendered facts

knowledge/areas/tools-and-systems/
    items.json
    index.md

knowledge/projects/job-search/
    items.json
    index.md      # existing content preserved

knowledge/resources/contacts/
    items.json
    index.md

Three decisions embedded in this structure that are worth explaining:

Decision 1: items.json colocated with index.md

The reasoning was practical: the items.json should live in the same subdirectory as the index.md, not at the top level. The reason was practical — if you're poking around the file system trying to verify something, the JSON and the rendered view should be right next to each other. Everything in career/items.json should appear somewhere in career/index.md. You can check that without opening multiple directories.

It also makes the global index honest. The global _meta/facts-index.json is rebuilt from all subdirectory items.json files. If something is missing from a subdirectory, it's missing from the global index too — there's no hidden flat file at the top level to catch strays.

Decision 2: Rendered section, not a separate file

The facts render into index.md directly — not into a separate facts.md. This keeps things consolidated. The index file is the single document for that topic: context, notes, and facts all in one place, all indexable together as a semantic unit.

To make this safe — so the render step doesn't clobber human-written content — the facts section is wrapped in HTML comment delimiters:

<!-- facts:begin -->
## Facts

### Preferences
- Prefers async communication over synchronous meetings
- Prefers documentation written before implementation begins

### Lessons
- Monorepo deployments need separate cache keys per package
<!-- facts:end -->

The render step finds those delimiters and replaces only what's between them. Everything outside the block is untouched. Since the nightly job controls all writes to items.json, it can regenerate this section on every run with no drift risk — the source of truth is always the JSON, and the rendered section always reflects it exactly.

Decision 3: Intelligent routing, not fixed buckets

When a new fact is created, the engine needs to decide which subdirectory it belongs in. This is where we had to be honest about taxonomy drift — an LLM making routing decisions from scratch every run would inevitably create new subdirectories arbitrarily and scatter related things into inconsistent places.

The fix: routing is a one-time decision made at fact creation, stored as a subdir field on the fact itself. The nightly render step just reads where each fact says it lives and renders it there. No re-routing on subsequent runs. To prevent taxonomy explosion, the engine strongly prefers existing subdirectories and requires a high bar for creating new ones.

What We Changed in facts.py

The Python engine needed four changes to support the new structure:

New storage helpers — items_path(para_dir, subdir), load_items(para_dir, subdir), save_items(para_dir, subdir, data). iter_all_subdirs() yields (para_dir, subdir) pairs for everything with an items.json.

render command — facts.py render [--para-dir] [--subdir]. Reads items.json, groups active facts by type, writes or updates the facts:begin/end block in index.md. Creates the file if it doesn't exist.

migrate command — One-time migration. Reads each flat top-level items.json, routes each fact via infer_subdir(), writes to the correct subdirectory, adds the subdir field, deletes the old file.

--subdir on add — facts.py add now accepts --subdir (e.g. 'career' or 'areas/career'). If omitted, infer_para_and_subdir() handles routing. The subdir field is stored on the fact for future render passes.

All iteration-based commands (expire-check, decay, health, rebuild-index, list, search) now use iter_all_subdirs() instead of iterating flat PARA directories. The behavior is identical — they just walk a tree now instead of a list.

The Migration: 27 Facts, 6 Subdirectories

Running facts.py migrate distributed all 27 existing facts based on content and type:

areas/career/ — 3 facts — Seniority level, preferred team size, target role type

areas/tools-and-systems/ — 16 facts — Notification preferences, cron schedules, deployment pipeline facts

projects/active-job-search/ — 4 facts — Upcoming interviews, companies in pipeline, prep notes

projects/home-lab/ — 2 facts — Server hostname, OS version deployed

projects/general/ — 2 facts — Deferred tasks, housekeeping decisions

resources/contacts/ — 5 facts — Recruiters, collaborators, references

Existing flat .md files at the PARA top level also moved into their new subdirectory homes — content preserved, paths updated. Subdirectories that already had an index.md kept their existing content; the facts block was simply appended inside the delimiters.

What It Looks Like Now

After running migrate and render, knowledge/areas/health/index.md looks like this:

# Health

[existing health notes here]

<!-- facts:begin -->
## Facts

### Preferences
- Prefers morning workouts before 8am
- Prefers running outdoors over treadmill when weather allows

### Status
- Current training goal is a half-marathon in May
<!-- facts:end -->

memory_search can find all of this now. A query about workout preferences surfaces the health facts. A query about an upcoming race finds the project facts. The fact system and the search index are finally speaking to each other.

Health After Migration

Total facts: 27 | Active: 27
Unreconciled: 0 | Dormant: 0
Temperature (ephemeral): hot: 4 | warm: 0 | cold: 0
Overdue expirations: 0
Alerts: none 🟢

No data loss during migration. The nightly job prompt was updated with --subdir routing guidance and a new final step: facts.py render after every run to keep the facts blocks in sync.

What We Learned

A working system and a useful system are different things — The fact engine worked perfectly — creating, expiring, reconciling facts. But working correctly and being actually useful for recall are different bars. A system that stores information I can't retrieve isn't a memory system; it's a write-only log.

The right structure matters more than the right content — The fix wasn't to add more facts or better routing logic. It was to change the shape of how facts are stored so they naturally align with how recall works. Structure determines retrievability.

One question exposes one problem; one problem reveals the design — It started with a simple question: where's the .md file? That one observation traced back to a fundamental architectural gap — facts stored outside the search index. It's a good reminder that questions about missing output are often really questions about missing structure.

Colocate what belongs together — items.json next to index.md in the same subdirectory means you can validate the system by inspection. 'Does the JSON match the rendered file?' is a question you can answer without tooling. That kind of human-verifiable structure is worth building for.

Tools: Python 3 · JSON · Markdown · OpenClaw cron

Previous post: Fact-Level Memory Decay, Part 2: Building the Engine →

Originally published at https://www.paulbrennaman.me/lab/facts-searchable-redesign

What Is a Fact, Exactly?

The first design question was definitional: what's the right atomic unit? Go too granular and every adjective becomes its own entry. Go too coarse and you're back to the same problem — a compound statement that's half stale and half fresh, but gets treated as one thing.

The definition I landed on: one subject, one predicate, one claim.

The practical test is the and-test. If you find yourself writing "and" to connect two independent ideas, that's two facts. Ask: would you ever need to update one piece without the other? If the answer is yes, they're separate. If updating one always means updating the other, keep them together.

Examples:

✅ "Team demo is scheduled for Friday" — one fact

✅ "Prefers async standups over live meetings" — one fact

❌ "Currently job searching and prefers fully remote roles" — two facts crammed together

Durable vs. Ephemeral

Once you have atomic facts, the next insight is that not all facts decay the same way. Some facts are true until they're contradicted. Others are true until time passes. These need different treatment.

Durable — True until explicitly contradicted. Preferences, long-term decisions, contact details. Exempt from temperature decay — only invalidated by a newer contradicting assertion. Example: 'Prefers async standups over live meetings'

Ephemeral — Time-bounded by nature. Becomes stale when the window passes, regardless of whether anything contradicted it. Subject to temperature decay. Example: 'Team demo call is on Friday'

Durable facts don't temperature-decay, but they can go dormant: if a durable fact hasn't been referenced in 90 days, it gets flagged as possibly no longer relevant. Not deleted — just surfaced for review. That's the difference between a preference that's still true but hasn't come up lately, versus a belief that has quietly become outdated.

Four Statuses, Not Two

The original decay system had two states: hot, warm, cold. But temperature alone can't capture everything that can happen to a fact. I added an explicit status field with four values:

active — Currently true and relevant. The default.

superseded — Replaced by a newer, contradicting fact. Linked to its successor via superseded_by. The chain is preserved — you can always trace how a belief evolved.

expired — Was true, but its time window has passed. Different from superseded: nothing contradicted it, the clock just ran out.

dormant — Durable fact with zero access count for 90+ days. Still believed, just unused. Worth reviewing.

The superseded/expired distinction matters. Superseded means a new claim replaced it. Expired means it was true but its time passed. Both preserve history — neither deletes anything. Facts are never deleted, only transitioned.

Write-Ahead Log + Nightly Compaction

The trickiest design question: who creates facts, and when? We landed on both — but with different trust levels and a reconciliation step.

Inline during sessions: When something clearly factual surfaces in conversation, create the fact immediately. Don't wait for the nightly job — if the session ends abruptly or the job fails, you've lost it. These are high-confidence, user-stated facts. Fast, durable, possibly a little noisy.

Nightly batch from daily logs: The nightly review job catches what the session didn't explicitly flag — inferences, patterns, things mentioned in passing. This is also where deduplication and reconciliation happen.

# The mental model
Inline facts = write-ahead log entries (WAL)
Nightly job = compaction

# Inline says:
"this seems like a fact, save it"

# Nightly says:
"confirmed / superseded / these two are the same thing"

Every inline fact gets a reconciled: false flag. The nightly job processes the unreconciled pile, confirms or merges each entry, and flips the flag. This gives compaction a clean entry point — it only needs to process new WAL entries, not compare every fact against every other fact on every run.

Deduplication Without Semantic Search

Detecting duplicate facts — "Prefers async standups" vs. "Dislikes synchronous meetings" — ideally requires semantic similarity. Vectorized semantic search wasn't available for this purpose. So the dedup strategy has to be practical rather than ideal.

We settled on a two-layer approach:

1. Structural keying. Each fact is indexed by type + subject entity at creation time. New facts only get compared against existing facts in the same bucket — dramatically smaller comparison space.

2. LLM reasoning on flagged candidates. The nightly job runs as a Claude agent. When structural keying surfaces candidate duplicates, Claude reads them and reasons about whether they assert the same claim. Output: skip, merge, or supersede. This is Claude thinking, not vector search.

It's not perfect — pure paraphrases with no structural overlap can still slip through. But inline creation discipline (only log clearly new information) keeps the duplicate rate low enough that this approach is workable in practice.

How Do You Know It's Working?

A memory system without observable success metrics is just vibes. We defined three layers of measurement:

Health metrics — Is the system functioning correctly? WAL backlog (should be near zero after each nightly run), reconciliation rate, expiration accuracy, nightly job runtime.

Quality metrics — Is the decay signal honest? Temperature distribution should be a pyramid — some hot, more warm, most cold. If everything is hot, decay isn't running. If everything is cold, bumping is broken.

Outcome metrics — Is it actually helping? Is context being repeated less? Is stale information bleeding into current responses? These are harder to measure but matter most.

A weekly health digest cron posts a summary to a configured notification channel. Threshold-based alerts handle acute failures without waiting for the weekly report: WAL backlog over 20, any active facts with an expired expires_after, nightly job runtime more than 2× its rolling average.

What's Next

This is a design, not a running system — yet. The spec is complete, but the file-level decay index is still what's actually running today. Building the fact-level system requires rewriting the nightly review job, creating the items.json structure across the knowledge base, and establishing the inline fact creation habit.

The gap between a good design and a working implementation is real. In Part 2, I build it.

Concepts: Write-ahead log · LRU/LFU decay · Knowledge representation · PARA method

Tools: OpenClaw · Claude Sonnet · Markdown

Next: Part 2: Building the Engine →

Originally published at https://www.paulbrennaman.me/lab/fact-level-memory-decay

What We Had to Build

The design spec (previous post) defined the schema, the rules, and the lifecycle. The goal was to turn that into running infrastructure:

1. A core engine that creates, queries, supersedes, expires, and decays facts

2. Per-directory storage files alongside the existing PARA knowledge base

3. A global index for cross-directory queries

4. Health metrics and alerting

5. An updated nightly cron job that handles fact extraction, reconciliation, and maintenance

6. Seed data — bootstrap the system with facts from today's daily log

The Core Engine: facts.py

Hank wrote the engine as a single Python CLI script: scripts/facts.py. Not a web service, not a database, not a framework — just a script that reads and writes JSON files. Here's why.

The runtime environment is a Debian container with Python 3 and basic Unix tools. The agent is stateless — it wakes up, does work, and goes back to sleep. Every session starts fresh. A CLI script that operates on JSON files fits this model perfectly. No daemon to manage, no connection to maintain, no state to corrupt if the agent crashes mid-session.

The commands map directly to the operations from the design spec:

# Create a fact (inline WAL entry)
facts.py add --content "Prefers async standups over live meetings" --type preference --durability durable

# Structural keying search (dedup check)
facts.py search --type preference --subject "remote"

# Supersede an old fact with a new one
facts.py supersede <old-id> <new-id>

# Nightly maintenance
facts.py expire-check  # flip past-due ephemeral facts to expired
facts.py decay          # recalculate temperature for all facts
facts.py health         # generate health metrics
facts.py rebuild-index  # rebuild the global aggregate index

Storage: Colocated with PARA

A key design decision: facts live alongside the knowledge they describe. Each PARA directory gets its own items.json:

knowledge/projects/items.json    # project-related facts
knowledge/areas/items.json       # area-related facts
knowledge/resources/items.json   # contacts, reference facts
knowledge/archives/items.json    # archived/historical facts
knowledge/_meta/facts-index.json # global aggregate

When I create a fact, the engine infers which directory it belongs to based on source file and fact type. A contact goes to resources/. An event goes to projects/. A preference goes to areas/. The mapping isn't perfect — but it doesn't need to be. The global index exists precisely so queries don't care which directory a fact lives in.

Seeding: The First 15 Facts

A memory system with zero facts isn't very useful. We seeded the initial facts by reading through today's daily log and extracting every independently true-or-false assertion. Here's a sample:

contact · durable — Alex Chen is the lead engineer at Acme and the primary point of contact

event · ephemeral — Team demo call scheduled for Friday 2026-03-01

preference · durable — Prefers async standups over live meetings when team is distributed

status · durable — Nightly review job runs at 2:00 AM daily

decision · durable — Staging environment does not have access to production credentials

15 facts total. 11 durable, 4 ephemeral. All marked reconciled: false so the first nightly run will process them through the compaction step — confirming, merging, or flagging any issues.

One judgment call during seeding: the async standup preference was inferred from context rather than a direct statement. That got confidence: "inferred" instead of "stated". The distinction matters because the nightly job treats inferred facts with more skepticism during reconciliation.

The Nightly Job: Upgraded

The existing nightly cron job already handled PARA file updates and file-level decay. We extended it with four new responsibilities:

Fact extraction — Read the daily log, extract atomic facts, dedup-check against existing facts before creating.

WAL compaction — Process all unreconciled facts — confirm, merge duplicates, resolve conflicts by timestamp order.

Maintenance — Expire past-due ephemeral facts, recalculate temperature decay, check for dormant durable facts.

Health check — Generate metrics, post alerts to a configured notification channel if anything looks wrong.

The prompt for the nightly job is stored as a Markdown file (knowledge/_meta/nightly-job-prompt.md) rather than hardcoded in the cron config. This means I can iterate on the extraction logic without touching the cron infrastructure. The cron job just reads the file and follows the steps.

We also bumped the timeout from 300s to 600s. The old job was just reading files and updating a simple index. The new job does LLM reasoning for reconciliation — comparing candidate duplicates, resolving conflicts, deciding whether two differently-worded claims assert the same thing. That takes more time.

Running in Parallel

The file-level decay index (decay-index.json) still runs. I didn't rip it out. Both systems operate on the same nightly job — the old file-level tracking continues exactly as before, and the new fact-level system runs alongside it.

This was deliberate. The fact-level system is brand new and unproven. If something breaks — bad extraction, reconciliation bugs, corrupt JSON — the file-level system is still there as a safety net. Once the fact system has a few weeks of successful runs, we'll deprecate the old one.

The Weekly Health Digest

We also set up a weekly cron job that posts a health digest every Monday morning to a dedicated notification channel. It reports:

• Total facts, broken down by status

• WAL backlog (unreconciled count — should be near zero)

• Temperature distribution for ephemeral facts

• Dormant durable fact count

• Nightly job success rate for the past week

• Any active alerts

The first digest will run next Monday. I'm genuinely curious what the numbers look like after a week of nightly extraction and compaction.

What I Decided to Skip

The design spec included a memory_recall wrapper — a layer between Hank and the memory_search tool that would track which retrieved facts I actually used in responses, and only bump access counts on those. The idea was to prevent temperature inflation from facts that were retrieved but never contributed to a response.

After thinking it through, the wrapper felt unnecessary. Temperature decay is self-correcting: a fact that gets retrieved but never matters will stop being retrieved as its content becomes less relevant to incoming queries. The false bumps wash out naturally. Building a wrapper that intercepts a built-in OpenClaw tool felt like over-engineering a problem that doesn't exist yet.

If the temperature distribution looks wrong after 100+ facts — everything stuck at hot, nothing cooling off — we'll revisit. But not before the data says there's a problem.

First Health Check

Right after building, I ran the health check to see what the system looks like at birth:

Total facts: 15 | Active: 15
Unreconciled: 15 (expected — first nightly run hasn't happened yet)
Temperature (ephemeral): 🔴 hot: 4 | 🟡 warm: 0 | 🔵 cold: 0
Dormant: 0
Alerts: none

Everything hot, nothing reconciled, zero history. That's exactly right for a system that was born today. After the first nightly run, the unreconciled count should drop to zero and the first round of extraction from today's daily log should add a few more facts.

What We Learned

JSON files are underrated — No database, no schema migrations, no connection pooling. Just files. They're human-readable, git-diffable, and if something goes wrong I can fix them with a text editor. For a system with dozens-to-hundreds of facts, this is the right level of infrastructure.

The nightly job prompt is the real product — The Python script is just plumbing. The nightly job prompt — the instructions that tell a future Claude session how to extract, reconcile, and maintain facts — is where all the intelligence lives. Getting that prompt right matters more than any code I wrote.

Parallel running buys confidence — Keeping the old file-level system running alongside the new fact-level system costs almost nothing (a few extra lines in the nightly prompt) but gives us a clean rollback path. We'll take that tradeoff every time.

What Happens Next

Tonight at 4 AM ET, the nightly job runs for the first time with the fact-level system enabled. It'll extract facts from today's daily log, reconcile the 15 seed facts, and report any issues.

Over the next few weeks, we'll watch the temperature distribution evolve as facts age. The time-bounded events will expire. Preferences will stay durable. New facts will accumulate. And at some point, the first supersession will happen — some belief I hold today will be replaced by a newer one.

That's when it gets interesting. Not when the system stores facts, but when it learns to let go of old ones.

Tools: Python 3 · JSON · OpenClaw cron · Claude Sonnet (nightly job)

Design spec: Fact-Level Memory Decay, Part 1: The Design

Originally published at https://www.paulbrennaman.me/lab/implementing-fact-memory

First: Reframing MEMORY.md

Before building anything, I had to fix a conceptual problem. My MEMORY.md had become a dumping ground — project details, contact info, system config, behavioral rules, all mixed together. None of it was organized around the question that actually matters: how do I work with this person?

The new rule: MEMORY.md is only for patterns, preferences, and rules of engagement. Not facts about the world. Not project status. Not contacts. Just the distilled understanding of how to work with me specifically — what I value, how I think, what's gotten the assistant in trouble before, and what I've explicitly asked for.

Everything else needed a different home.

The PARA System

I organized the rest using Tiago Forte's PARA method, which sorts all information into four buckets:

Projects — Active work with a specific goal and end date. Job search, website work, ongoing builds.

Areas — Ongoing responsibilities with no end date. Career development, the assistant system itself.

Resources — Reference material on topics of interest. Tech notes, contacts, how-to knowledge.

Archives — Completed or inactive items from the other three. Keeps things tidy without deleting anything.

The knowledge base lives at knowledge/ in the assistant workspace, right alongside MEMORY.md and the daily notes — so the same search tooling (QMD) indexes everything together.

Daily Notes → PARA: The Extraction Schema

Hank already keeps a daily log (memory/YYYY-MM-DD.md) — a fast, raw, append-only record of what happened each day. That stays. But raw notes aren't useful long-term without distillation.

Each night, Hank's review job reads the day's log and extracts seven categories of durable facts:

1. Key decisions made — anything that changed direction or set a constraint

2. Projects discussed — progress, blockers, next steps

3. People mentioned — who came up and in what context

4. Status changes — started, completed, blocked, archived

5. Lessons learned / gotchas — things that went wrong or produced insight

6. Preferences stated — any explicit statement about how I want things done

7. Open questions / follow-ups — unresolved things that need to come back up

Items 1–5 feed the PARA files. Items 6–7 feed MEMORY.md directly — those are behavioral facts, not project facts.

Why not capture directly into PARA? Speed. The daily note is zero-friction — just log everything as it happens. Deciding where something belongs in PARA requires judgment, and doing that mid-conversation slows things down. The nightly job handles organization when there's no urgency.

Memory Decay

Not all memories are equally relevant. A decision from this morning matters more than a note from four months ago — even if the older note is a better semantic match in search.

We track every file in the knowledge base in a decay index with three fields: last_accessed, access_count, and temperature. Temperature has three states:

🔥 Hot — Accessed in the last 7 days — Featured prominently in summaries and context.

🌡 Warm — 8–30 days since last access — Included but deprioritized.

🧊 Cold — 30+ days since last access — Dropped from active summaries but never deleted. Still searchable.

The twist: frequency resistance. Files that have been accessed many times require longer inactivity before they cool down. A note you've referenced 20 times stays warm much longer than one you read once. High-signal facts resist decay; incidental ones fade faster.

Cold facts are never deleted. When something cold becomes relevant again — via search, conversation, or the nightly review — it gets "reheated": last_accessed resets, the clock starts over.

The Nightly Review Job

Everything above runs automatically. At midnight, Hank spins up as an isolated sub-agent that:

1. Reads today's daily note

2. Runs the 7-category extraction

3. Updates the relevant PARA files

4. Updates MEMORY.md if new behavioral patterns emerged

5. Recalculates decay temperatures across the entire knowledge base

It runs silently — no notification unless something urgent surfaces. I wake up with the knowledge base already updated.

How It All Fits Together

# During the day
Conversation happens → raw notes go to memory/YYYY-MM-DD.md

# At midnight
Nightly job reads daily note → extracts 7 categories
→ updates knowledge/projects/, areas/, resources/
→ updates MEMORY.md (behavior/preferences only)
→ recalculates decay temperatures

# On any search
QMD searches all of: MEMORY.md + memory/ + knowledge/
Hot facts surface first, cold facts fade from summaries

Early Impressions

The system ran for the first time last night. It's early, but the structure already feels right. Having a clear place for everything — and a rule for what belongs in MEMORY.md vs. the knowledge base — removes a lot of ambiguity about where things should go.

The decay system is the part I'm most curious about long-term. The real test is six months from now: does old context gracefully fade while the stuff that actually matters stays warm? I'll write a follow-up when I have a real answer.

Inspired by: Tiago Forte's PARA Method, LRU/LFU cache algorithms

Tools: OpenClaw · QMD · Claude Sonnet · Markdown

Originally published at https://www.paulbrennaman.me/lab/para-knowledge-system

The Setup

My OpenClaw gateway runs on a cloud VM, exposed over Tailscale (HTTPS, MagicDNS). My Mac is where Chrome lives. The goal: have the agent — running on the server — control Chrome tabs on my Mac via the browser relay extension.

The architecture has three moving parts:

Gateway (remote VPS) — The AI agent runs here. It proxies browser tool calls to the node host.

Node host (Mac) — A lightweight OpenClaw process that runs on the machine with Chrome. Handles browser requests proxied from the gateway and manages the local relay server.

Chrome extension + relay — The extension attaches to a Chrome tab. A local relay server (127.0.0.1:18792) bridges the extension and the node host.

Starting the Node Host

On the Mac, you run a node host that connects back to the remote gateway:

openclaw node run --host your-gateway.ts.net --port 443 --tls

This connects the Mac to the gateway. On first run, you'll need to approve the pairing from the server side:

openclaw nodes pending
openclaw nodes approve <requestId>

Once paired, the node shows up as connected with browser and system capabilities. The node host process is foreground-only — it holds the terminal. Keep a second tab handy for everything else.

Installing the Extension

Install the extension files to a stable local path, then load them into Chrome:

openclaw browser extension install
openclaw browser extension path  # prints the directory

In Chrome: go to chrome://extensions, enable Developer mode, click Load unpacked, and select the directory from above. Pin the extension.

Tip: If the macOS file picker isn't showing hidden folders, press ⌘ Shift . to toggle them.

The Three Gotchas

Everything above is documented. What isn't well-documented is why the extension shows an error even after you do everything right. Hank and I worked through these together — there are three independent issues, and you need to resolve all of them.

1. The relay starts lazily

When the gateway is local, it starts the relay server (port 18792) on boot. When the gateway is remote, the node host is responsible for the relay — but it only starts it when the gateway sends the first browser request. Until then, port 18792 is closed.

This means: even with the node host running and connected, the extension will show Relay not reachable in its options page until something triggers the relay to start.

The fix is simple — just send any browser status request from the server side. This kicks the node host into starting the relay:

openclaw browser --browser-profile chrome status

After that, lsof -i :18792 should show something listening. The extension options page should now say the relay is reachable.

2. The node host needs the gateway auth token

Once the relay is running, the extension will still reject your token with Gateway token rejected — even if you're pasting the correct token from the server's config.

The reason: the relay validates incoming tokens against the gateway auth token. When the relay runs on the node host (not the gateway), it needs to know that token too — but the node host only has a node.json with its pairing credentials. It has no openclaw.json unless you create one.

Fix: create ~/.openclaw/openclaw.json on the Mac with the gateway auth token:

{
  "gateway": {
    "auth": {
      "token": "<your-gateway-token>"
    }
  }
}

Grab the token from the server: cat ~/.openclaw/openclaw.json and look for gateway.auth.token. Don't share it anywhere — treat it like a password.

After creating the file: restart the node host, trigger the relay again (step 1), then retry saving in the extension options. It should accept the token this time.

3. Playwright needs to be installed

The relay and browser proxy require Playwright on the node host machine. If it's not installed, the relay either won't start or certain browser operations will fail with a 501.

npm install -g playwright

Running npx playwright --version isn't enough — npx downloads on demand and isn't available to the node host process. A global install is what you want.

Attaching to a Tab

Once the extension is configured and the relay is running, click the extension icon on any Chrome tab. The badge shows ON when attached. The agent now has eyes (and hands) on that tab.

Only the tabs you explicitly attach are controllable. Detach by clicking the icon again. If you want to switch to a different tab, open it and click the icon there.

Verifying It Works

From the server (or in an agent session), take a snapshot of the attached tab:

openclaw browser --browser-profile chrome snapshot

You should get back a full accessibility tree of whatever tab is open. From there, the agent can click, type, navigate, fill forms, and read page content — all through your real, logged-in Chrome session.

Security note: This gives the agent access to whatever the attached tab is logged into. Keep the gateway and node host on a private network (Tailscale works well). Don't expose relay ports over LAN or public internet.

Summary

1. Start the node host on your Mac, pointing at your remote gateway

2. Install the Chrome extension and load it unpacked

3. Trigger any browser request from the server to lazily start the relay

4. Create ~/.openclaw/openclaw.json on the Mac with the gateway auth token

5. Install Playwright globally on the Mac

6. Restart the node host, re-trigger the relay, save the token in extension options

7. Click the extension icon on a tab — badge ON means you're good

Tools: OpenClaw · Chrome Extension · Tailscale · Playwright · Node.js

Originally published at https://www.paulbrennaman.me/lab/browser-relay-remote-gateway

The Problem with Default Memory Search

OpenClaw stores memory as plain Markdown files — a daily log, a long-term MEMORY.md, whatever you write to disk. The built-in search indexes those files in SQLite and does its best, but it's largely keyword-based. That means if you search for "gateway server setup" and your note says "run the gateway on the Mac Mini in the closet," you get nothing. The words don't match, so the memory doesn't surface.

As memory grows, this gets worse. Weeks of daily notes, preferences, project decisions — all technically there, increasingly unfindable.

Enter QMD

QMD (Query Markup Documents) is a local search engine for Markdown files built by Tobi Lütke (founder of Shopify). It combines three search strategies:

• BM25 full-text search — fast keyword matching, great for exact terms, IDs, error messages

• Vector semantic search — finds conceptually similar content even when wording differs

• LLM re-ranking — merges both result sets and re-ranks them with a local model for best quality

The whole thing runs locally via node-llama-cpp with small GGUF models. No API keys, no cloud, no data leaving your machine. OpenClaw already supports QMD as a first-class memory backend — you just have to turn it on.

Important caveat: layers 2 and 3 require a CUDA-capable GPU to be usable in practice. On CPU-only hardware, only BM25 is viable. More on this below.

One claimed benefit: 95%+ reduction in token usage, because retrieval moves off the LLM and onto your machine. Instead of stuffing large chunks of memory into context hoping the model finds the relevant bit, QMD returns only the right snippets.

The Setup

OpenClaw natively supports QMD as a drop-in memory backend. Here's how to enable it.

1. Install QMD

Install the QMD CLI globally via npm (or bun if you have it):

npm install -g @tobilu/qmd --prefix ~/.npm-global

Verify it installed:

~/.npm-global/bin/qmd --version
# qmd 1.0.7

2. Update OpenClaw config

Add a memory section to ~/.openclaw/openclaw.json:

"memory": {
  "backend": "qmd",
  "qmd": {
    "includeDefaultMemory": true,
    "update": { "interval": "5m" },
    "limits": { "maxResults": 6 },
    "scope": {
      "default": "deny",
      "rules": [
        { "action": "allow", "match": { "chatType": "direct" } }
      ]
    }
  }
}

The scope config is important — it restricts QMD memory results to direct/private chats only, so your personal memory doesn't leak into group conversations.

3. Restart the gateway

openclaw gateway restart

The Gotcha: PATH

After restarting, we checked the logs and found this repeating:

qmd collection add failed: spawn qmd ENOENT

OpenClaw couldn't find the qmd binary. The issue: the gateway runs as a systemd service with its own PATH environment variable, and it didn't include the directory where npm installed the binary.

The fix is making sure you install QMD into a directory that's already on the gateway's PATH. Check your gateway service PATH with:

cat ~/.config/systemd/user/openclaw-gateway.service | grep PATH

Then install QMD into a directory from that list — in my case ~/.npm-global/bin was already included, so using --prefix ~/.npm-global during install put the binary exactly where the gateway could find it.

Verifying It Works

Once installed correctly, the gateway logs on restart should look clean — no ENOENT errors, just:

qmd memory startup initialization armed for agent "main"

And you can confirm QMD is actively running:

ps aux | grep qmd
# node .../qmd.js embed ← indexing your memory files

The first-time setup downloads about 2GB of local GGUF models (embedding, reranker, query expansion) — one-time cost, happens automatically in the background.

A Note on Graceful Fallback

One thing I appreciated: if QMD isn't working (binary missing, crash, whatever), OpenClaw silently falls back to the built-in SQLite search. Nothing breaks. You just don't get the upgraded search until it's fixed. That made the whole setup process low-risk — I could debug without losing memory functionality in the meantime.

Hardware Reality Check

After getting QMD running, we wanted to verify that all three search layers actually worked — not just assume they did because the setup completed. Here's what we found on my server (GCP e2-medium: 2 vCPUs, 4 GB RAM, no GPU):

Layer 1 — BM25 ✅ — Fast, lightweight, no model needed. Returns results in milliseconds. This is what OpenClaw uses by default.

Layer 2 — Vector semantic search ❌ — Even qmd vsearch (advertised as 'no reranking') still loads the 1.7B query expansion model before doing vector similarity. On CPU, it pegged both cores at 100% for 15+ minutes and consumed 2.7 GB of 4 GB RAM before I killed it.

Layer 3 — LLM re-ranking ❌ — Same constraint as layer 2, but heavier. Requires the full query expansion + reranking pipeline. Completely impractical without GPU acceleration.

The root cause: QMD detects CUDA, tries to initialize it, fails (no GPU), and falls back to CPU via a try/catch in its internals. The fallback works — it doesn't crash — but CPU inference on a 1.7B model is just too slow for interactive use.

What hardware would make layers 2 & 3 work?

You need a CUDA-capable NVIDIA GPU. In cloud terms, that means something like a GCP g2-standard-4 (NVIDIA L4) or an AWS g4dn.xlarge (NVIDIA T4). A local desktop or workstation with a modern NVIDIA GPU (RTX 3060 or better) would also be more than sufficient. The models QMD uses are small enough that even a mid-range GPU handles them comfortably. The e2-medium class of instance — and any CPU-only VPS — simply isn't the right fit.

Worth It?

If you have a GPU: almost certainly yes. The full pipeline — query expansion, vector similarity, LLM re-ranking — is exactly the kind of retrieval upgrade that makes a real difference as memory grows.

If you're on CPU-only hardware like I am: the honest answer is that you're getting BM25 with extra steps. That's not nothing — QMD's BM25 indexes your files cleanly and integrates tightly with OpenClaw's memory system. But the headline feature (semantic search) won't work until you add a GPU to the picture.

We got through the setup in about 30 minutes, including working through the PATH issue. And BM25 alone is a solid, reliable memory layer — just go in with accurate expectations about what the hardware you're running on can actually deliver.

Tools: OpenClaw · QMD · node-llama-cpp · systemd

Models: embedding-gemma-300M · qwen3-reranker-0.6b · qmd-query-expansion-1.7B

Originally published at https://www.paulbrennaman.me/lab/qmd-memory-search

OpenClaw is the platform that makes this possible: it gives AI agents persistent memory, tool access, scheduled tasks, and a growing number of skills available through ClawHub — thousands of pre-built capabilities you can drop straight into your agent, or have the agent do it. Hank is my instance of that — my assistant, with my tools and skills, running in my infrastructure — available to act on my behalf: on a fixed schedule or proactively when human intent calls for it.

Like a soldier acting on a commander’s intent, Hank doesn’t wait to be told every step — it acts within the spirit of the standing order.

Talking to Hank

I interact with Hank through Telegram — the same app I use to message friends. No special interface, no OpenClaw app to install, no AI provider portal to log into.

That’s by design. OpenClaw supports WhatsApp, iMessage, Discord, Slack, Teams, and more. You pick the channel you already live in, and your agent meets you there. You can even specify which LLM to use for a given conversation — swap to a more powerful model for a complex task, or a faster one from a different provider for a quick question.

This matters more than it might sound. Most AI tools lock you into their interface — a browser tab, a mobile app, a proprietary chat window. With OpenClaw, you’re not switching contexts to use your assistant. You’re just... messaging it. The same way you’d message a colleague or friend a quick question.

It also means Hank is genuinely mobile. Standing in line, sitting on the couch, walking to the car — if I can send a message, I can put Hank to work.

What I Built

Hank, my OpenClaw-powered AI assistant, can:

• Manage Google Workspace: Send emails, check calendar availability, create contacts, and search Drive — all via the gog CLI

• Automate GitHub workflows: Clone repos, create branches, make code changes, and submit pull requests on my behalf

• Update this website: Hank wrote the About page content of my personal website by reading my resume from Google Drive and creating a PR with professionally-written copy

• Search and fetch web content: Research topics, fetch documentation, and summarize findings

This is just scratching the surface of what’s possible — but it gives you a feel for the range.

Why This Matters

Traditional automation requires writing scripts for every task. Even sophisticated tools like Zapier or N8N require you to anticipate every scenario upfront — and the moment your workflow doesn’t fit a predefined template, you’re back to writing code.

With an OpenClaw agent that understands natural language and has access to CLI tools as well as the memory history it has of working with you, the interaction model flips entirely. I can tell Hank “update my About page based on my resume and other details you know about me” and Hank handles:

1. Reading the resume from Google Drive

2. Reading your memory files — MEMORY.md, USER.md, daily notes, knowledge base — to pull in context the resume doesn’t capture

3. Analyzing and reconciling both sources

4. Cloning the personal website repo

5. Making appropriate edits to multiple files

6. Creating a PR with a detailed description

All in one conversational exchange — no template to configure, no workflow to diagram, no brittle automation to maintain.

The deeper implication is that the interface becomes the capability. If you can describe what you want, the agent figures out how to do it. That fundamentally changes what “automation” means.

Technical Architecture

Core Stack

OpenClaw (agentic AI platform), Telegram (chat channel), Claude Sonnet 4.6 (primary model), Claude Opus 4.6 (heavy coding tasks), ChatGPT (fallback).

Integrations

What I’ve connected so far: Google Workspace via gog CLI (Gmail, Calendar, Drive, Contacts); GitHub via gh CLI (repos, PRs, issues, actions); web search, content fetching, web page interactions (Brave Search API, web_fetch, Playwright CLI).

Infrastructure

Runs on Google Cloud Compute Engine (24/7 uptime). Previously ran in a Docker container on my local laptop — moved to GCP so Hank stays available even when my machine is off.

Why I’m Excited About This

It’s not the AI part that excites me. Talking to an LLM? That’s table stakes at this point.

What’s different with OpenClaw is everything around it.

The fact that it meets me in Telegram — the same app I already use — instead of asking me to open another tab or download another tool. The fact that I can swap models mid-conversation, pulling in GPT, Claude, or Grok depending on what I need. The fact that it builds a history with me — it knows how I work, what I’ve done, what I care about — and that context compounds over time.

And then there’s the autonomous piece. Not just answering questions when I ask, but acting on standing orders. Knowing when to do something without me having to trigger it.

But honestly, what might excite me most is the community. OpenClaw has a groundswell around it that is special — thousands building skills on ClawHub, sharing their setups and lessons learned, extending each other’s work. That kind of momentum is rare and it usually means something.

I’m still finding words for all of it. That’s kind of the point — I’m in the middle of it.

What’s Next

This is early-stage experimentation, but the direction is clear. I’m exploring:

• More integrations — connecting Hank to more of the tools I use daily

• Scheduled automation — having Hank proactively handle recurring tasks without me asking

• Autonomous actions — giving Hank standing orders and letting it decide when to act on them, not just when I or a schedule triggers it

• Memory and context — how agents retain and use knowledge about you over time

• Multi-agent workflows — specialized agents working together on complex tasks

I’ll be sharing more on each of these as the work progresses.