mirror of
https://github.com/garrytan/gbrain.git
synced 2026-08-16 18:02:30 +00:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 gbrain-release-bot
|
3ece117449 |
Executable
+84
@@ -0,0 +1,84 @@
|
||||
#!/bin/sh
|
||||
# .agents/gbrain-launcher — MCP-server launcher for the gbrain Codex and
|
||||
# Claude Code plugins. Unix-only (macOS/Linux): needs /bin/sh, executable
|
||||
# bits, and `command -v`. Windows support is a filed follow-up.
|
||||
#
|
||||
# Resolves the gbrain binary (the plugin snapshot cannot ship it — the CLI
|
||||
# installs separately), then execs it with the argv the plugin manifest
|
||||
# pinned. Resolution order:
|
||||
# 1. $GBRAIN_BIN explicit override (must be executable)
|
||||
# 2. `gbrain` on PATH
|
||||
# 3. ~/.bun/bin/gbrain the sanctioned global-install location
|
||||
#
|
||||
# GBRAIN_SURFACE: when set and argv[0] is `serve`, replaces the value of an
|
||||
# existing `--surface <x>` pair, or appends `--surface $GBRAIN_SURFACE` if
|
||||
# the pair is absent — so a user can widen (full) or narrow (verbs) this
|
||||
# machine's plugin surface without editing the plugin snapshot.
|
||||
#
|
||||
# No auto-install by design: an MCP server start must never run a network
|
||||
# install. On a miss this exits 127 with the recovery path on stderr; the
|
||||
# bundled `setup` skill walks the install interactively.
|
||||
|
||||
set -eu
|
||||
|
||||
resolve_bin() {
|
||||
if [ -n "${GBRAIN_BIN:-}" ]; then
|
||||
if [ ! -x "$GBRAIN_BIN" ]; then
|
||||
echo "gbrain-launcher: GBRAIN_BIN='$GBRAIN_BIN' is not an executable file" >&2
|
||||
exit 127
|
||||
fi
|
||||
printf '%s' "$GBRAIN_BIN"
|
||||
return
|
||||
fi
|
||||
# ~/.bun/bin (the sanctioned global-install location) is preferred OVER a
|
||||
# bare PATH lookup: a hostile repo that prepends node_modules/.bin with a
|
||||
# fake `gbrain` must not win over the real install. GBRAIN_BIN (above) is
|
||||
# the explicit escape hatch for a gbrain living elsewhere.
|
||||
if [ -x "${HOME:-}/.bun/bin/gbrain" ]; then
|
||||
printf '%s' "$HOME/.bun/bin/gbrain"
|
||||
return
|
||||
fi
|
||||
if command -v gbrain >/dev/null 2>&1; then
|
||||
command -v gbrain
|
||||
return
|
||||
fi
|
||||
echo "gbrain-launcher: gbrain binary not found." >&2
|
||||
echo " install: bun install -g github:garrytan/gbrain#latest-stable" >&2
|
||||
echo " (the npm package named 'gbrain' is unrelated - do not npm install it)" >&2
|
||||
echo " then run the bundled 'setup' skill to initialize your brain," >&2
|
||||
echo " or set GBRAIN_BIN to an absolute gbrain binary path." >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
BIN="$(resolve_bin)"
|
||||
echo "gbrain-launcher: using $BIN" >&2
|
||||
|
||||
# Surface override — only for `serve` invocations. Rebuilds the positional
|
||||
# params in place (rotate-through-sentinel idiom; no eval, no word-splitting
|
||||
# hazards): replace the value of an existing `--surface <x>` pair, or append
|
||||
# the pair when absent.
|
||||
if [ -n "${GBRAIN_SURFACE:-}" ] && [ "${1:-}" = "serve" ]; then
|
||||
replaced=0
|
||||
expect_value=0
|
||||
set -- "$@" "__gbrain_end__"
|
||||
while [ "$1" != "__gbrain_end__" ]; do
|
||||
a="$1"
|
||||
shift
|
||||
if [ "$expect_value" = 1 ]; then
|
||||
expect_value=0
|
||||
replaced=1
|
||||
set -- "$@" "$GBRAIN_SURFACE"
|
||||
continue
|
||||
fi
|
||||
if [ "$a" = "--surface" ]; then
|
||||
expect_value=1
|
||||
fi
|
||||
set -- "$@" "$a"
|
||||
done
|
||||
shift
|
||||
if [ "$replaced" = 0 ]; then
|
||||
set -- "$@" "--surface" "$GBRAIN_SURFACE"
|
||||
fi
|
||||
fi
|
||||
|
||||
exec "$BIN" "$@"
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"name": "gbrain",
|
||||
"interface": { "displayName": "GBrain" },
|
||||
"plugins": [
|
||||
{
|
||||
"name": "gbrain",
|
||||
"source": { "source": "local", "path": "./" },
|
||||
"policy": { "installation": "AVAILABLE", "authentication": "ON_USE" },
|
||||
"category": "Productivity"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "gbrain",
|
||||
"description": "GBrain — a persistent knowledge brain for your coding agent: hybrid search, synthesis, and cross-session memory.",
|
||||
"owner": { "name": "Garry Tan" },
|
||||
"plugins": [
|
||||
{
|
||||
"name": "gbrain",
|
||||
"source": "./",
|
||||
"description": "Personal knowledge brain for your coding agent — hybrid search, synthesis, and durable cross-session memory, plus a curated brain-first skill set.",
|
||||
"category": "productivity"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"name": "gbrain",
|
||||
"version": "0.46.11.0",
|
||||
"description": "Personal knowledge brain for your coding agent — hybrid search, synthesis, graph traversal, and durable cross-session memory over Postgres/PGLite with pgvector, plus a curated brain-first skill set.",
|
||||
"author": {
|
||||
"name": "Garry Tan",
|
||||
"url": "https://github.com/garrytan"
|
||||
},
|
||||
"homepage": "https://github.com/garrytan/gbrain",
|
||||
"repository": "https://github.com/garrytan/gbrain",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"memory",
|
||||
"knowledge-base",
|
||||
"mcp",
|
||||
"search",
|
||||
"agent",
|
||||
"brain",
|
||||
"pgvector"
|
||||
],
|
||||
"skills": "./plugin/skills/",
|
||||
"mcpServers": {
|
||||
"gbrain": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/.agents/gbrain-launcher",
|
||||
"args": [
|
||||
"serve",
|
||||
"--surface",
|
||||
"starter",
|
||||
"--source-guard"
|
||||
],
|
||||
"cwd": "${CLAUDE_PLUGIN_ROOT}"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,75 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"gbrain": {
|
||||
"command": "./.agents/gbrain-launcher",
|
||||
"args": [
|
||||
"serve",
|
||||
"--surface",
|
||||
"starter",
|
||||
"--source-guard"
|
||||
],
|
||||
"cwd": ".",
|
||||
"env_vars": [
|
||||
"ANTHROPIC_API_KEY",
|
||||
"ANTHROPIC_BASE_URL",
|
||||
"AZURE_OPENAI_API_KEY",
|
||||
"DASHSCOPE_API_KEY",
|
||||
"DATABASE_URL",
|
||||
"DEEPGRAM_API_KEY",
|
||||
"DEEPSEEK_API_KEY",
|
||||
"GBRAIN_BIN",
|
||||
"GBRAIN_BRAIN_ID",
|
||||
"GBRAIN_CHAT_FALLBACK_CHAIN",
|
||||
"GBRAIN_CHAT_MODEL",
|
||||
"GBRAIN_DATABASE_URL",
|
||||
"GBRAIN_EMBEDDING_DIMENSIONS",
|
||||
"GBRAIN_EMBEDDING_IMAGE_OCR",
|
||||
"GBRAIN_EMBEDDING_IMAGE_OCR_MODEL",
|
||||
"GBRAIN_EMBEDDING_MODEL",
|
||||
"GBRAIN_EMBEDDING_MULTIMODAL",
|
||||
"GBRAIN_EMBEDDING_MULTIMODAL_MODEL",
|
||||
"GBRAIN_EXPANSION_MODEL",
|
||||
"GBRAIN_HOME",
|
||||
"GBRAIN_MAX_MARKUP_RATIO",
|
||||
"GBRAIN_MCP_FORCE_SURFACE",
|
||||
"GBRAIN_NO_JUNK_PATTERNS",
|
||||
"GBRAIN_NO_SANITY",
|
||||
"GBRAIN_PAGE_BLOCK_BYTES",
|
||||
"GBRAIN_PAGE_WARN_BYTES",
|
||||
"GBRAIN_REMOTE_CLIENT_SECRET",
|
||||
"GBRAIN_RETRIEVAL_REFLEX",
|
||||
"GBRAIN_RETRIEVAL_REFLEX_WINDOW_TURNS",
|
||||
"GBRAIN_SOURCE",
|
||||
"GBRAIN_SURFACE",
|
||||
"GEMINI_API_KEY",
|
||||
"GOOGLE_GENERATIVE_AI_API_KEY",
|
||||
"GROQ_API_KEY",
|
||||
"HOME",
|
||||
"LITELLM_API_KEY",
|
||||
"LITELLM_BASE_URL",
|
||||
"LLAMA_SERVER_API_KEY",
|
||||
"LLAMA_SERVER_BASE_URL",
|
||||
"LLAMA_SERVER_RERANKER_API_KEY",
|
||||
"LLAMA_SERVER_RERANKER_BASE_URL",
|
||||
"LMSTUDIO_BASE_URL",
|
||||
"MINIMAX_API_KEY",
|
||||
"MISTRAL_API_KEY",
|
||||
"MOONSHOT_API_KEY",
|
||||
"NVIDIA_API_KEY",
|
||||
"OLLAMA_API_KEY",
|
||||
"OLLAMA_BASE_URL",
|
||||
"OPENAI_API_KEY",
|
||||
"OPENAI_BASE_URL",
|
||||
"OPENROUTER_API_KEY",
|
||||
"OPENROUTER_BASE_URL",
|
||||
"PATH",
|
||||
"PERPLEXITY_API_KEY",
|
||||
"PPLX_API_KEY",
|
||||
"TOGETHER_API_KEY",
|
||||
"VOYAGE_API_KEY",
|
||||
"ZEROENTROPY_API_KEY",
|
||||
"ZHIPUAI_API_KEY"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
{
|
||||
"name": "gbrain",
|
||||
"version": "0.46.11.0",
|
||||
"description": "Personal knowledge brain for your coding agent — hybrid search, synthesis, graph traversal, and durable cross-session memory over Postgres/PGLite with pgvector, plus a curated brain-first skill set.",
|
||||
"author": {
|
||||
"name": "Garry Tan",
|
||||
"url": "https://github.com/garrytan"
|
||||
},
|
||||
"homepage": "https://github.com/garrytan/gbrain",
|
||||
"repository": "https://github.com/garrytan/gbrain",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"memory",
|
||||
"knowledge-base",
|
||||
"mcp",
|
||||
"search",
|
||||
"agent",
|
||||
"brain",
|
||||
"pgvector"
|
||||
],
|
||||
"skills": "./plugin/skills/",
|
||||
"mcpServers": "./.codex-plugin/mcp.json",
|
||||
"interface": {
|
||||
"displayName": "GBrain",
|
||||
"shortDescription": "Give your agent a persistent brain: search, synthesis, memory",
|
||||
"longDescription": "GBrain wires a personal knowledge brain into every session: hybrid keyword+vector search, entity graph traversal, synthesis, and memory your agent writes itself — served on the starter MCP surface (the seven memory verbs plus the daily-driver brain ops). Bundles the curated brain-first skill set: setup (walks install + gbrain init), cold-start day-one brain filling, ingest, query, briefing, upgrade, and more. Requires the gbrain CLI (bun install -g github:garrytan/gbrain#latest-stable) and a brain (gbrain init); the bundled setup skill walks the rest. Unix (macOS/Linux) only.",
|
||||
"developerName": "Garry Tan",
|
||||
"category": "Productivity",
|
||||
"capabilities": [
|
||||
"Interactive",
|
||||
"Write"
|
||||
],
|
||||
"websiteURL": "https://github.com/garrytan/gbrain",
|
||||
"defaultPrompt": [
|
||||
"Search my brain, recall context across sessions, and write new memory as we work"
|
||||
],
|
||||
"brandColor": "#1F6F5C"
|
||||
}
|
||||
}
|
||||
@@ -1,12 +0,0 @@
|
||||
# GBrain E2E Test Configuration
|
||||
# Copy to .env.testing and fill in real values
|
||||
#
|
||||
# Tier 1 (required for E2E tests)
|
||||
# Option A: Local Docker Postgres (default)
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/gbrain_test
|
||||
# Option B: Real Supabase instance (tests the actual production path)
|
||||
# DATABASE_URL=postgresql://postgres.[project-ref]:[password]@aws-0-us-east-1.pooler.supabase.com:6543/postgres
|
||||
|
||||
# Tier 2 (required for skill tests, optional for mechanical tests)
|
||||
OPENAI_API_KEY=sk-...
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: Bug Report
|
||||
about: Something isn't working
|
||||
labels: bug
|
||||
---
|
||||
|
||||
**What happened?**
|
||||
|
||||
|
||||
**What did you expect?**
|
||||
|
||||
|
||||
**Steps to reproduce**
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
**Environment**
|
||||
- gbrain version: (`gbrain version`)
|
||||
- OS:
|
||||
- Bun version: (`bun --version`)
|
||||
- Database: Supabase / self-hosted Postgres
|
||||
|
||||
**`gbrain doctor --json` output**
|
||||
```json
|
||||
(paste output here)
|
||||
```
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
name: Feature Request
|
||||
about: Suggest an improvement
|
||||
labels: enhancement
|
||||
---
|
||||
|
||||
**What problem does this solve?**
|
||||
|
||||
|
||||
**What does the solution look like?**
|
||||
|
||||
|
||||
**Alternatives considered**
|
||||
|
||||
@@ -1,92 +0,0 @@
|
||||
name: E2E Tests
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
pull_request:
|
||||
branches: [master]
|
||||
schedule:
|
||||
- cron: '0 6 * * *' # Nightly at 6am UTC
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
tier1:
|
||||
name: Tier 1 (Mechanical)
|
||||
runs-on: ubuntu-latest
|
||||
services:
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg16
|
||||
env:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
POSTGRES_DB: gbrain_test
|
||||
ports:
|
||||
- 5432:5432
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
|
||||
with:
|
||||
bun-version: latest
|
||||
- run: bun install
|
||||
- name: Run Tier 1 E2E tests
|
||||
run: bun test test/e2e/mechanical.test.ts test/e2e/mcp.test.ts
|
||||
env:
|
||||
DATABASE_URL: postgresql://postgres:postgres@localhost:5432/gbrain_test
|
||||
|
||||
tier2:
|
||||
name: Tier 2 (LLM Skills)
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
|
||||
needs: tier1
|
||||
services:
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg16
|
||||
env:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
POSTGRES_DB: gbrain_test
|
||||
ports:
|
||||
- 5432:5432
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
|
||||
with:
|
||||
bun-version: latest
|
||||
- run: bun install
|
||||
- name: Install OpenClaw
|
||||
run: npm install -g openclaw@2026.4.9
|
||||
- name: Configure OpenClaw MCP
|
||||
run: |
|
||||
mkdir -p ~/.openclaw
|
||||
cat > ~/.openclaw/config.json << 'EOF'
|
||||
{
|
||||
"mcpServers": {
|
||||
"gbrain": {
|
||||
"command": "bun",
|
||||
"args": ["run", "src/cli.ts", "serve"],
|
||||
"env": {
|
||||
"DATABASE_URL": "${{ env.DATABASE_URL }}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
- name: Run Tier 2 skill tests
|
||||
run: bun test test/e2e/skills.test.ts
|
||||
env:
|
||||
DATABASE_URL: postgresql://postgres:postgres@localhost:5432/gbrain_test
|
||||
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
@@ -1,48 +0,0 @@
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ['v*']
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build:
|
||||
strategy:
|
||||
matrix:
|
||||
include:
|
||||
- os: macos-latest
|
||||
target: bun-darwin-arm64
|
||||
artifact: gbrain-darwin-arm64
|
||||
- os: ubuntu-latest
|
||||
target: bun-linux-x64
|
||||
artifact: gbrain-linux-x64
|
||||
runs-on: ${{ matrix.os }}
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
|
||||
with:
|
||||
bun-version: latest
|
||||
- run: bun install
|
||||
- run: bun test
|
||||
- run: bun build --compile --target=${{ matrix.target }} --outfile bin/${{ matrix.artifact }} src/cli.ts
|
||||
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
|
||||
with:
|
||||
name: ${{ matrix.artifact }}
|
||||
path: bin/${{ matrix.artifact }}
|
||||
|
||||
release:
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
path: artifacts
|
||||
- name: Create release
|
||||
uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
|
||||
with:
|
||||
files: |
|
||||
artifacts/gbrain-darwin-arm64/gbrain-darwin-arm64
|
||||
artifacts/gbrain-linux-x64/gbrain-linux-x64
|
||||
generate_release_notes: true
|
||||
@@ -1,31 +0,0 @@
|
||||
name: Test
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
pull_request:
|
||||
branches: [master]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
gitleaks:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: gitleaks/gitleaks-action@dcedce43c6f43de0b836d1fe38946645c9c638dc # v2
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
|
||||
with:
|
||||
bun-version: latest
|
||||
- run: bun install
|
||||
- run: bun test
|
||||
-14
@@ -1,14 +0,0 @@
|
||||
node_modules/
|
||||
bin/
|
||||
.DS_Store
|
||||
*.log
|
||||
.env
|
||||
.env.*
|
||||
!.env.*.example
|
||||
.18a49dfd730ff378-00000000.bun-build
|
||||
.18a49f9dfb996f70-00000000.bun-build
|
||||
.gstack/
|
||||
supabase/.temp/
|
||||
.claude/skills/
|
||||
.idea
|
||||
eval/reports/
|
||||
@@ -1,11 +0,0 @@
|
||||
title = "GBrain gitleaks config"
|
||||
|
||||
[allowlist]
|
||||
paths = [
|
||||
'''.env\.testing\.example''',
|
||||
'''.env\.example''',
|
||||
'''test/''',
|
||||
'''skills/''',
|
||||
'''.claude/skills/''',
|
||||
'''GBRAIN_SKILLPACK\.md''',
|
||||
]
|
||||
-1304
File diff suppressed because it is too large
Load Diff
@@ -1,609 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
GBrain is a personal knowledge brain and GStack mod for agent platforms. Pluggable
|
||||
engines: PGLite (embedded Postgres via WASM, zero-config default) or Postgres + pgvector
|
||||
+ hybrid search in a managed Supabase instance. `gbrain init` defaults to PGLite;
|
||||
suggests Supabase for 1000+ files. GStack teaches agents how to code. GBrain teaches
|
||||
agents everything else: brain ops, signal detection, content ingestion, enrichment,
|
||||
cron scheduling, reports, identity, and access control.
|
||||
|
||||
## Architecture
|
||||
|
||||
Contract-first: `src/core/operations.ts` defines ~41 shared operations (adds `find_orphans` in v0.12.3). CLI and MCP
|
||||
server are both generated from this single source. Engine factory (`src/core/engine-factory.ts`)
|
||||
dynamically imports the configured engine (`'pglite'` or `'postgres'`). Skills are fat
|
||||
markdown files (tool-agnostic, work with both CLI and plugin contexts).
|
||||
|
||||
**Trust boundary:** `OperationContext.remote` distinguishes trusted local CLI callers
|
||||
(`remote: false` set by `src/cli.ts`) from untrusted agent-facing callers
|
||||
(`remote: true` set by `src/mcp/server.ts`). Security-sensitive operations like
|
||||
`file_upload` tighten filesystem confinement when `remote=true` and default to
|
||||
strict behavior when unset.
|
||||
|
||||
## Key files
|
||||
|
||||
- `src/core/operations.ts` — Contract-first operation definitions (the foundation). Also exports upload validators: `validateUploadPath`, `validatePageSlug`, `validateFilename`. `OperationContext.remote` flags untrusted callers.
|
||||
- `src/core/engine.ts` — Pluggable engine interface (BrainEngine). `clampSearchLimit(limit, default, cap)` takes an explicit cap so per-operation caps can be tighter than `MAX_SEARCH_LIMIT`. Exports `LinkBatchInput` / `TimelineBatchInput` for the v0.12.1 bulk-insert API (`addLinksBatch` / `addTimelineEntriesBatch`).
|
||||
- `src/core/engine-factory.ts` — Engine factory with dynamic imports (`'pglite'` | `'postgres'`)
|
||||
- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders.
|
||||
- `src/core/pglite-schema.ts` — PGLite-specific DDL (pgvector, pg_trgm, triggers)
|
||||
- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query.
|
||||
- `src/core/utils.ts` — Shared SQL utilities extracted from postgres-engine.ts. Exports `parseEmbedding(value)` (throws on unknown input, used by migration + ingest paths where data integrity matters) and as of v0.12.3 `tryParseEmbedding(value)` (returns `null` + warns once per process, used by search/rescore paths where availability matters more than strictness).
|
||||
- `src/core/db.ts` — Connection management, schema initialization
|
||||
- `src/commands/migrate-engine.ts` — Bidirectional engine migration (`gbrain migrate --to supabase/pglite`)
|
||||
- `src/core/import-file.ts` — importFromFile + importFromContent (chunk + embed + tags)
|
||||
- `src/core/sync.ts` — Pure sync functions (manifest parsing, filtering, slug conversion)
|
||||
- `src/core/storage.ts` — Pluggable storage interface (S3, Supabase Storage, local)
|
||||
- `src/core/supabase-admin.ts` — Supabase admin API (project discovery, pgvector check)
|
||||
- `src/core/file-resolver.ts` — File resolution with fallback chain (local -> .redirect.yaml -> .redirect -> .supabase)
|
||||
- `src/core/chunkers/` — 3-tier chunking (recursive, semantic, LLM-guided)
|
||||
- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup
|
||||
- `src/core/search/intent.ts` — Query intent classifier (entity/temporal/event/general → auto-selects detail level)
|
||||
- `src/core/search/eval.ts` — Retrieval eval harness: P@k, R@k, MRR, nDCG@k metrics + runEval() orchestrator
|
||||
- `src/commands/eval.ts` — `gbrain eval` command: single-run table + A/B config comparison
|
||||
- `src/core/embedding.ts` — OpenAI text-embedding-3-large, batch, retry, backoff
|
||||
- `src/core/check-resolvable.ts` — Resolver validation: reachability, MECE overlap, DRY checks, structured fix objects. v0.14.1: `CROSS_CUTTING_PATTERNS.conventions` is an array (notability gate accepts both `conventions/quality.md` and `_brain-filing-rules.md`). New `extractDelegationTargets()` parses `> **Convention:**`, `> **Filing rule:**`, and inline backtick references. DRY suppression is proximity-based via `DRY_PROXIMITY_LINES = 40`.
|
||||
- `src/core/dry-fix.ts` — `gbrain doctor --fix` engine. `autoFixDryViolations(fixes, {dryRun})` rewrites inlined rules to `> **Convention:** see [path](path).` callouts via three shape-aware expanders (bullet / blockquote / paragraph). Five guards: working-tree-dirty (`getWorkingTreeStatus()` returns 3-state `'clean' | 'dirty' | 'not_a_repo'`), no-git-backup, inside-code-fence, already-delegated (40-line proximity, consistent with detector), ambiguous-multi-match, block-is-callout. `execFileSync` array args (no shell — no injection surface). EOF newline preserved.
|
||||
- `src/core/backoff.ts` — Adaptive load-aware throttling: CPU/memory checks, exponential backoff, active hours multiplier
|
||||
- `src/core/fail-improve.ts` — Deterministic-first, LLM-fallback loop with JSONL failure logging and auto-test generation
|
||||
- `src/core/transcription.ts` — Audio transcription: Groq Whisper (default), OpenAI fallback, ffmpeg segmentation for >25MB
|
||||
- `src/core/enrichment-service.ts` — Global enrichment service: entity slug generation, tier auto-escalation, batch throttling
|
||||
- `src/core/data-research.ts` — Recipe validation, field extraction (MRR/ARR regex), dedup, tracker parsing, HTML stripping
|
||||
- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs).
|
||||
- `src/commands/graph-query.ts` — `gbrain graph-query <slug> [--type T] [--depth N] [--direction in|out|both]`: typed-edge relationship traversal (renders indented tree)
|
||||
- `src/core/link-extraction.ts` — shared library for the v0.12.0 graph layer. extractEntityRefs (canonical, replaces backlinks.ts duplicate) matches both `[Name](people/slug)` markdown links and Obsidian `[[people/slug|Name]]` wikilinks as of v0.12.3. extractPageLinks, inferLinkType heuristics (attended/works_at/invested_in/founded/advises/source/mentions), parseTimelineEntries, isAutoLinkEnabled config helper. `DIR_PATTERN` covers `people`, `companies`, `deals`, `topics`, `concepts`, `projects`, `entities`, `tech`, `finance`, `personal`, `openclaw`. Used by extract.ts, operations.ts auto-link post-hook, and backlinks.ts.
|
||||
- `src/core/minions/` — Minions job queue: BullMQ-inspired, Postgres-native (queue, worker, backoff, types)
|
||||
- `src/core/minions/queue.ts` — MinionQueue class (submit, claim, complete, fail, stall detection, parent-child, depth/child-cap, per-job timeouts, cascade-kill, attachments, idempotency keys, child_done inbox, removeOnComplete/Fail). `add()` takes a 4th `trusted` arg (separate from `opts` to prevent spread leakage); protected names in `PROTECTED_JOB_NAMES` require `{allowProtectedSubmit: true}` and the check runs trim-normalized (whitespace-bypass safe).
|
||||
- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't.
|
||||
- `src/core/minions/protected-names.ts` — side-effect-free constant module exporting `PROTECTED_JOB_NAMES` + `isProtectedJobName()`. Kept pure so queue core can import without loading handler modules.
|
||||
- `src/core/minions/handlers/shell.ts` — `shell` job handler. Spawns `/bin/sh -c cmd` (absolute path, PATH-override-safe) or `argv[0] argv[1..]` (no shell). Env allowlist: `PATH, HOME, USER, LANG, TZ, NODE_ENV` + caller `env:` overrides. UTF-8-safe stdout/stderr tail via `string_decoder.StringDecoder`. Abort (either `ctx.signal` or `ctx.shutdownSignal`) fires SIGTERM → 5s grace → SIGKILL on child. Requires `GBRAIN_ALLOW_SHELL_JOBS=1` on worker (gated by `registerBuiltinHandlers`).
|
||||
- `src/core/minions/handlers/shell-audit.ts` — per-submission JSONL audit trail at `~/.gbrain/audit/shell-jobs-YYYY-Www.jsonl` (ISO-week rotation; override via `GBRAIN_AUDIT_DIR`). Best-effort: `mkdirSync(recursive)` + `appendFileSync`; failures logged to stderr, submission not blocked. Logs cmd (first 80 chars) or argv (JSON array). Never logs env values.
|
||||
- `src/core/minions/attachments.ts` — Attachment validation (path traversal, null byte, oversize, base64, duplicate detection)
|
||||
- `src/commands/jobs.ts` — `gbrain jobs` CLI subcommands + `gbrain jobs work` daemon
|
||||
- `src/commands/features.ts` — `gbrain features --json --auto-fix`: usage scan + feature adoption salesman
|
||||
- `src/commands/autopilot.ts` — `gbrain autopilot --install`: self-maintaining brain daemon (sync+extract+embed)
|
||||
- `src/mcp/server.ts` — MCP stdio server (generated from operations)
|
||||
- `src/commands/auth.ts` — Standalone token management (create/list/revoke/test)
|
||||
- `src/commands/upgrade.ts` — Self-update CLI. `runPostUpgrade()` enumerates migrations from the TS registry (src/commands/migrations/index.ts) and tail-calls `runApplyMigrations(['--yes', '--non-interactive'])` so the mechanical side of every outstanding migration runs unconditionally.
|
||||
- `src/commands/migrations/` — TS migration registry (compiled into the binary; no filesystem walk of `skills/migrations/*.md` needed at runtime). `index.ts` lists migrations in semver order. `v0_11_0.ts` = Minions adoption orchestrator (8 phases). `v0_12_0.ts` = Knowledge Graph auto-wire orchestrator (5 phases: schema → config check → backfill links → backfill timeline → verify). `phaseASchema` has a 600s timeout (bumped from 60s in v0.12.1 for duplicate-heavy brains). `v0_12_2.ts` = JSONB double-encode repair orchestrator (4 phases: schema → repair-jsonb → verify → record). `v0_14_0.ts` = shell-jobs + autopilot cooperative (2 phases: schema ALTER minion_jobs.max_stalled SET DEFAULT 3, pending-host-work ping for skills/migrations/v0.14.0.md). All orchestrators are idempotent and resumable from `partial` status. As of v0.14.2 (Bug 3), the RUNNER owns all ledger writes — orchestrators return `OrchestratorResult` and `apply-migrations.ts` persists a canonical `{version, status, phases}` shape after return. Orchestrators no longer call `appendCompletedMigration` directly. `statusForVersion` prefers `complete` over `partial` (never regresses). 3 consecutive partials → wedged → `--force-retry <version>` writes a `'retry'` reset marker.
|
||||
- `src/commands/repair-jsonb.ts` — `gbrain repair-jsonb [--dry-run] [--json]`: rewrites `jsonb_typeof='string'` rows in place across 5 affected columns (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter). Fixes v0.12.0 double-encode bug on Postgres; PGLite no-ops. Idempotent.
|
||||
- `src/commands/orphans.ts` — `gbrain orphans [--json] [--count] [--include-pseudo]`: surfaces pages with zero inbound wikilinks, grouped by domain. Auto-generated/raw/pseudo pages filtered by default. Also exposed as `find_orphans` MCP operation. Shipped in v0.12.3 (contributed by @knee5).
|
||||
- `src/commands/doctor.ts` — `gbrain doctor [--json] [--fast] [--fix] [--dry-run]`: health checks. v0.12.3 adds two reliability detection checks: `jsonb_integrity` (scans pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata for `jsonb_typeof='string'` rows left over from v0.12.0) and `markdown_body_completeness` (flags pages whose compiled_truth is <30% of raw source when raw has multiple H2/H3 boundaries). Fix hints point at `gbrain repair-jsonb` and `gbrain sync --force`. v0.14.1: `--fix` delegates inlined cross-cutting rules to `> **Convention:** see [path](path).` callouts (pipes DRY violations into `src/core/dry-fix.ts`); `--fix --dry-run` previews without writing.
|
||||
- `src/core/markdown.ts` — Frontmatter parsing + body splitter. `splitBody` requires an explicit timeline sentinel (`<!-- timeline -->`, `--- timeline ---`, or `---` immediately before `## Timeline`/`## History`). Plain `---` in body text is a markdown horizontal rule, not a separator. `inferType` auto-types `/wiki/analysis/` → analysis, `/wiki/guides/` → guide, `/wiki/hardware/` → hardware, `/wiki/architecture/` → architecture, `/writing/` → writing (plus the existing people/companies/deals/etc heuristics).
|
||||
- `scripts/check-jsonb-pattern.sh` — CI grep guard. Fails the build if anyone reintroduces the `${JSON.stringify(x)}::jsonb` interpolation pattern (which postgres.js v3 double-encodes). Wired into `bun test`.
|
||||
- `docs/UPGRADING_DOWNSTREAM_AGENTS.md` — Patches for downstream agent skill forks to apply when upgrading. Each release appends a new section. v0.10.3 includes diffs for brain-ops, meeting-ingestion, signal-detector, enrich.
|
||||
- `src/core/schema-embedded.ts` — AUTO-GENERATED from schema.sql (run `bun run build:schema`)
|
||||
- `src/schema.sql` — Full Postgres + pgvector DDL (source of truth, generates schema-embedded.ts)
|
||||
- `src/commands/integrations.ts` — Standalone integration recipe management (no DB needed). Exports `getRecipeDirs()` (trust-tagged recipe sources), SSRF helpers (`isInternalUrl`, `parseOctet`, `hostnameToOctets`, `isPrivateIpv4`). Only package-bundled recipes are `embedded=true`; `$GBRAIN_RECIPES_DIR` and cwd `./recipes/` are untrusted and cannot run `command`/`http`/string health checks.
|
||||
- `src/core/search/expansion.ts` — Multi-query expansion via Haiku. Exports `sanitizeQueryForPrompt` + `sanitizeExpansionOutput` (prompt-injection defense-in-depth). Sanitized query is only used for the LLM channel; original query still drives search.
|
||||
- `recipes/` — Integration recipe files (YAML frontmatter + markdown setup instructions)
|
||||
- `docs/guides/` — Individual SKILLPACK guides (broken out from monolith)
|
||||
- `docs/integrations/` — "Getting Data In" guides and integration docs
|
||||
- `docs/architecture/infra-layer.md` — Shared infrastructure documentation
|
||||
- `docs/ethos/THIN_HARNESS_FAT_SKILLS.md` — Architecture philosophy essay
|
||||
- `docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md` — "Homebrew for Personal AI" essay
|
||||
- `docs/guides/repo-architecture.md` — Two-repo pattern (agent vs brain)
|
||||
- `docs/guides/sub-agent-routing.md` — Model routing table for sub-agents
|
||||
- `docs/guides/skill-development.md` — 5-step skill development cycle + MECE
|
||||
- `docs/guides/idea-capture.md` — Originality distribution, depth test, cross-linking
|
||||
- `docs/guides/quiet-hours.md` — Notification hold + timezone-aware delivery
|
||||
- `docs/guides/diligence-ingestion.md` — Data room to brain pages pipeline
|
||||
- `docs/designs/HOMEBREW_FOR_PERSONAL_AI.md` — 10-star vision for integration system
|
||||
- `docs/mcp/` — Per-client setup guides (Claude Desktop, Code, Cowork, Perplexity)
|
||||
- `docs/benchmarks/` — Search quality benchmark results (reproducible, fictional data)
|
||||
- `skills/_brain-filing-rules.md` — Cross-cutting brain filing rules (referenced by all brain-writing skills)
|
||||
- `skills/RESOLVER.md` — Skill routing table (based on the agent-fork AGENTS.md pattern)
|
||||
- `skills/conventions/` — Cross-cutting rules (quality, brain-first, model-routing, test-before-bulk, cross-modal)
|
||||
- `skills/_output-rules.md` — Output quality standards (deterministic links, no slop, exact phrasing)
|
||||
- `skills/signal-detector/SKILL.md` — Always-on idea+entity capture on every message
|
||||
- `skills/brain-ops/SKILL.md` — Brain-first lookup, read-enrich-write loop, source attribution
|
||||
- `skills/idea-ingest/SKILL.md` — Links/articles/tweets with author people page mandatory
|
||||
- `skills/media-ingest/SKILL.md` — Video/audio/PDF/book with entity extraction
|
||||
- `skills/meeting-ingestion/SKILL.md` — Transcripts with attendee enrichment chaining
|
||||
- `skills/citation-fixer/SKILL.md` — Citation format auditing and fixing
|
||||
- `skills/repo-architecture/SKILL.md` — Filing rules by primary subject
|
||||
- `skills/skill-creator/SKILL.md` — Create conforming skills with MECE check
|
||||
- `skills/daily-task-manager/SKILL.md` — Task lifecycle with priority levels
|
||||
- `skills/daily-task-prep/SKILL.md` — Morning prep with calendar context
|
||||
- `skills/cross-modal-review/SKILL.md` — Quality gate via second model
|
||||
- `skills/cron-scheduler/SKILL.md` — Schedule staggering, quiet hours, idempotency
|
||||
- `skills/reports/SKILL.md` — Timestamped reports with keyword routing
|
||||
- `skills/testing/SKILL.md` — Skill validation framework
|
||||
- `skills/soul-audit/SKILL.md` — 6-phase interview for SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md
|
||||
- `skills/webhook-transforms/SKILL.md` — External events to brain signals
|
||||
- `skills/data-research/SKILL.md` — Structured data research: email-to-tracker pipeline with parameterized YAML recipes
|
||||
- `skills/minion-orchestrator/SKILL.md` — Background job orchestration: submit, fan out children with depth/cap/timeouts, collect results via child_done inbox
|
||||
- `templates/` — SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md templates
|
||||
- `skills/migrations/` — Version migration files with feature_pitch YAML frontmatter
|
||||
- `src/commands/publish.ts` — Deterministic brain page publisher (code+skill pair, zero LLM calls)
|
||||
- `src/commands/backlinks.ts` — Back-link checker and fixer (enforces Iron Law)
|
||||
- `src/commands/lint.ts` — Page quality linter (catches LLM artifacts, placeholder dates)
|
||||
- `src/commands/report.ts` — Structured report saver (audit trail for maintenance/enrichment)
|
||||
- `openclaw.plugin.json` — ClawHub bundle plugin manifest
|
||||
|
||||
## Commands
|
||||
|
||||
Run `gbrain --help` or `gbrain --tools-json` for full command reference.
|
||||
|
||||
Key commands added in v0.7:
|
||||
- `gbrain init` — defaults to PGLite (no Supabase needed), scans repo size, suggests Supabase for 1000+ files
|
||||
- `gbrain migrate --to supabase` / `gbrain migrate --to pglite` — bidirectional engine migration
|
||||
|
||||
Key commands added for Minions (job queue):
|
||||
- `gbrain jobs submit <name> [--params JSON] [--follow] [--dry-run]` — submit a background job
|
||||
- `gbrain jobs list [--status S] [--queue Q]` — list jobs with filters
|
||||
- `gbrain jobs get <id>` — job details with attempt history
|
||||
- `gbrain jobs cancel/retry/delete <id>` — manage job lifecycle
|
||||
- `gbrain jobs prune [--older-than 30d]` — clean old completed/dead jobs
|
||||
- `gbrain jobs stats` — job health dashboard
|
||||
- `gbrain jobs work [--queue Q] [--concurrency N]` — start worker daemon (Postgres only)
|
||||
|
||||
Key commands added in v0.12.2:
|
||||
- `gbrain repair-jsonb [--dry-run] [--json]` — repair double-encoded JSONB rows left over from v0.12.0-and-earlier Postgres writes. Idempotent; PGLite no-ops. The `v0_12_2` migration runs this automatically on `gbrain upgrade`.
|
||||
|
||||
Key commands added in v0.12.3:
|
||||
- `gbrain orphans [--json] [--count] [--include-pseudo]` — surface pages with zero inbound wikilinks, grouped by domain. Auto-generated/raw/pseudo pages filtered by default. Also exposed as `find_orphans` MCP operation. The natural consumer of the v0.12.0 knowledge graph layer: once edges are captured, find the gaps.
|
||||
- `gbrain doctor` gains two new reliability detection checks: `jsonb_integrity` (v0.12.0 Postgres double-encode damage) and `markdown_body_completeness` (pages truncated by the old splitBody bug). Detection only; fix hints point at `gbrain repair-jsonb` and `gbrain sync --force`.
|
||||
|
||||
Key commands added in v0.14.2:
|
||||
- `gbrain sync --skip-failed` — acknowledge the current set of failed-parse files recorded in `~/.gbrain/sync-failures.jsonl` so the sync bookmark advances past them. Doctor's `sync_failures` check shows previously-skipped as "all acknowledged" instead of warning.
|
||||
- `gbrain sync --retry-failed` — re-walk the unacknowledged failures and re-attempt parsing. If the files now succeed, they clear from the set and the bookmark advances naturally.
|
||||
- `gbrain apply-migrations --force-retry <version>` — reset a wedged migration (3 consecutive partials with no completion) by appending a `'retry'` marker. Next `apply-migrations --yes` treats the version as fresh. `complete` status never regresses to `partial` either before or after a retry marker.
|
||||
- `GBRAIN_POOL_SIZE` env var — honored by both the singleton pool (`src/core/db.ts`) and the parallel-import worker pool (`src/commands/import.ts`). Default is 10; lower to 2 for Supabase transaction pooler to avoid MaxClients crashes during `gbrain upgrade` subprocess spawns. Read at call time via `resolvePoolSize()`.
|
||||
- `gbrain doctor` gains two new checks: `sync_failures` (surfaces unacknowledged parse failures with exact paths + fix hints) and `brain_score` (renders the 5-component breakdown when score < 100: embed coverage / 35, link density / 25, timeline coverage / 15, orphans / 15, dead links / 10 — sum equals total).
|
||||
|
||||
## Testing
|
||||
|
||||
`bun test` runs all tests. After the v0.12.1 release: ~75 unit test files + 8 E2E test files (1412 unit pass, 119 E2E when `DATABASE_URL` is set — skip gracefully otherwise). Unit tests run
|
||||
without a database. E2E tests skip gracefully when `DATABASE_URL` is not set.
|
||||
|
||||
Unit tests: `test/markdown.test.ts` (frontmatter parsing), `test/chunkers/recursive.test.ts`
|
||||
(chunking), `test/parity.test.ts` (operations contract
|
||||
parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redaction),
|
||||
`test/files.test.ts` (MIME/hash), `test/import-file.test.ts` (import pipeline),
|
||||
`test/upgrade.test.ts` (schema migrations),
|
||||
`test/file-migration.test.ts` (file migration), `test/file-resolver.test.ts` (file resolution),
|
||||
`test/import-resume.test.ts` (import checkpoints), `test/migrate.test.ts` (migration; v8/v9 helper-btree-index SQL structural assertions + 1000-row wall-clock fixtures that guard the O(n²)→O(n log n) fix),
|
||||
`test/setup-branching.test.ts` (setup flow), `test/slug-validation.test.ts` (slug validation),
|
||||
`test/storage.test.ts` (storage backends), `test/supabase-admin.test.ts` (Supabase admin),
|
||||
`test/yaml-lite.test.ts` (YAML parsing), `test/check-update.test.ts` (version check + update CLI),
|
||||
`test/pglite-engine.test.ts` (PGLite engine, all 40 BrainEngine methods including 11 cases for `addLinksBatch` / `addTimelineEntriesBatch`: empty batch, missing optionals, within-batch dedup via ON CONFLICT, missing-slug rows dropped by JOIN, half-existing batch, batch of 100),
|
||||
`test/engine-factory.test.ts` (engine factory + dynamic imports),
|
||||
`test/integrations.test.ts` (recipe parsing, CLI routing, recipe validation),
|
||||
`test/publish.test.ts` (content stripping, encryption, password generation, HTML output),
|
||||
`test/backlinks.test.ts` (entity extraction, back-link detection, timeline entry generation),
|
||||
`test/lint.test.ts` (LLM artifact detection, code fence stripping, frontmatter validation),
|
||||
`test/report.test.ts` (report format, directory structure),
|
||||
`test/skills-conformance.test.ts` (skill frontmatter + required sections validation),
|
||||
`test/resolver.test.ts` (RESOLVER.md coverage, routing validation),
|
||||
`test/search.test.ts` (RRF normalization, compiled truth boost, cosine similarity, dedup key),
|
||||
`test/dedup.test.ts` (source-aware dedup, compiled truth guarantee, layer interactions),
|
||||
`test/intent.test.ts` (query intent classification: entity/temporal/event/general),
|
||||
`test/eval.test.ts` (retrieval metrics: precisionAtK, recallAtK, mrr, ndcgAtK, parseQrels),
|
||||
`test/check-resolvable.test.ts` (resolver reachability, MECE overlap, gap detection, DRY checks + v0.14.1 proximity-based DRY detection + `extractDelegationTargets` coverage — 13 DRY cases),
|
||||
`test/dry-fix.test.ts` (v0.14.1 auto-fix: three shape-aware expander pure-function tests, five guards — working-tree-dirty, no-git-backup, inside-code-fence, already-delegated within 40 lines, ambiguous-multi-match, block-is-callout — 28 cases),
|
||||
`test/doctor-fix.test.ts` (v0.14.1 `gbrain doctor --fix` CLI integration: dry-run preview, apply path, JSON output shape — 3 cases),
|
||||
`test/backoff.test.ts` (load-aware throttling, concurrency limits, active hours),
|
||||
`test/fail-improve.test.ts` (deterministic/LLM cascade, JSONL logging, test generation, rotation),
|
||||
`test/transcription.test.ts` (provider detection, format validation, API key errors),
|
||||
`test/enrichment-service.test.ts` (entity slugification, extraction, tier escalation),
|
||||
`test/data-research.test.ts` (recipe validation, MRR/ARR extraction, dedup, tracker parsing, HTML stripping),
|
||||
`test/minions.test.ts` (Minions job queue v7: CRUD, state machine, backoff, stall detection, dependencies, worker lifecycle, lock management, claim mechanics, depth/child-cap, timeouts, cascade kill, idempotency, child_done inbox, attachments, removeOnComplete/Fail),
|
||||
`test/extract.test.ts` (link extraction, timeline extraction, frontmatter parsing, directory type inference),
|
||||
`test/extract-db.test.ts` (gbrain extract --source db: typed link inference, idempotency, --type filter, --dry-run JSON output),
|
||||
`test/extract-fs.test.ts` (gbrain extract --source fs: first-run inserts + second-run reports zero, dry-run dedups candidates across files, second-run perf regression guard — the v0.12.1 N+1 dedup bug),
|
||||
`test/link-extraction.test.ts` (canonical extractEntityRefs both formats, extractPageLinks dedup, inferLinkType heuristics, parseTimelineEntries date variants, isAutoLinkEnabled config),
|
||||
`test/graph-query.test.ts` (direction in/out/both, type filter, indented tree output),
|
||||
`test/features.test.ts` (feature scanning, brain_score calculation, CLI routing, persistence),
|
||||
`test/file-upload-security.test.ts` (symlink traversal, cwd confinement, slug + filename allowlists, remote vs local trust),
|
||||
`test/query-sanitization.test.ts` (prompt-injection stripping, output sanitization, structural boundary),
|
||||
`test/search-limit.test.ts` (clampSearchLimit default/cap behavior across list_pages and get_ingest_log),
|
||||
`test/repair-jsonb.test.ts` (v0.12.2 JSONB repair: TARGETS list, idempotency, engine-awareness),
|
||||
`test/migrations-v0_12_2.test.ts` (v0.12.2 orchestrator phases: schema → repair → verify → record),
|
||||
`test/markdown.test.ts` (splitBody sentinel precedence, horizontal-rule preservation, inferType wiki subtypes),
|
||||
`test/orphans.test.ts` (v0.12.3 orphans command: detection, pseudo filtering, text/json/count outputs, MCP op),
|
||||
`test/postgres-engine.test.ts` (v0.12.3 statement_timeout scoping: `sql.begin` + `SET LOCAL` shape, source-level grep guardrail against reintroduced bare `SET statement_timeout`),
|
||||
`test/sync.test.ts` (sync logic + v0.12.3 regression guard asserting top-level `engine.transaction` is not called),
|
||||
`test/doctor.test.ts` (doctor command + v0.12.3 assertions that `jsonb_integrity` scans the four v0.12.0 write sites and `markdown_body_completeness` is present),
|
||||
`test/utils.test.ts` (shared SQL utilities + `tryParseEmbedding` null-return and single-warn semantics).
|
||||
|
||||
E2E tests (`test/e2e/`): Run against real Postgres+pgvector. Require `DATABASE_URL`.
|
||||
- `bun run test:e2e` runs Tier 1 (mechanical, all operations, no API keys). Includes 9 dedicated cases for the postgres-engine `addLinksBatch` / `addTimelineEntriesBatch` bind path — postgres-js's `unnest()` binding is structurally different from PGLite's and gets its own coverage.
|
||||
- `test/e2e/search-quality.test.ts` runs search quality E2E against PGLite (no API keys, in-memory)
|
||||
- `test/e2e/graph-quality.test.ts` runs the v0.10.3 knowledge graph pipeline (auto-link via put_page, reconciliation, traversePaths) against PGLite in-memory
|
||||
- `test/e2e/postgres-jsonb.test.ts` — v0.12.2 regression test. Round-trips all 5 JSONB write sites (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter) against real Postgres and asserts `jsonb_typeof='object'` plus `->>'key'` returns the expected scalar. The test that should have caught the original double-encode bug.
|
||||
- `test/e2e/jsonb-roundtrip.test.ts` — v0.12.3 companion regression against the 4 doctor-scanned JSONB sites. Assertion-level overlap with `postgres-jsonb.test.ts` is intentional defense-in-depth: if doctor's scan surface ever drifts from the actual write surface, one of these tests catches it.
|
||||
- `test/e2e/upgrade.test.ts` runs check-update E2E against real GitHub API (network required)
|
||||
- Tier 2 (`skills.test.ts`) requires OpenClaw + API keys, runs nightly in CI
|
||||
- If `.env.testing` doesn't exist in this directory, check sibling worktrees for one:
|
||||
`find ../ -maxdepth 2 -name .env.testing -print -quit` and copy it here if found.
|
||||
- Always run E2E tests when they exist. Do not skip them just because DATABASE_URL
|
||||
is not set. Start the test DB, run the tests, then tear it down.
|
||||
|
||||
### API keys and running ALL tests
|
||||
|
||||
ALWAYS source the user's shell profile before running tests:
|
||||
|
||||
```bash
|
||||
source ~/.zshrc 2>/dev/null || true
|
||||
```
|
||||
|
||||
This loads `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`. Without these, Tier 2 tests
|
||||
skip silently. Do NOT skip Tier 2 tests just because they require API keys — load
|
||||
the keys and run them.
|
||||
|
||||
When asked to "run all E2E tests" or "run tests", that means ALL tiers:
|
||||
- Tier 1: `bun run test:e2e` (mechanical, sync, upgrade — no API keys needed)
|
||||
- Tier 2: `test/e2e/skills.test.ts` (requires OpenAI + Anthropic + openclaw CLI)
|
||||
- Always spin up the test DB, source zshrc, run everything, tear down.
|
||||
|
||||
### E2E test DB lifecycle (ALWAYS follow this)
|
||||
|
||||
You are responsible for spinning up and tearing down the test Postgres container.
|
||||
Do not leave containers running after tests. Do not skip E2E tests.
|
||||
|
||||
1. **Check for `.env.testing`** — if missing, copy from sibling worktree.
|
||||
Read it to get the DATABASE_URL (it has the port number).
|
||||
2. **Check if the port is free:**
|
||||
`docker ps --filter "publish=PORT"` — if another container is on that port,
|
||||
pick a different port (try 5435, 5436, 5437) and start on that one instead.
|
||||
3. **Start the test DB:**
|
||||
```bash
|
||||
docker run -d --name gbrain-test-pg \
|
||||
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
|
||||
-e POSTGRES_DB=gbrain_test \
|
||||
-p PORT:5432 pgvector/pgvector:pg16
|
||||
```
|
||||
Wait for ready: `docker exec gbrain-test-pg pg_isready -U postgres`
|
||||
4. **Run E2E tests:**
|
||||
`DATABASE_URL=postgresql://postgres:postgres@localhost:PORT/gbrain_test bun run test:e2e`
|
||||
5. **Tear down immediately after tests finish (pass or fail):**
|
||||
`docker stop gbrain-test-pg && docker rm gbrain-test-pg`
|
||||
|
||||
Never leave `gbrain-test-pg` running. If you find a stale one from a previous run,
|
||||
stop and remove it before starting a new one.
|
||||
|
||||
## Skills
|
||||
|
||||
Read the skill files in `skills/` before doing brain operations. GBrain ships 26 skills
|
||||
organized by `skills/RESOLVER.md`:
|
||||
|
||||
**Original 8 (conformance-migrated):** ingest (thin router), query, maintain, enrich,
|
||||
briefing, migrate, setup, publish.
|
||||
|
||||
**Brain skills (ported from an upstream agent fork):** signal-detector, brain-ops, idea-ingest, media-ingest,
|
||||
meeting-ingestion, citation-fixer, repo-architecture, skill-creator, daily-task-manager.
|
||||
|
||||
**Operational + identity:** daily-task-prep, cross-modal-review, cron-scheduler, reports,
|
||||
testing, soul-audit, webhook-transforms, data-research, minion-orchestrator.
|
||||
|
||||
**Conventions:** `skills/conventions/` has cross-cutting rules (quality, brain-first,
|
||||
model-routing, test-before-bulk, cross-modal). `skills/_brain-filing-rules.md` and
|
||||
`skills/_output-rules.md` are shared references.
|
||||
|
||||
## Build
|
||||
|
||||
`bun build --compile --outfile bin/gbrain src/cli.ts`
|
||||
|
||||
## Pre-ship requirements
|
||||
|
||||
Before shipping (/ship) or reviewing (/review), always run the full test suite:
|
||||
- `bun test` — unit tests (no database required)
|
||||
- Follow the "E2E test DB lifecycle" steps above to spin up the test DB,
|
||||
run `bun run test:e2e`, then tear it down.
|
||||
|
||||
Both must pass. Do not ship with failing E2E tests. Do not skip E2E tests.
|
||||
|
||||
## Post-ship requirements (MANDATORY)
|
||||
|
||||
After EVERY /ship, you MUST run /document-release. This is NOT optional. Do NOT
|
||||
skip it. Do NOT say "docs look fine" without running it. The skill reads every .md
|
||||
file in the project, cross-references the diff, and updates anything that drifted.
|
||||
|
||||
If /ship's Step 8.5 triggers document-release automatically, that counts. But if
|
||||
it gets skipped for ANY reason (timeout, error, oversight), you MUST run it manually
|
||||
before considering the ship complete.
|
||||
|
||||
Files that MUST be checked on every ship:
|
||||
- README.md — does it reflect new features, commands, or setup steps?
|
||||
- CLAUDE.md — does it reflect new files, test files, or architecture changes?
|
||||
- CHANGELOG.md — does it cover every commit?
|
||||
- TODOS.md — are completed items marked done?
|
||||
- docs/ — do any guides need updating?
|
||||
|
||||
A ship without updated docs is an incomplete ship. Period.
|
||||
|
||||
## CHANGELOG voice + release-summary format
|
||||
|
||||
Every version entry in `CHANGELOG.md` MUST start with a release-summary section in
|
||||
the GStack/Garry voice — one viewport's worth of prose + tables that lands like a
|
||||
verdict, not marketing. The itemized changelog (subsections, bullets, files) goes
|
||||
BELOW that summary, separated by a `### Itemized changes` header.
|
||||
|
||||
The release-summary section gets read by humans, by the auto-update agent, and by
|
||||
anyone deciding whether to upgrade. The itemized list is for agents that need to
|
||||
know exactly what changed.
|
||||
|
||||
### Release-summary template
|
||||
|
||||
Use this structure for the top of every `## [X.Y.Z]` entry:
|
||||
|
||||
1. **Two-line bold headline** (10-14 words total) ... should land like a verdict, not
|
||||
marketing. Sound like someone who shipped today and cares whether it works.
|
||||
2. **Lead paragraph** (3-5 sentences) ... what shipped, what changed for the user.
|
||||
Specific, concrete, no AI vocabulary, no em dashes, no hype.
|
||||
3. **A "The X numbers that matter" section** with:
|
||||
- One short setup paragraph naming the source of the numbers (real production
|
||||
deployment OR a reproducible benchmark ... name the file/command to run).
|
||||
- A table of 3-6 key metrics with BEFORE / AFTER / Δ columns.
|
||||
- A second optional table for per-category breakdown if relevant.
|
||||
- 1-2 sentences interpreting the most striking number in concrete user terms.
|
||||
4. **A "What this means for [audience]" closing paragraph** (2-4 sentences) tying
|
||||
the metrics to a real workflow shift. End with what to do.
|
||||
|
||||
Voice rules:
|
||||
- No em dashes (use commas, periods, "...").
|
||||
- No AI vocabulary (delve, robust, comprehensive, nuanced, fundamental, etc.) or
|
||||
banned phrases ("here's the kicker", "the bottom line", etc.).
|
||||
- Real numbers, real file names, real commands. Not "fast" but "~30s on 30K pages."
|
||||
- Short paragraphs, mix one-sentence punches with 2-3 sentence runs.
|
||||
- Connect to user outcomes: "the agent does ~3x less reading" beats "improved
|
||||
precision."
|
||||
- Be direct about quality. "Well-designed" or "this is a mess." No dancing.
|
||||
|
||||
Source material to pull from:
|
||||
- CHANGELOG.md previous entry for prior context
|
||||
- `docs/benchmarks/[latest].md` for the headline numbers
|
||||
- Recent commits (`git log <prev-version>..HEAD --oneline`) for what shipped
|
||||
- Don't make up numbers. If a metric isn't in a benchmark or production data, don't
|
||||
include it. Say "no measurement yet" if asked.
|
||||
|
||||
Target length: ~250-350 words for the summary. Should render as one viewport.
|
||||
|
||||
### "To take advantage of v[version]" block (required, v0.13+)
|
||||
|
||||
After the release-summary and BEFORE `### Itemized changes`, every `## [X.Y.Z]`
|
||||
entry MUST include a human-readable self-repair block under the heading
|
||||
`## To take advantage of v[version]`.
|
||||
|
||||
Why: `gbrain upgrade` runs `gbrain post-upgrade` which runs `gbrain apply-migrations`.
|
||||
This chain has a known weak link — `upgrade.ts` catches post-upgrade failures as
|
||||
best-effort (so the binary still works). When that chain silently fails, users end
|
||||
up with half-upgraded brains. The self-repair block gives them a paste-ready
|
||||
recovery path; the v0.13+ `~/.gbrain/upgrade-errors.jsonl` trail + `gbrain doctor`
|
||||
integration close the loop.
|
||||
|
||||
Template (adapt the verify commands per release):
|
||||
|
||||
```markdown
|
||||
## To take advantage of v[version]
|
||||
|
||||
`gbrain upgrade` should do this automatically. If it didn't, or if `gbrain doctor`
|
||||
warns about a partial migration:
|
||||
|
||||
1. **Run the orchestrator manually:**
|
||||
```bash
|
||||
gbrain apply-migrations --yes
|
||||
```
|
||||
2. **Your agent reads `skills/migrations/v[version].md` the next time you interact with it.**
|
||||
[One sentence on whether headless agents need manual action, or whether the
|
||||
orchestrator already handled the mechanical side.]
|
||||
3. **Verify the outcome:**
|
||||
```bash
|
||||
[release-specific verify commands, e.g. `gbrain graph ... --depth 2`]
|
||||
gbrain stats
|
||||
```
|
||||
4. **If any step fails or the numbers look wrong,** please file an issue:
|
||||
https://github.com/garrytan/gbrain/issues with:
|
||||
- output of `gbrain doctor`
|
||||
- contents of `~/.gbrain/upgrade-errors.jsonl` if it exists
|
||||
- which step broke
|
||||
|
||||
This feedback loop is how the gbrain maintainers find fragile upgrade paths. Thank you.
|
||||
```
|
||||
|
||||
**Skip this block** for patches that are pure bug fixes with zero user-facing action
|
||||
(rare). If the release has a schema migration, data backfill, or new feature the
|
||||
user needs to verify, the block is required.
|
||||
|
||||
The v0.13.0 entry in CHANGELOG.md is the canonical example.
|
||||
|
||||
### Itemized changes (the existing rules)
|
||||
|
||||
Below the release summary, write `### Itemized changes` and continue with the
|
||||
detailed subsections (Knowledge Graph Layer, Schema migrations, Security hardening,
|
||||
Tests, etc.). Same rules as before:
|
||||
|
||||
- Lead with what the user can now DO that they couldn't before
|
||||
- Frame as benefits and capabilities, not files changed or code written
|
||||
- Make the user think "hell yeah, I want that"
|
||||
- Bad: "Added GBRAIN_VERIFY.md installation verification runbook"
|
||||
- Good: "Your agent now verifies the entire GBrain installation end-to-end, catching
|
||||
silent sync failures and stale embeddings before they bite you"
|
||||
- Bad: "Setup skill Phase H and Phase I added"
|
||||
- Good: "New installs automatically set up live sync so your brain never falls behind"
|
||||
- **Always credit community contributions.** When a CHANGELOG entry includes work from
|
||||
a community PR, name the contributor with `Contributed by @username`. Contributors
|
||||
did real work. Thank them publicly every time, no exceptions.
|
||||
|
||||
### Reference: v0.12.0 entry as canonical example
|
||||
|
||||
The v0.12.0 entry in CHANGELOG.md is the canonical example of the format. Match its
|
||||
structure for every future version: bold headline, lead paragraph, "numbers that
|
||||
matter" with BrainBench-style before/after table, "what this means" closer, then
|
||||
`### Itemized changes` with the detailed sections below.
|
||||
|
||||
## Version migrations
|
||||
|
||||
Create a migration file at `skills/migrations/v[version].md` when a release
|
||||
includes changes that existing users need to act on. The auto-update agent
|
||||
reads these files post-upgrade (Section 17, Step 4) and executes them.
|
||||
|
||||
**You need a migration file when:**
|
||||
- New setup step that existing installs don't have (e.g., v0.5.0 added live sync,
|
||||
existing users need to set it up, not just new installs)
|
||||
- New SKILLPACK section with a MUST ADD setup requirement
|
||||
- Schema changes that require `gbrain init` or manual SQL
|
||||
- Changed defaults that affect existing behavior
|
||||
- Deprecated commands or flags that need replacement
|
||||
- New verification steps that should run on existing installs
|
||||
- New cron jobs or background processes that should be registered
|
||||
|
||||
**You do NOT need a migration file when:**
|
||||
- Bug fixes with no behavior changes
|
||||
- Documentation-only improvements (the agent re-reads docs automatically)
|
||||
- New optional features that don't affect existing setups
|
||||
- Performance improvements that are transparent
|
||||
|
||||
**The key test:** if an existing user upgrades and does nothing else, will their
|
||||
brain work worse than before? If yes, migration file. If no, skip it.
|
||||
|
||||
Write migration files as agent instructions, not technical notes. Tell the agent
|
||||
what to do, step by step, with exact commands. See `skills/migrations/v0.5.0.md`
|
||||
for the pattern.
|
||||
|
||||
## Migration is canonical, not advisory
|
||||
|
||||
GBrain's job is to deliver a canonical, working setup to every user on upgrade.
|
||||
Anything that looks like a "host-repo change" — AGENTS.md, cron manifests,
|
||||
launchctl units, config files outside `~/.gbrain/` — is a GBrain migration
|
||||
step, not a nudge we leave for the host-repo maintainer. Migrations edit host
|
||||
files (with backups) to make the canonical setup real. Exceptions: changes
|
||||
that require human judgment (content edits, renames that break semantics,
|
||||
host-specific handler registration where shell-exec would be an RCE surface).
|
||||
Everything mechanical ships in the migration.
|
||||
|
||||
**Test:** if shipping a feature requires a sentence that starts with "in
|
||||
your AGENTS.md, add…" or "in your cron/jobs.json, rewrite…", the migration
|
||||
orchestrator should be doing that edit, not the user.
|
||||
|
||||
**The exception is host-specific code.** For custom Minion handlers
|
||||
(host-specific integrations like inbox sweeps or third-party API scanners), shipping them as a
|
||||
data file the worker would exec is an RCE surface. Those get registered in
|
||||
the host's own repo via the plugin contract (`docs/guides/plugin-handlers.md`);
|
||||
the migration orchestrator emits a structured TODO to
|
||||
`~/.gbrain/migrations/pending-host-work.jsonl` + the host agent walks the
|
||||
TODOs using `skills/migrations/v0.11.0.md` — stays host-agnostic, still
|
||||
canonical.
|
||||
|
||||
## Privacy rule: scrub real names from public docs
|
||||
|
||||
**Never reference real people, companies, funds, or private agent names in any
|
||||
public-facing artifact.** Public artifacts include: `CHANGELOG.md`, `README.md`,
|
||||
`docs/`, `skills/`, PR titles + bodies, commit messages, and comments in checked-in
|
||||
code. Query examples, benchmark stories, and migration guides MUST use generic
|
||||
placeholders.
|
||||
|
||||
Why: gbrain runs a personal knowledge brain containing notes on real people and
|
||||
real companies (YC founders, portfolio companies, funds, investors, meeting
|
||||
attendees). When a doc copies a query like `gbrain graph diana-hu --depth 2` or
|
||||
names a specific agent fork like `Wintermute`, that real name gets indexed by
|
||||
search engines, surfaced in cross-references, and distributed with every release.
|
||||
|
||||
**Name mapping** to use in examples:
|
||||
- Agent forks → `your agent fork`, `a downstream agent`, or `agent-fork`
|
||||
- Example person → `alice-example`, `charlie-example`, or `a-founder`
|
||||
- Example company → `acme-example`, `widget-co`, or `a-company`
|
||||
- Example fund → `fund-a`, `fund-b`, `fund-c`
|
||||
- Example deal → `acme-seed`, `widget-series-a`
|
||||
- Example meeting → `meetings/2026-04-03` (generic date is fine)
|
||||
- Example user → `you` or `the user`, never a proper name
|
||||
|
||||
**When in doubt, ask yourself:** "Would this query reveal private information
|
||||
about the user's contacts, investments, or portfolio if it were read by a
|
||||
stranger?" If yes, replace with generic placeholders.
|
||||
|
||||
**Illustrative API examples with household-brand companies** (Stripe, Brex, OpenAI,
|
||||
GitHub, etc.) are fine — they're public entities, not contacts in anyone's brain.
|
||||
Do not confuse illustrative API examples with queries that reveal real
|
||||
relationships.
|
||||
|
||||
## Schema state tracking
|
||||
|
||||
`~/.gbrain/update-state.json` tracks which recommended schema directories the user
|
||||
adopted, declined, or added custom. The auto-update agent (SKILLPACK Section 17)
|
||||
reads this during upgrades to suggest new schema additions without re-suggesting
|
||||
things the user already declined. The setup skill writes the initial state during
|
||||
Phase C/E. Never modify a user's custom directories or re-suggest declined ones.
|
||||
|
||||
## GitHub Actions SHA maintenance
|
||||
|
||||
All GitHub Actions in `.github/workflows/` are pinned to commit SHAs. Before shipping
|
||||
(`/ship`) or reviewing (`/review`), check for stale pins and update them:
|
||||
|
||||
```bash
|
||||
for action in actions/checkout oven-sh/setup-bun actions/upload-artifact actions/download-artifact softprops/action-gh-release gitleaks/gitleaks-action; do
|
||||
tag=$(grep -r "$action@" .github/workflows/ | head -1 | grep -o '#.*' | tr -d '# ')
|
||||
[ -n "$tag" ] && echo "$action@$tag: $(gh api repos/$action/git/ref/tags/$tag --jq .object.sha 2>/dev/null)"
|
||||
done
|
||||
```
|
||||
|
||||
If any SHA differs from what's in the workflow files, update the pin and version comment.
|
||||
|
||||
## PR descriptions cover the whole branch
|
||||
|
||||
Pull request titles and bodies must describe **everything in the PR diff against the
|
||||
base branch**, not just the most recent commit you made. When you open or update a
|
||||
PR, walk the full commit range with `git log --oneline <base>..<head>` and write the
|
||||
body to cover all of it. Group by feature area (schema, code, tests, docs) — not
|
||||
chronologically by commit.
|
||||
|
||||
This matters because reviewers read the PR body to understand what's shipping. If
|
||||
the body only covers your last commit, they miss everything else and can't review
|
||||
properly. A 7-commit PR with a body that describes commit 7 is worse than no body
|
||||
at all — it actively misleads.
|
||||
|
||||
When in doubt, run `gh pr view <N> --json commits --jq '[.commits[].messageHeadline]'`
|
||||
to see what's actually in the PR before writing the body.
|
||||
|
||||
## Community PR wave process
|
||||
|
||||
Never merge external PRs directly into master. Instead, use the "fix wave" workflow:
|
||||
|
||||
1. **Categorize** — group PRs by theme (bug fixes, features, infra, docs)
|
||||
2. **Deduplicate** — if two PRs fix the same thing, pick the one that changes fewer
|
||||
lines. Close the other with a note pointing to the winner.
|
||||
3. **Collector branch** — create a feature branch (e.g. `garrytan/fix-wave-N`), cherry-pick
|
||||
or manually re-implement the best fixes from each PR. Do NOT merge PR branches directly —
|
||||
read the diff, understand the fix, and write it yourself if needed.
|
||||
4. **Test the wave** — verify with `bun test && bun run test:e2e` (full E2E lifecycle).
|
||||
Every fix in the wave must have test coverage.
|
||||
5. **Close with context** — every closed PR gets a comment explaining why and what (if
|
||||
anything) supersedes it. Contributors did real work; respect that with clear communication
|
||||
and thank them.
|
||||
6. **Ship as one PR** — single PR to master with all attributions preserved via
|
||||
`Co-Authored-By:` trailers. Include a summary of what merged and what closed.
|
||||
|
||||
**Community PR guardrails:**
|
||||
- Always AskUserQuestion before accepting commits that touch voice, tone, or
|
||||
promotional material (README intro, CHANGELOG voice, skill templates).
|
||||
- Never auto-merge PRs that remove YC references or "neutralize" the founder perspective.
|
||||
- Preserve contributor attribution in commit messages.
|
||||
|
||||
## Skill routing
|
||||
|
||||
When the user's request matches an available skill, ALWAYS invoke it using the Skill
|
||||
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
|
||||
The skill has specialized workflows that produce better results than ad-hoc answers.
|
||||
|
||||
**NEVER hand-roll ship operations.** Do not manually run git commit + push + gh pr
|
||||
create when /ship is available. /ship handles VERSION bump, CHANGELOG, document-release,
|
||||
pre-landing review, test coverage audit, and adversarial review. Manually creating a PR
|
||||
skips all of these. If the user says "commit and ship", "push and ship", "bisect and
|
||||
ship", or any combination that ends with shipping — invoke /ship and let it handle
|
||||
everything including the commits. If the branch name contains a version (e.g.
|
||||
`v0.5-live-sync`), /ship should use that version for the bump.
|
||||
|
||||
Key routing rules:
|
||||
- Product ideas, "is this worth building", brainstorming → invoke office-hours
|
||||
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
|
||||
- Ship, deploy, push, create PR, "commit and ship", "push and ship" → invoke ship
|
||||
- QA, test the site, find bugs → invoke qa
|
||||
- Code review, check my diff → invoke review
|
||||
- Update docs after shipping → invoke document-release
|
||||
- Weekly retro → invoke retro
|
||||
- Design system, brand → invoke design-consultation
|
||||
- Visual audit, design polish → invoke design-review
|
||||
- Architecture review → invoke plan-eng-review
|
||||
- Save progress, checkpoint, resume → invoke checkpoint
|
||||
- Code quality, health check → invoke health
|
||||
-104
@@ -1,104 +0,0 @@
|
||||
# Contributing to GBrain
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/garrytan/gbrain.git
|
||||
cd gbrain
|
||||
bun install
|
||||
bun test
|
||||
```
|
||||
|
||||
Requires Bun 1.0+.
|
||||
|
||||
## Project structure
|
||||
|
||||
```
|
||||
src/
|
||||
cli.ts CLI entry point
|
||||
commands/ CLI-only commands (init, upgrade, import, export, etc.)
|
||||
core/
|
||||
operations.ts Contract-first operation definitions (the foundation)
|
||||
engine.ts BrainEngine interface
|
||||
postgres-engine.ts Postgres implementation
|
||||
db.ts Connection management + schema loader
|
||||
import-file.ts Import pipeline (chunk + embed + tags)
|
||||
types.ts TypeScript types
|
||||
markdown.ts Frontmatter parsing
|
||||
config.ts Config file management
|
||||
storage.ts Pluggable storage interface
|
||||
storage/ Storage backends (S3, Supabase, local)
|
||||
supabase-admin.ts Supabase admin API
|
||||
file-resolver.ts MIME detection + content hashing
|
||||
migrate.ts Migration helpers
|
||||
yaml-lite.ts Lightweight YAML parser
|
||||
chunkers/ 3-tier chunking (recursive, semantic, llm)
|
||||
search/ Hybrid search (vector, keyword, hybrid, expansion, dedup)
|
||||
embedding.ts OpenAI embedding service
|
||||
mcp/
|
||||
server.ts MCP stdio server (generated from operations)
|
||||
schema.sql Postgres DDL
|
||||
skills/ Fat markdown skills for AI agents
|
||||
test/ Unit tests (bun test, no DB required)
|
||||
test/e2e/ E2E tests (requires DATABASE_URL, real Postgres+pgvector)
|
||||
fixtures/ Miniature realistic brain corpus (16 files)
|
||||
helpers.ts DB lifecycle, fixture import, timing
|
||||
mechanical.test.ts All operations against real DB
|
||||
mcp.test.ts MCP tool generation verification
|
||||
skills.test.ts Tier 2 skill tests (requires OpenClaw + API keys)
|
||||
docs/ Architecture docs
|
||||
```
|
||||
|
||||
## Running tests
|
||||
|
||||
```bash
|
||||
bun test # all tests (unit + E2E skipped without DB)
|
||||
bun test test/markdown.test.ts # specific unit test
|
||||
|
||||
# E2E tests (requires Postgres with pgvector)
|
||||
docker compose -f docker-compose.test.yml up -d
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5434/gbrain_test bun run test:e2e
|
||||
|
||||
# Or use your own Postgres / Supabase
|
||||
DATABASE_URL=postgresql://... bun run test:e2e
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
bun build --compile --outfile bin/gbrain src/cli.ts
|
||||
```
|
||||
|
||||
## Adding a new operation
|
||||
|
||||
GBrain uses a contract-first architecture. Add your operation to one file and it
|
||||
automatically appears in the CLI, MCP server, and tools-json:
|
||||
|
||||
1. Add your operation to `src/core/operations.ts` (define params, handler, cliHints)
|
||||
2. Add tests
|
||||
3. That's it. The CLI, MCP server, and tools-json are generated from operations.
|
||||
|
||||
For CLI-only commands (init, upgrade, import, export, files, embed, doctor, sync):
|
||||
1. Create `src/commands/mycommand.ts`
|
||||
2. Add the case to `src/cli.ts`
|
||||
|
||||
Parity tests (`test/parity.test.ts`) verify CLI/MCP/tools-json stay in sync.
|
||||
|
||||
## Adding a new engine
|
||||
|
||||
See `docs/ENGINES.md` for the full guide. In short:
|
||||
|
||||
1. Create `src/core/myengine-engine.ts` implementing `BrainEngine`
|
||||
2. Add to engine factory in `src/core/engine.ts`
|
||||
3. Run the test suite against your engine
|
||||
4. Document in `docs/`
|
||||
|
||||
The SQLite engine is designed and ready for implementation. See `docs/SQLITE_ENGINE.md`.
|
||||
|
||||
## Welcome PRs
|
||||
|
||||
- SQLite engine implementation
|
||||
- Docker Compose for self-hosted Postgres
|
||||
- Additional migration sources
|
||||
- New enrichment API integrations
|
||||
- Performance optimizations
|
||||
@@ -1,154 +0,0 @@
|
||||
# GBrain Installation Guide for AI Agents
|
||||
|
||||
Read this entire file, then follow the steps. Ask the user for API keys when needed.
|
||||
Target: ~30 minutes to a fully working brain.
|
||||
|
||||
## Step 1: Install GBrain
|
||||
|
||||
```bash
|
||||
git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
export PATH="$HOME/.bun/bin:$PATH"
|
||||
bun install && bun link
|
||||
```
|
||||
|
||||
Verify: `gbrain --version` should print a version number. If `gbrain` is not found,
|
||||
restart the shell or add the PATH export to the shell profile.
|
||||
|
||||
## Step 2: API Keys
|
||||
|
||||
Ask the user for these:
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY=sk-... # required for vector search
|
||||
export ANTHROPIC_API_KEY=sk-ant-... # optional, improves search quality
|
||||
```
|
||||
|
||||
Save to shell profile or `.env`. Without OpenAI, keyword search still works.
|
||||
Without Anthropic, search works but skips query expansion.
|
||||
|
||||
## Step 3: Create the Brain
|
||||
|
||||
```bash
|
||||
gbrain init # PGLite, no server needed
|
||||
gbrain doctor --json # verify all checks pass
|
||||
```
|
||||
|
||||
The user's markdown files (notes, docs, brain repo) are SEPARATE from this tool repo.
|
||||
Ask the user where their files are, or create a new brain repo:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/brain && cd ~/brain && git init
|
||||
```
|
||||
|
||||
Read `~/gbrain/docs/GBRAIN_RECOMMENDED_SCHEMA.md` and set up the MECE directory
|
||||
structure (people/, companies/, concepts/, etc.) inside the user's brain repo,
|
||||
NOT inside ~/gbrain.
|
||||
|
||||
## Step 4: Import and Index
|
||||
|
||||
```bash
|
||||
gbrain import ~/brain/ --no-embed # import markdown files
|
||||
gbrain embed --stale # generate vector embeddings
|
||||
gbrain query "key themes across these documents?"
|
||||
```
|
||||
|
||||
## Step 4.5: Wire the Knowledge Graph
|
||||
|
||||
If the user already had a brain repo (Step 3 imported existing markdown), backfill
|
||||
the typed-link graph and structured timeline. This populates the `links` and
|
||||
`timeline_entries` tables that future writes will maintain automatically.
|
||||
|
||||
```bash
|
||||
gbrain extract links --source db --dry-run | head -20 # preview
|
||||
gbrain extract links --source db # commit
|
||||
gbrain extract timeline --source db # dated events
|
||||
gbrain stats # verify links > 0
|
||||
```
|
||||
|
||||
For brand-new empty brains, skip this step — auto-link populates the graph as the
|
||||
agent writes pages going forward. There is nothing to backfill yet.
|
||||
|
||||
After this step:
|
||||
- `gbrain graph-query <slug> --depth 2` works (relationship traversal)
|
||||
- Search ranks well-connected entities higher (backlink boost)
|
||||
- Every future `put_page` auto-creates typed links and reconciles stale ones
|
||||
|
||||
If a user has a very large brain (>10K pages), `extract --source db` is idempotent
|
||||
and supports `--since YYYY-MM-DD` for incremental runs.
|
||||
|
||||
## Step 5: Load Skills
|
||||
|
||||
Read `~/gbrain/skills/RESOLVER.md`. This is the skill dispatcher. It tells you which
|
||||
skill to read for any task. Save this to your memory permanently.
|
||||
|
||||
The three most important skills to adopt immediately:
|
||||
|
||||
1. **Signal detector** (`skills/signal-detector/SKILL.md`) — fire this on EVERY
|
||||
inbound message. It captures ideas and entities in parallel. The brain compounds.
|
||||
|
||||
2. **Brain-ops** (`skills/brain-ops/SKILL.md`) — brain-first lookup on every response.
|
||||
Check the brain before any external API call.
|
||||
|
||||
3. **Conventions** (`skills/conventions/quality.md`) — citation format, back-linking
|
||||
iron law, source attribution. These are non-negotiable quality rules.
|
||||
|
||||
## Step 6: Identity (optional)
|
||||
|
||||
Run the soul-audit skill to customize the agent's identity:
|
||||
|
||||
```
|
||||
Read skills/soul-audit/SKILL.md and follow it.
|
||||
```
|
||||
|
||||
This generates SOUL.md (agent identity), USER.md (user profile), ACCESS_POLICY.md
|
||||
(who sees what), and HEARTBEAT.md (operational cadence) from the user's answers.
|
||||
|
||||
If skipped, minimal defaults are installed automatically.
|
||||
|
||||
## Step 7: Recurring Jobs
|
||||
|
||||
Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab):
|
||||
|
||||
- **Live sync** (every 15 min): `gbrain sync --repo ~/brain && gbrain embed --stale`
|
||||
- **Auto-update** (daily): `gbrain check-update --json` (tell user, never auto-install)
|
||||
- **Dream cycle** (nightly): read `docs/guides/cron-schedule.md` for the full protocol.
|
||||
Entity sweep, citation fixes, memory consolidation. This is what makes the brain
|
||||
compound. Do not skip it.
|
||||
- **Weekly**: `gbrain doctor --json && gbrain embed --stale`
|
||||
|
||||
## Step 8: Integrations
|
||||
|
||||
Run `gbrain integrations list`. Each recipe in `~/gbrain/recipes/` is a self-contained
|
||||
installer. It tells you what credentials to ask for, how to validate, and what cron
|
||||
to register. Ask the user which integrations they want (email, calendar, voice, Twitter).
|
||||
|
||||
Verify: `gbrain integrations doctor` (after at least one is configured)
|
||||
|
||||
## Step 9: Verify
|
||||
|
||||
Read `docs/GBRAIN_VERIFY.md` and run all 7 verification checks. Check #4 (live sync
|
||||
actually works) is the most important.
|
||||
|
||||
## Upgrade
|
||||
|
||||
```bash
|
||||
cd ~/gbrain && git pull origin main && bun install
|
||||
gbrain init # apply schema migrations (idempotent)
|
||||
gbrain post-upgrade # show migration notes for the version range
|
||||
```
|
||||
|
||||
Then read `~/gbrain/skills/migrations/v<NEW_VERSION>.md` (and any intermediate
|
||||
versions you skipped) and run any backfill or verification steps it lists. Skipping
|
||||
this is how features ship in the binary but stay dormant in the user's brain.
|
||||
|
||||
For v0.12.0+ specifically: if your brain was created before v0.12.0, run
|
||||
`gbrain extract links --source db && gbrain extract timeline --source db` to
|
||||
backfill the new graph layer (see Step 4.5 above).
|
||||
|
||||
For v0.12.2+ specifically: if your brain is Postgres- or Supabase-backed and
|
||||
predates v0.12.2, the `v0_12_2` migration runs `gbrain repair-jsonb`
|
||||
automatically during `gbrain post-upgrade` to fix the double-encoded JSONB
|
||||
columns. PGLite brains no-op. If wiki-style imports were truncated by the old
|
||||
`splitBody` bug, run `gbrain sync --full` after upgrading to rebuild
|
||||
`compiled_truth` from source markdown.
|
||||
@@ -1,587 +0,0 @@
|
||||
# GBrain
|
||||
|
||||
Your AI agent is smart but forgetful. GBrain gives it a brain.
|
||||
|
||||
Built by the President and CEO of Y Combinator to run his actual AI agents. The production brain powering his OpenClaw and Hermes deployments: **17,888 pages, 4,383 people, 723 companies**, 21 cron jobs running autonomously, built in 12 days. The agent ingests meetings, emails, tweets, voice calls, and original ideas while you sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. You wake up and the brain is smarter than when you went to bed.
|
||||
|
||||
The brain wires itself. Every page write extracts entity references and creates typed links (`attended`, `works_at`, `invested_in`, `founded`, `advises`) with zero LLM calls. Hybrid search. Self-wiring knowledge graph. Structured timeline. Backlink-boosted ranking. Ask "who works at Acme AI?" or "what did Bob invest in this quarter?" and get answers vector search alone can't reach. Benchmarked end-to-end: **Recall@5 jumps from 83% to 95%, Precision@5 from 39% to 45%, +30 more correct answers in the agent's top-5 reads** on a 240-page Opus-generated rich-prose corpus. Graph-only F1: **86.6% vs grep's 57.8%** (+28.8 pts). [Full report](docs/benchmarks/2026-04-18-brainbench-v1.md).
|
||||
|
||||
GBrain is those patterns, generalized. 26 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
|
||||
|
||||
> **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
|
||||
|
||||
## Install
|
||||
|
||||
### On an agent platform (recommended)
|
||||
|
||||
GBrain is designed to be installed and operated by an AI agent. If you don't have one running yet:
|
||||
|
||||
- **[OpenClaw](https://openclaw.ai)** ... Deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
|
||||
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** ... Deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
|
||||
|
||||
Paste this into your agent:
|
||||
|
||||
```
|
||||
Retrieve and follow the instructions at:
|
||||
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
|
||||
```
|
||||
|
||||
That's it. The agent clones the repo, installs GBrain, sets up the brain, loads 26 skills, and configures recurring jobs. You answer a few questions about API keys. ~30 minutes.
|
||||
|
||||
### Standalone CLI (no agent)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/garrytan/gbrain.git && cd gbrain && bun install && bun link
|
||||
gbrain init # local brain, ready in 2 seconds
|
||||
gbrain import ~/notes/ # index your markdown
|
||||
gbrain query "what themes show up across my notes?"
|
||||
```
|
||||
|
||||
```
|
||||
3 results (hybrid search, 0.12s):
|
||||
|
||||
1. concepts/do-things-that-dont-scale (score: 0.94)
|
||||
PG's argument that unscalable effort teaches you what users want.
|
||||
[Source: paulgraham.com, 2013-07-01]
|
||||
|
||||
2. originals/founder-mode-observation (score: 0.87)
|
||||
Deep involvement isn't micromanagement if it expands the team's thinking.
|
||||
|
||||
3. concepts/build-something-people-want (score: 0.81)
|
||||
The YC motto. Connected to 12 other brain pages.
|
||||
```
|
||||
|
||||
### MCP server (Claude Code, Cursor, Windsurf)
|
||||
|
||||
GBrain exposes 30+ MCP tools via stdio:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gbrain": { "command": "gbrain", "args": ["serve"] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Add to `~/.claude/server.json` (Claude Code), Settings > MCP Servers (Cursor), or your client's MCP config.
|
||||
|
||||
### Remote MCP (Claude Desktop, Cowork, Perplexity)
|
||||
|
||||
```bash
|
||||
ngrok http 8787 --url your-brain.ngrok.app
|
||||
bun run src/commands/auth.ts create "claude-desktop"
|
||||
claude mcp add gbrain -t http https://your-brain.ngrok.app/mcp -H "Authorization: Bearer TOKEN"
|
||||
```
|
||||
|
||||
Per-client guides: [`docs/mcp/`](docs/mcp/DEPLOY.md). ChatGPT requires OAuth 2.1 (not yet implemented).
|
||||
|
||||
## The 26 Skills
|
||||
|
||||
GBrain ships 26 skills organized by `skills/RESOLVER.md`. The resolver tells your agent which skill to read for any task.
|
||||
|
||||
[Skill files are code.](https://x.com/garrytan/status/2042925773300908103) They're the most powerful way to get knowledge work done. A skill file is a fat markdown document that encodes an entire workflow: when to fire, what to check, how to chain with other skills, what quality bar to enforce. The agent reads the skill and executes it. Skills can also call deterministic TypeScript code bundled in GBrain (search, import, embed, sync) for the parts that shouldn't be left to LLM judgment. [Thin harness, fat skills](docs/ethos/THIN_HARNESS_FAT_SKILLS.md): the intelligence lives in the skills, not the runtime.
|
||||
|
||||
### Always-on
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| **signal-detector** | Fires on every message. Spawns a cheap model in parallel to capture original thinking and entity mentions. The brain compounds on autopilot. |
|
||||
| **brain-ops** | Brain-first lookup before any external API. The read-enrich-write loop that makes every response smarter. |
|
||||
|
||||
### Content ingestion
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| **ingest** | Thin router. Detects input type and delegates to the right ingestion skill. |
|
||||
| **idea-ingest** | Links, articles, tweets become brain pages with analysis, author people pages, and cross-linking. |
|
||||
| **media-ingest** | Video, audio, PDF, books, screenshots, GitHub repos. Transcripts, entity extraction, backlink propagation. |
|
||||
| **meeting-ingestion** | Transcripts become brain pages. Every attendee gets enriched. Every company gets a timeline entry. |
|
||||
|
||||
### Brain operations
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| **enrich** | Tiered enrichment (Tier 1/2/3). Creates and updates person/company pages with compiled truth and timelines. |
|
||||
| **query** | 3-layer search with synthesis and citations. Says "the brain doesn't have info on X" instead of hallucinating. |
|
||||
| **maintain** | Periodic health: stale pages, orphans, dead links, citation audit, back-link enforcement, tag consistency. |
|
||||
| **citation-fixer** | Scans pages for missing or malformed citations. Fixes format to match the standard. |
|
||||
| **repo-architecture** | Where new brain files go. Decision protocol: primary subject determines directory, not format. |
|
||||
| **publish** | Share brain pages as password-protected HTML. Zero LLM calls. |
|
||||
| **data-research** | Structured data research with parameterized YAML recipes. Extract investor updates, expenses, company metrics from email. |
|
||||
|
||||
### Operational
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| **daily-task-manager** | Task lifecycle with priority levels (P0-P3). Stored as searchable brain pages. |
|
||||
| **daily-task-prep** | Morning prep: calendar lookahead with brain context per attendee, open threads, task review. |
|
||||
| **cron-scheduler** | Schedule staggering (5-min offsets), quiet hours (timezone-aware with wake-up override), idempotency. |
|
||||
| **reports** | Timestamped reports with keyword routing. "What's the latest briefing?" finds it instantly. |
|
||||
| **cross-modal-review** | Quality gate via second model. Refusal routing: if one model refuses, silently switch. |
|
||||
| **webhook-transforms** | External events (SMS, meetings, social mentions) converted into brain pages with entity extraction. |
|
||||
| **testing** | Validates every skill has SKILL.md with frontmatter, manifest coverage, resolver coverage. |
|
||||
| **skill-creator** | Create new skills following the conformance standard. MECE check against existing skills. |
|
||||
| **minion-orchestrator** | Long-running agent work as background jobs. Submit, fan out children with depth/cap/timeouts, collect results via child_done inbox. |
|
||||
|
||||
### Identity and setup
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| **soul-audit** | 6-phase interview generating SOUL.md (agent identity), USER.md (user profile), ACCESS_POLICY.md (4-tier privacy), HEARTBEAT.md (operational cadence). |
|
||||
| **setup** | Auto-provision PGLite or Supabase. First import. GStack detection. |
|
||||
| **migrate** | Universal migration from Obsidian, Notion, Logseq, markdown, CSV, JSON, Roam. |
|
||||
| **briefing** | Daily briefing with meeting context, active deals, and citation tracking. |
|
||||
|
||||
### Conventions
|
||||
|
||||
Cross-cutting rules in `skills/conventions/`:
|
||||
- **quality.md** ... citations, back-links, notability gate, source attribution
|
||||
- **brain-first.md** ... 5-step lookup before any external API call
|
||||
- **model-routing.md** ... which model for which task
|
||||
- **test-before-bulk.md** ... test 3-5 items before any batch operation
|
||||
- **cross-modal.yaml** ... review pairs and refusal routing chain
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
Signal arrives (meeting, email, tweet, link)
|
||||
-> Signal detector captures ideas + entities (parallel, never blocks)
|
||||
-> Brain-ops: check the brain first (gbrain search, gbrain get)
|
||||
-> Respond with full context
|
||||
-> Write: update brain pages with new information + citations
|
||||
-> Auto-link: typed relationships extracted on every write (zero LLM calls)
|
||||
-> Sync: gbrain indexes changes for next query
|
||||
```
|
||||
|
||||
Every cycle adds knowledge. The agent enriches a person page after a meeting. Next time that person comes up, the agent already has context. The difference compounds daily.
|
||||
|
||||
The system gets smarter on its own. Entity enrichment auto-escalates: a person mentioned once gets a stub page (Tier 3). After 3 mentions across different sources, they get web + social enrichment (Tier 2). After a meeting or 8+ mentions, full pipeline (Tier 1). The brain learns who matters without being told. Deterministic classifiers improve over time via a fail-improve loop that logs every LLM fallback and generates better regex patterns from the failures. `gbrain doctor` shows the trajectory: "intent classifier: 87% deterministic, up from 40% in week 1."
|
||||
|
||||
> "Prep me for my meeting with Jordan in 30 minutes"
|
||||
> ... pulls dossier, shared history, recent activity, open threads
|
||||
|
||||
> "What have I said about the relationship between shame and founder performance?"
|
||||
> ... searches YOUR thinking, not the internet
|
||||
|
||||
## Minions: your sub-agents won't drop work anymore
|
||||
|
||||
A durable, Postgres-native job queue built into the brain. Every long-running agent task is now a job that survives gateway restarts, streams progress, gets paused / resumed / steered mid-flight, and shows up in `gbrain jobs list`. Zero infra beyond your existing brain.
|
||||
|
||||
### The production numbers that matter
|
||||
|
||||
Here's my personal OpenClaw deployment: one Render container. Supabase Postgres holding a 45,000-page brain. 19 cron jobs firing on schedule. Real gateway load from real daily work. The task: pull a month of my social posts from an external API and ingest them end-to-end into the brain as a structured page.
|
||||
|
||||
| | Minions | `sessions_spawn` |
|
||||
|--- |--- |--- |
|
||||
| Wall time | **753ms** | **>10,000ms** (gateway timeout) |
|
||||
| Token cost | **$0.00** | ~$0.03 per run |
|
||||
| Success rate | **100%** | **0%** (couldn't even spawn) |
|
||||
| Memory/job | ~2 MB | ~80 MB |
|
||||
|
||||
Under that 19-cron load, sub-agent spawn couldn't clear the 10-second gateway wall. Minions landed it in under a second for zero tokens. **Scaling:** 19,240 posts across 36 months, single bash loop, ~15 min total, $0.00. Sub-agents: ~9 min best case, ~$1.08 in tokens, ~40% spawn failure. **Lab:** durability ∞ (SIGKILL mid-flight, 10/10 rescued), throughput ~10× faster, fan-out ~21× with no failure wall, memory ~400× less.
|
||||
|
||||
Full benchmarks: [production](docs/benchmarks/2026-04-18-minions-vs-openclaw-production.md) and [lab](docs/benchmarks/2026-04-18-minions-vs-openclaw-subagents.md).
|
||||
|
||||
### The routing rule
|
||||
|
||||
> **Deterministic** (same input → same steps → same output) → **Minions**
|
||||
> **Judgment** (input requires assessment or decision) → **Sub-agents**
|
||||
|
||||
Pull posts, parse JSON, write a brain page, run a sync — deterministic. $0 tokens, survives restart, millisecond runtime. Triage the inbox, assess meeting priority, decide if a cold email deserves a reply — judgment. What sub-agents are actually good at. `minion_mode: pain_triggered` (the default) automates the routing.
|
||||
|
||||
### What's fixed
|
||||
|
||||
The six daily pains — spawn storms, agents that stop responding, forgotten dispatches, gateway crashes mid-run, runaway grandchildren, debugging soup — all belonged to the "deterministic work through a reasoning model" mistake. Minions fixes them by not making that mistake: `max_children` cap, `timeout_ms` + AbortSignal, `child_done` inbox, full `parent_job_id`/`depth`/transcript per job, Postgres durability with stall detection, cascade cancel via recursive CTE. Plus idempotency keys, attachment validation, `removeOnComplete`, and `gbrain jobs smoke` that proves the install in half a second.
|
||||
|
||||
```bash
|
||||
gbrain jobs smoke # verify install
|
||||
gbrain jobs submit sync --params '{}' # fire a background job
|
||||
gbrain jobs stats # health dashboard
|
||||
gbrain jobs work --concurrency 4 # start a worker (Postgres only)
|
||||
```
|
||||
|
||||
Read [`skills/minion-orchestrator/SKILL.md`](skills/minion-orchestrator/SKILL.md) for parent-child DAGs, fan-in collection, steering via inbox.
|
||||
|
||||
**Minions is not incrementally better than sub-agents for background work. It's categorically different.** 753ms vs gateway timeout. $0 vs tokens. 100% vs couldn't-spawn. If your agent does deterministic work on a schedule, it runs on Minions now.
|
||||
|
||||
### Health check and self-heal
|
||||
|
||||
Minions is canonical as of v0.11.1 — every `gbrain upgrade` runs the migration automatically (schema → smoke → prefs → host rewrites → env-aware autopilot install). If you ever want to verify manually or wire a cron into your morning briefing:
|
||||
|
||||
```bash
|
||||
gbrain doctor # half-migrated state? prints loud banner + exits non-zero
|
||||
gbrain skillpack-check --quiet # exit 0/1/2 for pipeline gating
|
||||
gbrain skillpack-check | jq # full JSON: {healthy, summary, actions[], doctor, migrations}
|
||||
```
|
||||
|
||||
If anything's off, `actions[]` tells you the exact command to run. For deeper troubleshooting: [`docs/guides/minions-fix.md`](docs/guides/minions-fix.md).
|
||||
|
||||
Moving gateway crons to Minions (deterministic scripts, zero LLM tokens per fire): [`docs/guides/minions-shell-jobs.md`](docs/guides/minions-shell-jobs.md).
|
||||
|
||||
## Skillify: your skills tree stops being a black box
|
||||
|
||||
Hermes and similar agent frameworks auto-create skills as a background behavior. Fine until you don't know what the agent shipped. Checklists decay. Tests drift. Resolver entries get stale. Six months later you've got an opaque pile of "skills" that nobody has read, nobody has tested, and nobody is sure still work.
|
||||
|
||||
GBrain ships the same capability. Except the human stays in the loop.
|
||||
|
||||
- **`/skillify`** turns raw code into a properly-skilled feature: SKILL.md + deterministic script + unit tests + integration tests + LLM evals + resolver trigger + resolver trigger eval + E2E smoke + brain filing. Ten items. Every one required.
|
||||
- **`gbrain check-resolvable`** walks the whole skills tree: reachability, MECE overlap, DRY violations, gap detection, orphaned skills. Exits non-zero if anything is off.
|
||||
- **`scripts/skillify-check.ts`** — machine-readable audit. `--json` for CI, `--recent` for last-7-days files.
|
||||
|
||||
You decide when and what. The tooling keeps the checklist honest.
|
||||
|
||||
### Why this is the right answer for OpenClaw
|
||||
|
||||
Auto-generated skills are a liability the first time a behavior breaks. Was it the skill? The test? The resolver trigger? The eval? You don't know, because you never read it. Debugging a black box is pure guesswork.
|
||||
|
||||
Skillify makes the black box legible. Every skill in your tree has: a contract (SKILL.md), tests that exercise that contract, an eval that grades LLM output against a rubric, a resolver trigger the user actually types, and a test that confirms the trigger routes right. If something breaks, you know which layer to look at. If anything goes stale, `check-resolvable` says so.
|
||||
|
||||
In practice this combo produces **zero orphaned skills, every feature with tests + evals + resolver triggers + evals of the triggers.** Compounding quality instead of compounding entropy.
|
||||
|
||||
```bash
|
||||
# Audit a feature's skill completeness (10-item checklist)
|
||||
bun run scripts/skillify-check.ts src/commands/publish.ts
|
||||
|
||||
# In CI: fail the build when a new feature isn't properly skilled
|
||||
bun run scripts/skillify-check.ts --json --recent
|
||||
|
||||
# Validate the whole skills tree before shipping
|
||||
gbrain check-resolvable
|
||||
```
|
||||
|
||||
**Skillify is not a nice-to-have. It's the piece that makes the skills tree survive six months of compounding work.** Read [`skills/skillify/SKILL.md`](skills/skillify/SKILL.md) for the full 10-item checklist and the anti-patterns it catches.
|
||||
|
||||
## Getting Data In
|
||||
|
||||
GBrain ships integration recipes that your agent sets up for you. Each recipe tells the agent what credentials to ask for, how to validate, and what cron to register.
|
||||
|
||||
| Recipe | Requires | What It Does |
|
||||
|--------|----------|-------------|
|
||||
| [Public Tunnel](recipes/ngrok-tunnel.md) | — | Fixed URL for MCP + voice (ngrok Hobby $8/mo) |
|
||||
| [Credential Gateway](recipes/credential-gateway.md) | — | Gmail + Calendar access |
|
||||
| [Voice-to-Brain](recipes/twilio-voice-brain.md) | ngrok-tunnel | Phone calls to brain pages (Twilio + OpenAI Realtime) |
|
||||
| [Email-to-Brain](recipes/email-to-brain.md) | credential-gateway | Gmail to entity pages |
|
||||
| [X-to-Brain](recipes/x-to-brain.md) | — | Twitter timeline + mentions + deletions |
|
||||
| [Calendar-to-Brain](recipes/calendar-to-brain.md) | credential-gateway | Google Calendar to searchable daily pages |
|
||||
| [Meeting Sync](recipes/meeting-sync.md) | — | Circleback transcripts to brain pages with attendees |
|
||||
|
||||
**Data research recipes** extract structured data from email into tracked brain pages. Built-in recipes for investor updates (MRR, ARR, runway, headcount), expense tracking, and company metrics. Create your own with `gbrain research init`.
|
||||
|
||||
Run `gbrain integrations` to see status.
|
||||
|
||||
## GBrain + GStack
|
||||
|
||||
[GStack](https://github.com/garrytan/gstack) is the engine. GBrain is the mod.
|
||||
|
||||
- **[GStack](https://github.com/garrytan/gstack)** = coding skills (ship, review, QA, investigate, office-hours, retro). 70,000+ stars, 30,000 developers per day. When your agent codes on itself, it uses GStack.
|
||||
- **GBrain** = everything-else skills (brain ops, signal detection, ingestion, enrichment, cron, reports, identity). When your agent remembers, thinks, and operates, it uses GBrain.
|
||||
- **`hosts/gbrain.ts`** = the bridge. Tells GStack's coding skills to check the brain before coding.
|
||||
|
||||
`gbrain init` detects if GStack is installed and reports mod status. If GStack isn't there, it tells you how to get it.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────┐ ┌───────────────┐ ┌──────────────────┐
|
||||
│ Brain Repo │ │ GBrain │ │ AI Agent │
|
||||
│ (git) │ │ (retrieval) │ │ (read/write) │
|
||||
│ │ │ │ │ │
|
||||
│ markdown files │───>│ Postgres + │<──>│ 26 skills │
|
||||
│ = source of │ │ pgvector │ │ define HOW to │
|
||||
│ truth │ │ │ │ use the brain │
|
||||
│ │<───│ hybrid │ │ │
|
||||
│ human can │ │ search │ │ RESOLVER.md │
|
||||
│ always read │ │ (vector + │ │ routes intent │
|
||||
│ & edit │ │ keyword + │ │ to skill │
|
||||
│ │ │ RRF) │ │ │
|
||||
└──────────────────┘ └───────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
The repo is the system of record. GBrain is the retrieval layer. The agent reads and writes through both. Human always wins... edit any markdown file and `gbrain sync` picks up the changes.
|
||||
|
||||
## The Knowledge Model
|
||||
|
||||
Every page follows the compiled truth + timeline pattern:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: concept
|
||||
title: Do Things That Don't Scale
|
||||
tags: [startups, growth, pg-essay]
|
||||
---
|
||||
|
||||
Paul Graham's argument that startups should do unscalable things early on.
|
||||
The key insight: the unscalable effort teaches you what users actually
|
||||
want, which you can't learn any other way.
|
||||
|
||||
---
|
||||
|
||||
- 2013-07-01: Published on paulgraham.com
|
||||
- 2024-11-15: Referenced in batch W25 kickoff talk
|
||||
```
|
||||
|
||||
Above the `---`: **compiled truth**. Your current best understanding. Gets rewritten when new evidence changes the picture. Below: **timeline**. Append-only evidence trail. Never edited, only added to.
|
||||
|
||||
## Knowledge Graph
|
||||
|
||||
Pages aren't just text. Every mention of a person, company, or concept becomes a typed link in a structured graph. The brain wires itself.
|
||||
|
||||
```
|
||||
Write a meeting page mentioning Alice and Acme AI
|
||||
-> Auto-link extracts entity refs from content (zero LLM calls)
|
||||
-> Infers types: meeting page + person ref => `attended`
|
||||
"CEO of X" pattern => `works_at`
|
||||
"invested in" => `invested_in`
|
||||
"advises", "advisor" => `advises`
|
||||
"founded", "co-founded" => `founded`
|
||||
-> Reconciles stale links: edits remove links no longer in content
|
||||
-> Backlinks rank well-connected entities higher in search
|
||||
```
|
||||
|
||||
```bash
|
||||
gbrain graph-query people/alice --type attended --depth 2
|
||||
# returns who Alice met with, transitively
|
||||
```
|
||||
|
||||
The graph powers questions vector search can't: "who works at Acme AI?", "what has Bob invested in?", "find the connection between Alice and Carol". Backfill an existing brain in one command:
|
||||
|
||||
```bash
|
||||
gbrain extract links --source db # wire up the existing 29K pages
|
||||
gbrain extract timeline --source db # extract dated events from markdown timelines
|
||||
```
|
||||
|
||||
Then ask graph questions or watch the search ranking improve. Benchmarked: **Recall@5 jumps from 83% to 95%, Precision@5 from 39% to 45%, +30 more correct answers in the agent's top-5 reads** on a 240-page Opus-generated rich-prose corpus. Graph-only F1 hits 86.6% vs grep's 57.8% (+28.8 pts). See [docs/benchmarks/2026-04-18-brainbench-v1.md](docs/benchmarks/2026-04-18-brainbench-v1.md).
|
||||
|
||||
## Search
|
||||
|
||||
Hybrid search: vector + keyword + RRF fusion + multi-query expansion + 4-layer dedup.
|
||||
|
||||
```
|
||||
Query
|
||||
-> Intent classifier (entity? temporal? event? general?)
|
||||
-> Multi-query expansion (Claude Haiku)
|
||||
-> Vector search (HNSW cosine) + Keyword search (tsvector)
|
||||
-> RRF fusion: score = sum(1/(60 + rank))
|
||||
-> Cosine re-scoring + compiled truth boost
|
||||
-> 4-layer dedup + compiled truth guarantee
|
||||
-> Results
|
||||
```
|
||||
|
||||
Keyword alone misses conceptual matches. Vector alone misses exact phrases. RRF gets both. Search quality is benchmarked and reproducible: `gbrain eval --qrels queries.json` measures P@k, Recall@k, MRR, and nDCG@k. A/B test config changes before deploying them.
|
||||
|
||||
## Why it works: many strategies in concert
|
||||
|
||||
The brain isn't one trick. Every retrieval question goes through ~20 deterministic
|
||||
techniques layered together. No single one is magic; the win comes from stacking
|
||||
them so each layer covers what the others miss.
|
||||
|
||||
```
|
||||
Question
|
||||
│
|
||||
├─ INGESTION (every put_page)
|
||||
│ ├─ Recursive markdown chunking (or semantic / LLM-guided)
|
||||
│ ├─ Embedding cache invalidation on edit
|
||||
│ └─ Idempotent imports (content-hash dedup)
|
||||
│
|
||||
├─ GRAPH EXTRACTION (auto-link post-hook, zero LLM)
|
||||
│ ├─ Entity-ref regex (markdown links + bare slugs)
|
||||
│ ├─ Code-fence stripping (no false-positive slugs in code blocks)
|
||||
│ ├─ Typed inference cascade (FOUNDED → INVESTED → ADVISES → WORKS_AT)
|
||||
│ ├─ Page-role priors (partner-bio language → invested_in)
|
||||
│ ├─ Within-page dedup (same target collapses to one link)
|
||||
│ ├─ Stale-link reconciliation (edits remove dropped refs)
|
||||
│ └─ Multi-type link constraint (same person can works_at AND advises)
|
||||
│
|
||||
├─ SEARCH PIPELINE (every query)
|
||||
│ ├─ Intent classifier (entity / temporal / event / general — auto-routes)
|
||||
│ ├─ Multi-query expansion (Haiku rephrases the question 3 ways)
|
||||
│ ├─ Vector search (HNSW cosine over OpenAI embeddings)
|
||||
│ ├─ Keyword search (Postgres tsvector + websearch_to_tsquery)
|
||||
│ ├─ Reciprocal Rank Fusion (score = sum 1/(60+rank) across both)
|
||||
│ ├─ Cosine re-scoring (re-rank chunks against actual query embedding)
|
||||
│ ├─ Compiled-truth boost (assessments outrank timeline noise)
|
||||
│ ├─ Backlink boost (well-connected entities rank higher)
|
||||
│ └─ Source-aware dedup (one CT chunk per page guaranteed)
|
||||
│
|
||||
├─ GRAPH TRAVERSAL (relational queries)
|
||||
│ ├─ Recursive CTE with cycle prevention (visited-array check)
|
||||
│ ├─ Type-filtered edges (--type works_at, attended, etc.)
|
||||
│ ├─ Direction control (in / out / both)
|
||||
│ └─ Depth-capped (≤10 for remote MCP; DoS prevention)
|
||||
│
|
||||
└─ AGENT WORKFLOW (graph-confident hybrid)
|
||||
├─ Graph-query first (high-precision typed answers)
|
||||
├─ Grep fallback when graph returns nothing
|
||||
└─ Graph hits ranked first in top-K (better P@K and R@K)
|
||||
```
|
||||
|
||||
End-to-end on the BrainBench v1 corpus (240 rich-prose pages, before/after PR #188):
|
||||
|
||||
| Metric | BEFORE PR #188 | AFTER PR #188 | Δ |
|
||||
|-------------------------|----------------|---------------|-------------|
|
||||
| **Precision@5** | 39.2% | **44.7%** | **+5.4 pts**|
|
||||
| **Recall@5** | 83.1% | **94.6%** | **+11.5 pts**|
|
||||
| Correct in top-5 | 217 | 247 | **+30** |
|
||||
| Graph-only F1 (ablation)| 57.8% (grep) | **86.6%** | **+28.8 pts**|
|
||||
|
||||
Plus 5 orthogonal capability checks (identity resolution, temporal queries,
|
||||
performance at 10K-page scale, robustness to malformed input, MCP operation
|
||||
contract). All pass. [Full report.](docs/benchmarks/2026-04-18-brainbench-v1.md)
|
||||
|
||||
The point: each technique handles a class of inputs the others miss. Vector
|
||||
search misses exact slug refs; keyword catches them. Keyword misses conceptual
|
||||
matches; vector catches them. RRF picks the best of both. Compiled-truth boost
|
||||
keeps assessments above timeline noise. Auto-link extraction wires the graph
|
||||
that lets backlink boost rank well-connected entities higher. Graph traversal
|
||||
answers questions search alone can't reach. The agent picks graph-first for
|
||||
precision and falls back to keyword for recall. **All deterministic, all in
|
||||
concert, all measured.**
|
||||
|
||||
## Voice
|
||||
|
||||
Call a phone number. Your AI answers. It knows who's calling, pulls their full context from the brain, and responds like someone who actually knows your world. When the call ends, a brain page appears with the transcript, entity detection, and cross-references.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/images/voice-client.png" alt="Voice client connected" width="300" />
|
||||
</p>
|
||||
|
||||
> [See it in action](https://x.com/garrytan/status/2043022208512172263)
|
||||
|
||||
The voice recipe ships with GBrain: [Voice-to-Brain](recipes/twilio-voice-brain.md). WebRTC works in a browser tab with zero setup. A real phone number is optional.
|
||||
|
||||
## Engine Architecture
|
||||
|
||||
```
|
||||
CLI / MCP Server
|
||||
(thin wrappers, identical operations)
|
||||
|
|
||||
BrainEngine interface (pluggable)
|
||||
|
|
||||
+--------+--------+
|
||||
| |
|
||||
PGLiteEngine PostgresEngine
|
||||
(default) (Supabase)
|
||||
| |
|
||||
~/.gbrain/ Supabase Pro ($25/mo)
|
||||
brain.pglite Postgres + pgvector
|
||||
embedded PG 17.5
|
||||
|
||||
gbrain migrate --to supabase|pglite
|
||||
(bidirectional migration)
|
||||
```
|
||||
|
||||
PGLite: embedded Postgres, no server, zero config. When your brain outgrows local (1000+ files, multi-device), `gbrain migrate --to supabase` moves everything.
|
||||
|
||||
## File Storage
|
||||
|
||||
Brain repos accumulate binaries. GBrain has a three-stage migration:
|
||||
|
||||
```bash
|
||||
gbrain files mirror <dir> # copy to cloud, local untouched
|
||||
gbrain files redirect <dir> # replace local with .redirect pointers
|
||||
gbrain files clean <dir> # remove pointers, cloud only
|
||||
gbrain files restore <dir> # download everything back (undo)
|
||||
```
|
||||
|
||||
Storage backends: S3-compatible (AWS, R2, MinIO), Supabase Storage, or local.
|
||||
|
||||
## Commands
|
||||
|
||||
```
|
||||
SETUP
|
||||
gbrain init [--supabase|--url] Create brain (PGLite default)
|
||||
gbrain migrate --to supabase|pglite Bidirectional engine migration
|
||||
gbrain upgrade Self-update with feature discovery
|
||||
|
||||
PAGES
|
||||
gbrain get <slug> Read a page (fuzzy slug matching)
|
||||
gbrain put <slug> [< file.md] Write/update (auto-versions)
|
||||
gbrain delete <slug> Delete a page
|
||||
gbrain list [--type T] [--tag T] List with filters
|
||||
|
||||
SEARCH
|
||||
gbrain search <query> Keyword search (tsvector)
|
||||
gbrain query <question> Hybrid search (vector + keyword + RRF)
|
||||
|
||||
IMPORT
|
||||
gbrain import <dir> [--no-embed] Import markdown (idempotent)
|
||||
gbrain sync [--repo <path>] Git-to-brain incremental sync
|
||||
gbrain export [--dir ./out/] Export to markdown
|
||||
|
||||
FILES
|
||||
gbrain files list|upload|sync|verify File storage operations
|
||||
|
||||
EMBEDDINGS
|
||||
gbrain embed [<slug>|--all|--stale] Generate/refresh embeddings
|
||||
|
||||
LINKS + GRAPH
|
||||
gbrain link|unlink|backlinks Cross-reference management
|
||||
gbrain extract links|timeline|all Batch backfill from existing pages
|
||||
(--source db|fs, --type, --since, --dry-run)
|
||||
gbrain graph-query <slug> Typed traversal (--type T --depth N
|
||||
--direction in|out|both)
|
||||
|
||||
JOBS (Minions)
|
||||
gbrain jobs submit <name> [--params JSON] [--follow] Submit a background job
|
||||
gbrain jobs list [--status S] [--queue Q] List jobs with filters
|
||||
gbrain jobs get|cancel|retry|delete <id> Manage job lifecycle
|
||||
gbrain jobs prune [--older-than 30d] Clean completed/dead jobs
|
||||
gbrain jobs stats Job health dashboard
|
||||
gbrain jobs smoke One-command health check
|
||||
gbrain jobs work [--queue Q] [--concurrency N] Start worker daemon
|
||||
|
||||
ADMIN
|
||||
gbrain doctor [--json] [--fast] Health checks (resolver, skills, DB, embeddings)
|
||||
gbrain doctor --fix [--dry-run] Auto-fix DRY violations (delegate inlined rules to conventions)
|
||||
gbrain stats Brain statistics
|
||||
gbrain serve MCP server (stdio)
|
||||
gbrain integrations Integration recipe dashboard
|
||||
gbrain check-backlinks check|fix Back-link enforcement
|
||||
gbrain lint [--fix] LLM artifact detection
|
||||
gbrain repair-jsonb [--dry-run] Repair v0.12.0 double-encoded JSONB (Postgres)
|
||||
gbrain orphans [--json] [--count] Find pages with zero inbound wikilinks
|
||||
gbrain transcribe <audio> Transcribe audio (Groq Whisper)
|
||||
gbrain research init <name> Scaffold a data-research recipe
|
||||
gbrain research list Show available recipes
|
||||
```
|
||||
|
||||
Run `gbrain --help` for the full reference.
|
||||
|
||||
## Origin Story
|
||||
|
||||
I was setting up my [OpenClaw](https://openclaw.ai) agent and started a markdown brain repo. One page per person, one page per company, compiled truth on top, timeline on the bottom. Within a week: 10,000+ files, 3,000+ people, 13 years of calendar data, 280+ meeting transcripts, 300+ captured ideas.
|
||||
|
||||
The agent runs while I sleep. The dream cycle scans every conversation, enriches missing entities, fixes broken citations, consolidates memory. I wake up and the brain is smarter than when I went to sleep.
|
||||
|
||||
The skills in this repo are those patterns, generalized. What took 11 days to build by hand ships as a mod you install in 30 minutes.
|
||||
|
||||
## Docs
|
||||
|
||||
**For agents:**
|
||||
- **[skills/RESOLVER.md](skills/RESOLVER.md)** ... Start here. The skill dispatcher.
|
||||
- [Individual skill files](skills/) ... 25 standalone instruction sets
|
||||
- [GBRAIN_SKILLPACK.md](docs/GBRAIN_SKILLPACK.md) ... Legacy reference architecture
|
||||
- [Getting Data In](docs/integrations/README.md) ... Integration recipes and data flow
|
||||
- [GBRAIN_VERIFY.md](docs/GBRAIN_VERIFY.md) ... Installation verification
|
||||
|
||||
**For humans:**
|
||||
- [GBRAIN_RECOMMENDED_SCHEMA.md](docs/GBRAIN_RECOMMENDED_SCHEMA.md) ... Brain repo directory structure
|
||||
- [Thin Harness, Fat Skills](docs/ethos/THIN_HARNESS_FAT_SKILLS.md) ... Architecture philosophy
|
||||
- [ENGINES.md](docs/ENGINES.md) ... Pluggable engine interface
|
||||
|
||||
**Reference:**
|
||||
- [GBRAIN_V0.md](docs/GBRAIN_V0.md) ... Full product spec
|
||||
- [CHANGELOG.md](CHANGELOG.md) ... Version history
|
||||
|
||||
**Benchmarks:**
|
||||
- [BrainBench v1 (PR #188)](docs/benchmarks/2026-04-18-brainbench-v1.md) ... single comprehensive before/after report on a 240-page Opus-generated corpus. 7 categories: relational queries, identity resolution, temporal queries, performance, robustness, MCP contract.
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md). Run `bun test` for unit tests. E2E tests: spin up Postgres with pgvector, run `bun run test:e2e`, tear down.
|
||||
|
||||
PRs welcome for: new enrichment APIs, performance optimizations, additional engine backends, new skills following the conformance standard in `skills/skill-creator/SKILL.md`.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
@@ -1,391 +0,0 @@
|
||||
# TODOS
|
||||
|
||||
## P1 (BrainBench v1.1 — categories deferred from PR #188)
|
||||
|
||||
### BrainBench Cat 5: Source Attribution / Provenance
|
||||
**What:** Eval that gbrain correctly cites the right page when claiming fact F, and resolves source-conflict cases (3 sources disagree on $5M raise — which wins?). 200 queries across citation/provenance/conflict sub-categories on a 300-entity dataset with deliberately-conflicting sources.
|
||||
|
||||
**Why deferred from PR #188:** Needs ~$100-200 of Opus tokens to generate the conflict-graph dataset. v1 scope was procedural-only.
|
||||
|
||||
**Threshold:** citation_recall > 90%, citation_precision > 85%, conflict_resolution > 70%.
|
||||
|
||||
**Depends on:** Identity Resolution (Cat 3) shipped — uses same world generator pattern.
|
||||
|
||||
### BrainBench Cat 6: Auto-link Precision under Prose (at scale)
|
||||
**What:** Cat 10 (Robustness/Adversarial) covered code-fence leak and false-positive substrings on 22 hand-crafted cases. v1.1 extends this to 500+ prose-heavy pages with realistic narrative noise. Tests link precision in the wild, not just edge cases.
|
||||
|
||||
**Why deferred from PR #188:** Needs prose-heavy generated corpus (~$100-150 Opus). Existing 22-case eval already caught + fixed the code-fence leak bug.
|
||||
|
||||
**Threshold:** link_precision > 95% on prose, type_accuracy > 80% on varied phrasing.
|
||||
|
||||
### BrainBench Cat 8: Skill Behavior Compliance
|
||||
**What:** Replays 100 inbound signals through a real LLM agent loop with gbrain skills loaded. Measures: brain-first lookup compliance, back-link iron-law adherence, citation format compliance, tier escalation correctness.
|
||||
|
||||
**Why deferred:** Needs real LLM API loop (~$2K total — most expensive single category).
|
||||
|
||||
**Threshold:** brain_first_compliance > 95%, back_link_compliance > 90%, citation_format > 95%.
|
||||
|
||||
### BrainBench Cat 9: End-to-End Workflows
|
||||
**What:** 50 end-to-end scenarios across meeting ingestion, email-to-brain, daily-task-prep, briefing generation, sync cycle. Rubric-graded (10-15 criteria each).
|
||||
|
||||
**Why deferred:** Needs LLM agent loop (~$1K). Plus 50 hand-built rubrics.
|
||||
|
||||
**Threshold:** 80% scenario pass rate per workflow.
|
||||
|
||||
### BrainBench Cat 11: Multi-modal Ingestion
|
||||
**What:** PDF/image/audio/video ingestion accuracy. 50 PDFs, 30 images, 20 audio files, 10 videos, 30 HTML pages. Per-modality recall and fidelity metrics.
|
||||
|
||||
**Why deferred:** Needs licensed real datasets (Common Voice for audio etc.). Dataset curation is the bulk of the work.
|
||||
|
||||
**Threshold:** PDF text fidelity > 95% (text-based) / > 80% (scanned), audio WER < 15%, entity_recall > 80% post-ingestion.
|
||||
|
||||
### BrainBench Cat 1+2 at full scale
|
||||
**What:** Existing benchmark-search-quality.ts (29 pages, 20 queries) and benchmark-graph-quality.ts (80 pages, 5 queries) currently pass at small scale. v1.1 extends both to 2-3K rich-prose pages generated via Opus to surface scale-dependent failures (tied keyword clusters, hub-node fan-out, prose-noise extraction precision).
|
||||
|
||||
**Why deferred from PR #188:** Needs ~$200-300 of Opus tokens for the rich corpus. The 80-page version already proves algorithmic correctness; scale-up proves it survives real-world load.
|
||||
|
||||
**Threshold:** maintain v1 metrics at 30x scale.
|
||||
|
||||
### ~~v0.10.4: inferLinkType prose precision fix~~
|
||||
**Shipped in PR #188.** BrainBench Cat 2 rich-corpus type accuracy went from
|
||||
70.7% → 88.5%. Fix: widened verb regexes (added "led the seed/Series A",
|
||||
"early investor", "invests in", "portfolio company", etc.), tightened
|
||||
ADVISES_RE to require explicit advisor rooting (generic "board member"
|
||||
matches investors too), widened context window 80→240 chars, added
|
||||
person-page role prior (partner-bio language → invested_in for outbound
|
||||
company refs only). Per-type after fix: invested_in 91.7% (was 0%),
|
||||
mentions 100%, attended 100%. works_at 58% and advises 41% are next
|
||||
iteration's residuals.
|
||||
|
||||
### v0.10.5: inferLinkType residuals (works_at, advises)
|
||||
**What:** After the v0.10.4 fix, two link types still under-perform on rich
|
||||
prose. Drive these to >85% type accuracy in next iteration.
|
||||
|
||||
**works_at: 58% type accuracy.** Engineer/employee pages use varied phrasings
|
||||
the regex doesn't catch ("spent some time at", "joined the team", narrative
|
||||
"is currently at" without a verb). Approach: extend WORKS_AT_RE; consider
|
||||
employee-role page prior similar to partner prior.
|
||||
|
||||
**advises: 41% type accuracy.** Advisor pages often describe board roles
|
||||
without using the word "advisor" explicitly ("on Beta Health's board",
|
||||
"joined Beta as a board member"). The v0.10.4 fix tightened ADVISES_RE to
|
||||
require "advisor" rooting to avoid false positives from investors. Need
|
||||
a tighter signal that distinguishes "advisor on board" from "investor on
|
||||
board" — likely an advisor-role page prior plus verb-pattern combinations.
|
||||
|
||||
**Threshold:** Cat 2 rich-prose type accuracy > 92% (currently 88.5%).
|
||||
|
||||
### v0.10.4: gbrain alias resolution feature (driven by Cat 3)
|
||||
**What:** Add an alias table to gbrain so "Sarah Chen" / "S. Chen" / "@schen" / "sarah.chen@example.com" resolve to one canonical entity. Schema: `aliases (id, slug, alias_text)` with a unique index. Search blends alias matches into hybrid scoring.
|
||||
|
||||
**Why:** BrainBench Cat 3 measured 31% recall on undocumented aliases — that's the v0.10.x baseline. With alias table, should jump to 80%+.
|
||||
|
||||
**Depends on:** Cat 3 baseline (shipped in PR #188).
|
||||
|
||||
## P1
|
||||
|
||||
### Minions shell jobs — Phase 2 scheduling (deferred from v0.13.0)
|
||||
|
||||
**What:** `minion_schedules` table + autopilot-cycle scanner that submits due shell jobs.
|
||||
|
||||
**Why:** v0.13.0 moves shell scripts to Minions but still leaves scheduling in the host crontab. Your OpenClaw's `scripts/service-manager.sh` + crontab is the only piece left on the host side. A DB-driven scheduler would mean a single `gbrain autopilot --install` replaces the host crontab entirely, scheduling is visible via `gbrain jobs list --scheduled`, and downtime-on-one-machine tolerance improves (schedule is shared DB state, not per-host crontab).
|
||||
|
||||
**Pros:** Canonical host-agnostic deployment. No more host-specific crontab.
|
||||
|
||||
**Cons:** Cross-engine migration complexity (new table on both PGLite + Postgres). Autopilot-cycle scanner needs to handle missed-schedule semantics (fire-once-on-startup or skip-if-past-now), and this is where every other cron-like system has historically accrued bugs.
|
||||
|
||||
**Depends on:** v0.13.0 shell jobs shipped. ✅
|
||||
|
||||
### `gbrain crontab-to-minions <file>` migration helper (deferred from v0.13.0)
|
||||
|
||||
**What:** Parse an existing crontab file, emit a proposed rewrite using `gbrain jobs submit shell ...` for each deterministic entry, keep LLM-requiring entries as-is.
|
||||
|
||||
**Why:** Hand-rewriting ~14 OpenClaw cron entries is error-prone and one-shot. A helper would make the migration reversible and auditable (diff the before/after crontab, dry-run the first N, commit).
|
||||
|
||||
**Pros:** Removes the "rewrite 14 lines by hand" tax every agent operator pays on adoption.
|
||||
|
||||
**Cons:** Crontab parsing is historically fiddly (5-field vs 6-field, `@hourly` aliases, Vixie extensions, env vars in crontab). Could misrewrite entries with shell substitution.
|
||||
|
||||
**Depends on:** v0.13.0 shell jobs shipped. ✅
|
||||
|
||||
### Batch the DB-source extract read path (deferred from v0.12.1)
|
||||
**What:** `extractLinksFromDB` and `extractTimelineFromDB` at `src/commands/extract.ts:447, 504` issue one `engine.getPage(slug)` per slug after `engine.getAllSlugs()`. On a 47K-page brain that's still 47K serial reads over the Supabase pooler.
|
||||
|
||||
**Why:** v0.12.1 fixed the write-side N+1 with batched INSERTs (~100x fewer round-trips). The read side still does serial `getPage()` calls — each fetches `compiled_truth + timeline + frontmatter` (tens of KB per page). On a 47K-page Supabase brain that's ~10-20 minutes of read latency before any work happens. The v0.12.0 orchestrator's backfill uses `--source db`, so this stays slow until fixed.
|
||||
|
||||
**Pros:** Mirrors the write-side fix on the read path. Combined with batched writes, full re-extract on a 47K-page brain should drop from "minutes" to "seconds" end-to-end. Eliminates the implicit `listPages-pagination-mutation` learning risk by giving you a snapshot read.
|
||||
|
||||
**Cons:** New engine method (`getPagesBatch(slugs: string[]) → Promise<Page[]>` or a streaming cursor) needs to land on both PGLite and Postgres. Memory budget — a 47K-page brain with ~30KB/page is ~1.4GB if loaded all at once; needs chunked iteration (e.g., 500 slugs/query, stream-process).
|
||||
|
||||
**Context:** Codex's plan-time review and the testing/performance specialists at ship time both flagged this. Filed during v0.12.1 to ship the bug fix without scope creep. Approach: add `getPagesBatch(slugs)` returning chunked results, then update the 4 DB-source extract paths to consume it.
|
||||
|
||||
**Depends on:** v0.12.1 ships first.
|
||||
|
||||
### Batch embedding queue across files
|
||||
**What:** Shared embedding queue that collects chunks from all parallel import workers and flushes to OpenAI in batches of 100, instead of each worker batching independently.
|
||||
|
||||
**Why:** With 4 workers importing files that average 5 chunks each, you get 4 concurrent OpenAI API calls with small batches (5-10 chunks). A shared queue would batch 100 chunks across workers into one API call, cutting embedding cost and latency roughly in half.
|
||||
|
||||
**Pros:** Fewer API calls (500 chunks = 5 calls instead of ~100), lower cost, faster embedding.
|
||||
|
||||
**Cons:** Adds coordination complexity: backpressure when queue is full, error attribution back to source file, worker pausing. Medium implementation effort.
|
||||
|
||||
**Context:** Deferred during eng review because per-worker embedding is simpler and the parallel workers themselves are the bigger speed win (network round-trips). Revisit after profiling real import workloads to confirm embedding is actually the bottleneck. If most imports use `--no-embed`, this matters less.
|
||||
|
||||
**Implementation sketch:** `src/core/embedding-queue.ts` with a Promise-based semaphore. Workers `await queue.submit(chunks)` which resolves when the queue has room. Queue flushes to OpenAI in batches of 100 with max 2-3 concurrent API calls. Track source file per chunk for error propagation.
|
||||
|
||||
**Depends on:** Part 5 (parallel import with per-worker engines) -- already shipped.
|
||||
|
||||
## P0
|
||||
|
||||
### Fix `bun build --compile` WASM embedding for PGLite
|
||||
**What:** Submit PR to oven-sh/bun fixing WASM file embedding in `bun build --compile` (issue oven-sh/bun#15032).
|
||||
|
||||
**Why:** PGLite's WASM files (~3MB) can't be embedded in the compiled binary. Users who install via `bun install -g gbrain` are fine (WASM resolves from node_modules), but the compiled binary can't use PGLite. Jarred Sumner (Bun founder, YC W22) would likely be receptive.
|
||||
|
||||
**Pros:** Single-binary distribution includes PGLite. No sidecar files needed.
|
||||
|
||||
**Cons:** Requires understanding Bun's bundler internals. May be a large PR.
|
||||
|
||||
**Context:** Issue has been open since Nov 2024. The root cause is that `bun build --compile` generates virtual filesystem paths (`/$bunfs/root/...`) that PGLite can't resolve. Multiple users have reported this. A fix would benefit any WASM-dependent package, not just PGLite.
|
||||
|
||||
**Depends on:** PGLite engine shipping (to have a real use case for the PR).
|
||||
|
||||
### ChatGPT MCP support (OAuth 2.1)
|
||||
**What:** Add OAuth 2.1 with Dynamic Client Registration to the self-hosted MCP server so ChatGPT can connect.
|
||||
|
||||
**Why:** ChatGPT requires OAuth 2.1 for MCP connectors. Bearer token auth is NOT supported. This is the only major AI client that can't use GBrain remotely.
|
||||
|
||||
**Pros:** Completes the "every AI client" promise. ChatGPT has the largest user base.
|
||||
|
||||
**Cons:** OAuth 2.1 is a significant implementation: authorization endpoint, token endpoint, PKCE flow, dynamic client registration. Estimated CC: ~3-4 hours.
|
||||
|
||||
**Context:** Discovered during DX review (2026-04-10). All other clients (Claude Desktop/Code/Cowork, Perplexity) work with bearer tokens. The Edge Function deployment was removed in v0.8.0. OAuth needs to be added to the self-hosted HTTP MCP server (or `gbrain serve --http` when implemented).
|
||||
|
||||
**Depends on:** `gbrain serve --http` (not yet implemented).
|
||||
|
||||
### Runtime MCP access control
|
||||
**What:** Add sender identity checking to MCP operations. Brain ops return filtered data based on access tier (Full/Work/Family/None).
|
||||
|
||||
**Why:** ACCESS_POLICY.md is prompt-layer enforcement (agent reads policy before responding). A direct MCP caller can bypass it. Runtime enforcement in the MCP server is the real security boundary for multi-user and remote deployments.
|
||||
|
||||
**Pros:** Real security boundary. ACCESS_POLICY.md becomes enforceable, not advisory.
|
||||
|
||||
**Cons:** Requires adding `sender_id` or `access_tier` to `OperationContext`. Each mutating operation needs a permission check. Medium implementation effort.
|
||||
|
||||
**Context:** From CEO review + Codex outside voice (2026-04-13). Prompt-layer access control works in practice (same model as Wintermute) but is not sufficient for remote MCP where direct tool calls bypass the agent's prompt.
|
||||
|
||||
**Depends on:** v0.10.0 GStackBrain skill layer (shipped).
|
||||
|
||||
## P1 (new from v0.7.0)
|
||||
|
||||
### ~~Constrained health_check DSL for third-party recipes~~
|
||||
**Completed:** v0.9.3 (2026-04-12). Typed DSL with 4 check types (`http`, `env_exists`, `command`, `any_of`). All 7 first-party recipes migrated. String health checks accepted with deprecation warning + metachar validation for non-embedded recipes.
|
||||
|
||||
## P1 (new from v0.11.0 — Minions)
|
||||
|
||||
### Per-queue rate limiting for Minions
|
||||
**What:** Token-bucket rate limiting per queue via a new `minion_rate_limits` table (queue, capacity, refill_rate, tokens, updated_at), with acquire/release in `claim()`.
|
||||
|
||||
**Why:** The #1 daily OpenClaw pain is spawn storms hitting OpenAI/Anthropic rate limits. `max_children` caps fan-out per parent, but a queue with 50 ready jobs will still slam the API. Every Minions consumer currently reinvents token-bucket in user code.
|
||||
|
||||
**Pros:** First-class rate limiting means no consumer has to roll their own. Composes with `max_children` (which is per-parent) to give two orthogonal throttles.
|
||||
|
||||
**Cons:** Adds a write hotspot on the rate-limit row. Mitigate by keeping it a simple `UPDATE ... WHERE tokens > 0 RETURNING` that fails fast and puts the claim back in the pool.
|
||||
|
||||
**Effort:** ~2 hours. Deferred from v0.11.0 to keep the parity PR at a reviewable size.
|
||||
|
||||
**Depends on:** Minions (shipped in v0.11.0).
|
||||
|
||||
### Minions repeat/cron scheduler
|
||||
**What:** BullMQ-style repeatable jobs. `queue.add(name, data, { repeat: { cron: '0 * * * *' } })`.
|
||||
|
||||
**Why:** Idempotency keys (shipped in v0.11.0) are the foundation. Consumers currently use launchd/cron to fire `gbrain jobs submit`, but a native scheduler inside the worker would be cleaner and portable across deployments.
|
||||
|
||||
**Pros:** One mental model for both immediate and scheduled work. Idempotency prevents double-fire.
|
||||
|
||||
**Cons:** Every cron library has edge cases (DST, missed intervals on worker restart). Use a battle-tested parser.
|
||||
|
||||
**Effort:** ~1 day.
|
||||
|
||||
**Depends on:** Idempotency keys (shipped in v0.11.0).
|
||||
|
||||
### Minions worker event emitter
|
||||
**What:** `worker.on('job:completed', handler)` / `worker.on('job:failed', ...)` instead of polling.
|
||||
|
||||
**Why:** Consumers currently poll `getJob(id)` to watch state changes. An event API is the ergonomic BullMQ has and Minions doesn't.
|
||||
|
||||
**Effort:** ~4 hours.
|
||||
|
||||
### `waitForChildren(parent_id, n)` / `collectResults(parent_id)` helpers
|
||||
**What:** Convenience wrappers over `readChildCompletions` for common fan-in patterns.
|
||||
|
||||
**Why:** The `child_done` inbox primitive shipped in v0.11.0. Now add the ergonomic API on top so orchestrators don't have to write the polling loop.
|
||||
|
||||
**Effort:** ~2 hours.
|
||||
|
||||
**Depends on:** `child_done` inbox primitive (shipped in v0.11.0).
|
||||
|
||||
## P2
|
||||
|
||||
### Minions: `gbrain jobs stats --orphaned` (deferred from v0.13.0)
|
||||
|
||||
**What:** New CLI flag / output column surfacing jobs that are waiting with no registered handler on any live worker.
|
||||
|
||||
**Why:** v0.13.0 adds shell jobs that require `GBRAIN_ALLOW_SHELL_JOBS=1` on the worker. If an operator submits a shell job but no worker with the flag is running, the row sits in `waiting` silently. The CLI's starvation warning + docs help at submit time; this TODO surfaces the problem at operational-check time.
|
||||
|
||||
**Pros:** Closes the "did my cron actually run" ambiguity for multi-machine deployments.
|
||||
|
||||
**Cons:** Knowing "no worker has this handler registered" requires worker heartbeat tracking, which Minions doesn't have yet (it's stateless at DB level beyond `lock_token`). Could be approximated by "no jobs of this name have completed in last N minutes AND count of waiting is > 0."
|
||||
|
||||
**Depends on:** v0.13.0 shell jobs shipped. ✅
|
||||
|
||||
### Minions: AbortReason plumbing on MinionJobContext (deferred from v0.13.0)
|
||||
|
||||
**What:** Handlers today can't distinguish whether `ctx.signal.aborted` fired due to timeout, cancel, or lock-loss. v0.13.0 derives this at worker-catch-time from `abort.signal.reason`, but the handler can't see it directly. Expose `ctx.abortReason?: 'timeout' | 'cancel' | 'lock-lost' | 'shutdown'` on the context.
|
||||
|
||||
**Why:** Shell handler's kill-sequence today can't decide "retry this" (lock-lost) vs "don't retry, user cancelled" (cancel) — they look the same. A typed AbortReason lets handlers make that decision for themselves.
|
||||
|
||||
**Pros:** Handlers get richer signals.
|
||||
|
||||
**Cons:** Small surface-area addition to the handler API. Not strictly required since the worker already makes the retry/dead decision for them.
|
||||
|
||||
**Depends on:** v0.13.0 shell jobs shipped. ✅
|
||||
|
||||
### Minions: blocking-mode audit log for true forensic integrity (deferred from v0.13.0)
|
||||
|
||||
**What:** Opt-in mode for `shell-audit` where `appendFileSync` failures DO block submission instead of logging-and-continuing.
|
||||
|
||||
**Why:** v0.13.0 ships the audit log in best-effort mode, which means a disk-full attacker can silently disable the forensic trail. Acceptable for v0.13.0 because the primary use is operational ("what did this cron do last Tuesday"), not security forensics. Operators who want fail-closed semantics should have a flag.
|
||||
|
||||
**Pros:** Enables true forensic integrity for deployments that need it.
|
||||
|
||||
**Cons:** Fail-closed means a transient disk issue blocks shell submissions, which can be worse than a missing log line for most operators. Opt-in is the right shape but adds surface area.
|
||||
|
||||
**Depends on:** v0.13.0 shell jobs shipped. ✅
|
||||
|
||||
### Minions: configurable per-job output buffer sizes (deferred from v0.13.0)
|
||||
|
||||
**What:** Add `max_stdout_bytes` / `max_stderr_bytes` to ShellJobParams; override the 64KB/16KB defaults.
|
||||
|
||||
**Why:** 64KB/16KB covers typical OpenClaw scripts today but a verbose benchmark or a debug-dump script could need more.
|
||||
|
||||
**Depends on:** First shell-job author who actually needs it. Don't pre-build the flag.
|
||||
|
||||
### Security hardening follow-ups (deferred from security-wave-3)
|
||||
**What:** Close remaining security gaps identified during the v0.9.4 Codex outside-voice review that didn't make the wave's in-scope cut.
|
||||
|
||||
**Why:** Wave 3 closed 5 blockers + 4 mediums. These are the known residuals. Each is an independent hardening item that becomes trivial as Runtime MCP access control (P0 above) lands.
|
||||
|
||||
**Items (each a separate small task):**
|
||||
- **DNS rebinding protection for HTTP health_checks.** Current `isInternalUrl` validates the hostname string; DNS resolution happens later inside `fetch`. A malicious DNS server can return a public IP on first lookup and an internal IP on the actual request. Fix: resolve hostname via `dns.lookup` before fetch, pin the IP with a custom `http.Agent` `lookup` override, re-validate post-resolution. Alternative: use `ssrf-req-filter` library.
|
||||
- **Extended IPv6 private-range coverage.** Block `fc00::/7` (Unique Local Addresses), `fe80::/10` (link-local), `2002::/16` (6to4), `2001::/32` (Teredo), `::/128`. Current code covers `::1`, `::`, and IPv4-mapped (`::ffff:*`) via hex hextet parsing.
|
||||
- **IPv4 shorthand parsing.** `127.1` (legacy 2-octet form = 127.0.0.1), `127.0.1` (3-octet), mixed-radix with trailing dots. Current code handles hex/octal/decimal integer-form IPs but not these shorthand variants.
|
||||
- **Broader operation-layer limit caps.** `traverse_graph` `depth` param, plus `get_chunks`, `get_links`, `get_backlinks`, `get_timeline`, `get_versions`, `get_raw_data`, `resolve_slugs` — all currently accept unbounded `limit`/`depth`. Wave 3 only clamped `list_pages` and `get_ingest_log`.
|
||||
- **`sync_brain` repo path validation.** The `repo` parameter accepts an arbitrary filesystem path. Same threat model as `file_upload` before wave 3. Add `validateUploadPath` (strict) for remote callers.
|
||||
- **`file_upload` size limit.** `readFileSync` loads the entire file into memory. Trivial memory-DoS from MCP. Add ~100MB cap (matches CLI's TUS routing threshold) and stream for larger files.
|
||||
- **`file_upload` regular-file check.** Reject directories, devices, FIFOs, Unix sockets via `stat.isFile()` before `readFileSync`.
|
||||
- **Explicit confinement root (H2).** `file_upload` strict mode currently uses `process.cwd()`. Move to `ctx.config.upload_root` (or derive from where the brain's schema lives) so MCP server cwd can't be the wrong anchor.
|
||||
|
||||
**Effort:** M total (human: ~1 day / CC: ~1-2 hrs).
|
||||
|
||||
**Priority:** P2 — deferred consciously. Wave 3 closed the easily-exploitable paths. These are the defense-in-depth follow-ups.
|
||||
|
||||
**Depends on:** Security wave 3 shipped. None are blockers for Runtime MCP access control, but all three security workstreams (this, that P0, and the health-check DSL) converge on the same zero-trust MCP goal.
|
||||
|
||||
### Community recipe submission (`gbrain integrations submit`)
|
||||
**What:** Package a user's custom integration recipe as a PR to the GBrain repo. Validates frontmatter, checks constrained DSL health_checks, creates PR with template.
|
||||
|
||||
**Why:** Turns GBrain from a single-author integration set into a community ecosystem. The recipe format IS the contribution format.
|
||||
|
||||
**Pros:** Community-driven integration library. Users build Slack-to-brain, RSS-to-brain, Discord-to-brain.
|
||||
|
||||
**Cons:** Support burden. Need constrained DSL (P1) before accepting third-party recipes. Need review process for recipe quality.
|
||||
|
||||
**Context:** From CEO review (2026-04-11). User explicitly deferred due to bandwidth constraints. Target v0.9.0.
|
||||
|
||||
**Depends on:** Constrained health_check DSL (P1) — **SHIPPED in v0.9.3.**
|
||||
|
||||
### Always-on deployment recipes (Fly.io, Railway)
|
||||
**What:** Alternative deployment recipes for voice-to-brain and future integrations that run on cloud servers instead of local + ngrok.
|
||||
|
||||
**Why:** ngrok free URLs are ephemeral (change on restart). Always-on deployment eliminates the watchdog complexity and gives a stable webhook URL.
|
||||
|
||||
**Pros:** Stable URLs, no ngrok dependency, production-grade uptime.
|
||||
|
||||
**Cons:** Costs $5-10/mo per integration. Requires cloud account.
|
||||
|
||||
**Context:** From DX review (2026-04-11). v0.7.0 ships local+ngrok as v1 deployment path.
|
||||
|
||||
**Depends on:** v0.7.0 recipe format (shipped).
|
||||
|
||||
### `gbrain serve --http` + Fly.io/Railway deployment
|
||||
**What:** Add `gbrain serve --http` as a thin HTTP wrapper around the stdio MCP server. Include a Dockerfile/fly.toml for cloud deployment.
|
||||
|
||||
**Why:** The Edge Function deployment was removed in v0.8.0. Remote MCP now requires a custom HTTP wrapper around `gbrain serve`. A built-in `--http` flag would make this zero-effort. Bun runs natively, no bundling seam, no 60s timeout, no cold start.
|
||||
|
||||
**Pros:** Simpler remote MCP setup. Users run `gbrain serve --http` behind ngrok instead of building a custom server. Supports all 30 operations remotely (including sync_brain and file_upload).
|
||||
|
||||
**Cons:** Users need ngrok ($8/mo) or a cloud host (Fly.io $5/mo, Railway $5/mo). Not zero-infra.
|
||||
|
||||
**Context:** Production deployments use a custom Hono server wrapping `gbrain serve`. This TODO would formalize that pattern into the CLI. ChatGPT OAuth 2.1 support depends on this.
|
||||
|
||||
**Depends on:** v0.8.0 (Edge Function removal shipped).
|
||||
|
||||
## P2 (knowledge graph follow-ups)
|
||||
|
||||
### Auto-link skipped writes generate redundant SQL
|
||||
**What:** When `gbrain put` is called with identical content (status=skipped), runAutoLink still does a full getLinks + per-candidate addLink loop. On N identical writes of a 50-entity page that's 50N round trips.
|
||||
|
||||
**Why:** Defensive reconciliation catches drift between page text and links table, but on truly idempotent writes it's wasted work.
|
||||
|
||||
**Pros:** Lower DB load on cron-style re-syncs. Keeps put_page latency tight under bulk MCP usage.
|
||||
|
||||
**Cons:** Need to track whether links could have drifted independent of content (e.g., a target page was deleted). Conservative approach: only skip auto-link reconciliation if status=skipped AND existing links match desired set (which still requires the getLinks call).
|
||||
|
||||
**Context:** Caught in /ship adversarial review (2026-04-18). Acceptable for v0.10.3 because auto-link runs in a transaction with row locks, so amplification cost is bounded.
|
||||
|
||||
**Effort estimate:** S (CC: ~10min)
|
||||
**Priority:** P2
|
||||
**Depends on:** Nothing.
|
||||
|
||||
### Audit `extract --source db` against auto_link config flag
|
||||
**What:** `gbrain extract links --source db` writes to the same `links` table that `auto_link=false` is supposed to opt out of. The two are conceptually distinct (extract is intentional batch op, auto_link is implicit on write), but a user who turned off auto_link expecting "no automatic link writes" might be surprised.
|
||||
|
||||
**Why:** Either the behavior should match (extract checks auto_link too) or the docs should explicitly state extract is a superset.
|
||||
|
||||
**Pros:** Less surprise for users who treat auto_link as a master switch.
|
||||
|
||||
**Cons:** Some users want extract to work even when auto_link is off (e.g. one-time backfill).
|
||||
|
||||
**Context:** Caught in /ship adversarial review (2026-04-18). Documenting for now.
|
||||
|
||||
**Effort estimate:** S (CC: ~10min for docs OR ~20min for code change).
|
||||
**Priority:** P2
|
||||
**Depends on:** Nothing.
|
||||
|
||||
### Doctor --fix polish from v0.14.1 adversarial review
|
||||
**What:** Six deferred findings from v0.14.1 ship-time adversarial review on `src/core/dry-fix.ts`:
|
||||
1. **TOCTOU between read and write.** `attemptFix` reads once, writes later. Concurrent editor saves silently overwritten. Fix: re-read immediately before write and compare snapshot, or `O_EXCL` tempfile + rename.
|
||||
2. **Fence detection misses 4-backtick and `~~~` fences.** `isInsideCodeFence` only catches `^```$`. CommonMark-legal alternates slip through.
|
||||
3. **`expandBullet` walk-up is dead code.** Loop breaks immediately because `baseIndent` matches the current line. Remove or make it actually walk up.
|
||||
4. **Multi-match guard too strict.** Skills with the pattern in a table-of-contents AND body get `ambiguous_multiple_matches` forever. Consider: fix first, re-scan, repeat until fixed-point.
|
||||
5. **Subprocess spam.** `getWorkingTreeStatus` spawns `git status` N×M times per `doctor --fix`. Cache per-skill per-invocation.
|
||||
6. **`doctor --fix --json` swallows the auto-fix report.** `printAutoFixReport` returns early on `jsonOutput`; agents don't see fix outcomes. Emit `auto_fix` as a top-level key.
|
||||
|
||||
**Why:** None are ship-blockers; all surfaced during v0.14.1 Codex adversarial review. Bundle into one follow-up PR.
|
||||
|
||||
**Pros:** Closes the adversarial findings loop. Better correctness under concurrent edits and JSON-consumer agents.
|
||||
|
||||
**Cons:** Concurrent-edit test is finicky.
|
||||
|
||||
**Context:** v0.14.1 shipped with the 4 critical fixes (shell-injection via execFileSync, no-git-backup detection, EOF newline preservation, proximity-window consistency). These six are the deferred remainder.
|
||||
|
||||
**Effort estimate:** M (CC: ~45min for all six + tests).
|
||||
**Priority:** P2
|
||||
**Depends on:** Nothing.
|
||||
|
||||
## Completed
|
||||
|
||||
### Implement AWS Signature V4 for S3 storage backend
|
||||
**Completed:** v0.6.0 (2026-04-10) — replaced with @aws-sdk/client-s3 for proper SigV4 signing.
|
||||
@@ -1,506 +0,0 @@
|
||||
{
|
||||
"lockfileVersion": 1,
|
||||
"configVersion": 1,
|
||||
"workspaces": {
|
||||
"": {
|
||||
"name": "gbrain",
|
||||
"dependencies": {
|
||||
"@anthropic-ai/sdk": "^0.30.0",
|
||||
"@aws-sdk/client-s3": "^3.1028.0",
|
||||
"@electric-sql/pglite": "^0.4.4",
|
||||
"@modelcontextprotocol/sdk": "^1.0.0",
|
||||
"gray-matter": "^4.0.3",
|
||||
"marked": "^18.0.0",
|
||||
"openai": "^4.0.0",
|
||||
"pgvector": "^0.2.0",
|
||||
"postgres": "^3.4.0",
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/bun": "latest",
|
||||
},
|
||||
},
|
||||
},
|
||||
"packages": {
|
||||
"@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.30.1", "", { "dependencies": { "@types/node": "^18.11.18", "@types/node-fetch": "^2.6.4", "abort-controller": "^3.0.0", "agentkeepalive": "^4.2.1", "form-data-encoder": "1.7.2", "formdata-node": "^4.3.2", "node-fetch": "^2.6.7" } }, "sha512-nuKvp7wOIz6BFei8WrTdhmSsx5mwnArYyJgh4+vYu3V4J0Ltb8Xm3odPm51n1aSI0XxNCrDl7O88cxCtUdAkaw=="],
|
||||
|
||||
"@aws-crypto/crc32": ["@aws-crypto/crc32@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg=="],
|
||||
|
||||
"@aws-crypto/crc32c": ["@aws-crypto/crc32c@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-+iWb8qaHLYKrNvGRbiYRHSdKRWhto5XlZUEBwDjYNf+ly5SVYG6zEoYIdxvf5R3zyeP16w4PLBn3rH1xc74Rag=="],
|
||||
|
||||
"@aws-crypto/sha1-browser": ["@aws-crypto/sha1-browser@5.2.0", "", { "dependencies": { "@aws-crypto/supports-web-crypto": "^5.2.0", "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "@aws-sdk/util-locate-window": "^3.0.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-OH6lveCFfcDjX4dbAvCFSYUjJZjDr/3XJ3xHtjn3Oj5b9RjojQo8npoLeA/bNwkOkrSQ0wgrHzXk4tDRxGKJeg=="],
|
||||
|
||||
"@aws-crypto/sha256-browser": ["@aws-crypto/sha256-browser@5.2.0", "", { "dependencies": { "@aws-crypto/sha256-js": "^5.2.0", "@aws-crypto/supports-web-crypto": "^5.2.0", "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "@aws-sdk/util-locate-window": "^3.0.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw=="],
|
||||
|
||||
"@aws-crypto/sha256-js": ["@aws-crypto/sha256-js@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA=="],
|
||||
|
||||
"@aws-crypto/supports-web-crypto": ["@aws-crypto/supports-web-crypto@5.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg=="],
|
||||
|
||||
"@aws-crypto/util": ["@aws-crypto/util@5.2.0", "", { "dependencies": { "@aws-sdk/types": "^3.222.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ=="],
|
||||
|
||||
"@aws-sdk/client-s3": ["@aws-sdk/client-s3@3.1028.0", "", { "dependencies": { "@aws-crypto/sha1-browser": "5.2.0", "@aws-crypto/sha256-browser": "5.2.0", "@aws-crypto/sha256-js": "5.2.0", "@aws-sdk/core": "^3.973.27", "@aws-sdk/credential-provider-node": "^3.972.30", "@aws-sdk/middleware-bucket-endpoint": "^3.972.9", "@aws-sdk/middleware-expect-continue": "^3.972.9", "@aws-sdk/middleware-flexible-checksums": "^3.974.7", "@aws-sdk/middleware-host-header": "^3.972.9", "@aws-sdk/middleware-location-constraint": "^3.972.9", "@aws-sdk/middleware-logger": "^3.972.9", "@aws-sdk/middleware-recursion-detection": "^3.972.10", "@aws-sdk/middleware-sdk-s3": "^3.972.28", "@aws-sdk/middleware-ssec": "^3.972.9", "@aws-sdk/middleware-user-agent": "^3.972.29", "@aws-sdk/region-config-resolver": "^3.972.11", "@aws-sdk/signature-v4-multi-region": "^3.996.16", "@aws-sdk/types": "^3.973.7", "@aws-sdk/util-endpoints": "^3.996.6", "@aws-sdk/util-user-agent-browser": "^3.972.9", "@aws-sdk/util-user-agent-node": "^3.973.15", "@smithy/config-resolver": "^4.4.14", "@smithy/core": "^3.23.14", "@smithy/eventstream-serde-browser": "^4.2.13", "@smithy/eventstream-serde-config-resolver": "^4.3.13", "@smithy/eventstream-serde-node": "^4.2.13", "@smithy/fetch-http-handler": "^5.3.16", "@smithy/hash-blob-browser": "^4.2.14", "@smithy/hash-node": "^4.2.13", "@smithy/hash-stream-node": "^4.2.13", "@smithy/invalid-dependency": "^4.2.13", "@smithy/md5-js": "^4.2.13", "@smithy/middleware-content-length": "^4.2.13", "@smithy/middleware-endpoint": "^4.4.29", "@smithy/middleware-retry": "^4.5.0", "@smithy/middleware-serde": "^4.2.17", "@smithy/middleware-stack": "^4.2.13", "@smithy/node-config-provider": "^4.3.13", "@smithy/node-http-handler": "^4.5.2", "@smithy/protocol-http": "^5.3.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "@smithy/url-parser": "^4.2.13", "@smithy/util-base64": "^4.3.2", "@smithy/util-body-length-browser": "^4.2.2", "@smithy/util-body-length-node": "^4.2.3", "@smithy/util-defaults-mode-browser": "^4.3.45", "@smithy/util-defaults-mode-node": "^4.2.49", "@smithy/util-endpoints": "^3.3.4", "@smithy/util-middleware": "^4.2.13", "@smithy/util-retry": "^4.3.0", "@smithy/util-stream": "^4.5.22", "@smithy/util-utf8": "^4.2.2", "@smithy/util-waiter": "^4.2.15", "tslib": "^2.6.2" } }, "sha512-KL8PREFJxyWXUjMQR6Krq/OjZ5qbcV1QFjtA7Q7oMW5XaFO9YoSBtBxQeeXO4um6vYSmRVYVDTvEKZDcNbyeXw=="],
|
||||
|
||||
"@aws-sdk/core": ["@aws-sdk/core@3.973.27", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@aws-sdk/xml-builder": "^3.972.17", "@smithy/core": "^3.23.14", "@smithy/node-config-provider": "^4.3.13", "@smithy/property-provider": "^4.2.13", "@smithy/protocol-http": "^5.3.13", "@smithy/signature-v4": "^5.3.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "@smithy/util-base64": "^4.3.2", "@smithy/util-middleware": "^4.2.13", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-CUZ5m8hwMCH6OYI4Li/WgMfIEx10Q2PLI9Y3XOUTPGZJ53aZ0007jCv+X/ywsaERyKPdw5MRZWk877roQksQ4A=="],
|
||||
|
||||
"@aws-sdk/crc64-nvme": ["@aws-sdk/crc64-nvme@3.972.6", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-NMbiqKdruhwwgI6nzBVe2jWMkXjaoQz2YOs3rFX+2F3gGyrJDkDPwMpV/RsTFeq2vAQ055wZNtOXFK4NYSkM8g=="],
|
||||
|
||||
"@aws-sdk/credential-provider-env": ["@aws-sdk/credential-provider-env@3.972.25", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/types": "^3.973.7", "@smithy/property-provider": "^4.2.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-6QfI0wv4jpG5CrdO/AO0JfZ2ux+tKwJPrUwmvxXF50vI5KIypKVGNF6b4vlkYEnKumDTI1NX2zUBi8JoU5QU3A=="],
|
||||
|
||||
"@aws-sdk/credential-provider-http": ["@aws-sdk/credential-provider-http@3.972.27", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/types": "^3.973.7", "@smithy/fetch-http-handler": "^5.3.16", "@smithy/node-http-handler": "^4.5.2", "@smithy/property-provider": "^4.2.13", "@smithy/protocol-http": "^5.3.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "@smithy/util-stream": "^4.5.22", "tslib": "^2.6.2" } }, "sha512-3V3Usj9Gs93h865DqN4M2NWJhC5kXU9BvZskfN3+69omuYlE3TZxOEcVQtBGLOloJB7BVfJKXVLqeNhOzHqSlQ=="],
|
||||
|
||||
"@aws-sdk/credential-provider-ini": ["@aws-sdk/credential-provider-ini@3.972.29", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/credential-provider-env": "^3.972.25", "@aws-sdk/credential-provider-http": "^3.972.27", "@aws-sdk/credential-provider-login": "^3.972.29", "@aws-sdk/credential-provider-process": "^3.972.25", "@aws-sdk/credential-provider-sso": "^3.972.29", "@aws-sdk/credential-provider-web-identity": "^3.972.29", "@aws-sdk/nested-clients": "^3.996.19", "@aws-sdk/types": "^3.973.7", "@smithy/credential-provider-imds": "^4.2.13", "@smithy/property-provider": "^4.2.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-SiBuAnXecCbT/OpAf3vqyI/AVE3mTaYr9ShXLybxZiPLBiPCCOIWSGAtYYGQWMRvobBTiqOewaB+wcgMMZI2Aw=="],
|
||||
|
||||
"@aws-sdk/credential-provider-login": ["@aws-sdk/credential-provider-login@3.972.29", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/nested-clients": "^3.996.19", "@aws-sdk/types": "^3.973.7", "@smithy/property-provider": "^4.2.13", "@smithy/protocol-http": "^5.3.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-OGOslTbOlxXexKMqhxCEbBQbUIfuhGxU5UXw3Fm56ypXHvrXH4aTt/xb5Y884LOoteP1QST1lVZzHfcTnWhiPQ=="],
|
||||
|
||||
"@aws-sdk/credential-provider-node": ["@aws-sdk/credential-provider-node@3.972.30", "", { "dependencies": { "@aws-sdk/credential-provider-env": "^3.972.25", "@aws-sdk/credential-provider-http": "^3.972.27", "@aws-sdk/credential-provider-ini": "^3.972.29", "@aws-sdk/credential-provider-process": "^3.972.25", "@aws-sdk/credential-provider-sso": "^3.972.29", "@aws-sdk/credential-provider-web-identity": "^3.972.29", "@aws-sdk/types": "^3.973.7", "@smithy/credential-provider-imds": "^4.2.13", "@smithy/property-provider": "^4.2.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-FMnAnWxc8PG+ZrZ2OBKzY4luCUJhe9CG0B9YwYr4pzrYGLXBS2rl+UoUvjGbAwiptxRL6hyA3lFn03Bv1TLqTw=="],
|
||||
|
||||
"@aws-sdk/credential-provider-process": ["@aws-sdk/credential-provider-process@3.972.25", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/types": "^3.973.7", "@smithy/property-provider": "^4.2.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-HR7ynNRdNhNsdVCOCegy1HsfsRzozCOPtD3RzzT1JouuaHobWyRfJzCBue/3jP7gECHt+kQyZUvwg/cYLWurNQ=="],
|
||||
|
||||
"@aws-sdk/credential-provider-sso": ["@aws-sdk/credential-provider-sso@3.972.29", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/nested-clients": "^3.996.19", "@aws-sdk/token-providers": "3.1026.0", "@aws-sdk/types": "^3.973.7", "@smithy/property-provider": "^4.2.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-HWv4SEq3jZDYPlwryZVef97+U8CxxRos5mK8sgGO1dQaFZpV5giZLzqGE5hkDmh2csYcBO2uf5XHjPTpZcJlig=="],
|
||||
|
||||
"@aws-sdk/credential-provider-web-identity": ["@aws-sdk/credential-provider-web-identity@3.972.29", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/nested-clients": "^3.996.19", "@aws-sdk/types": "^3.973.7", "@smithy/property-provider": "^4.2.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-PdMBza1WEKEUPFEmMGCfnU2RYCz9MskU2e8JxjyUOsMKku7j9YaDKvbDi2dzC0ihFoM6ods2SbhfAAro+Gwlew=="],
|
||||
|
||||
"@aws-sdk/middleware-bucket-endpoint": ["@aws-sdk/middleware-bucket-endpoint@3.972.9", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@aws-sdk/util-arn-parser": "^3.972.3", "@smithy/node-config-provider": "^4.3.13", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "@smithy/util-config-provider": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-COToYKgquDyligbcAep7ygs48RK+mwe/IYprq4+TSrVFzNOYmzWvHf6werpnKV5VYpRiwdn+Wa5ZXkPqLVwcTg=="],
|
||||
|
||||
"@aws-sdk/middleware-expect-continue": ["@aws-sdk/middleware-expect-continue@3.972.9", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-V/FNCjFxnh4VGu+HdSiW4Yg5GELihA1MIDSAdsEPvuayXBVmr0Jaa6jdLAZLH38KYXl/vVjri9DQJWnTAujHEA=="],
|
||||
|
||||
"@aws-sdk/middleware-flexible-checksums": ["@aws-sdk/middleware-flexible-checksums@3.974.7", "", { "dependencies": { "@aws-crypto/crc32": "5.2.0", "@aws-crypto/crc32c": "5.2.0", "@aws-crypto/util": "5.2.0", "@aws-sdk/core": "^3.973.27", "@aws-sdk/crc64-nvme": "^3.972.6", "@aws-sdk/types": "^3.973.7", "@smithy/is-array-buffer": "^4.2.2", "@smithy/node-config-provider": "^4.3.13", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "@smithy/util-middleware": "^4.2.13", "@smithy/util-stream": "^4.5.22", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-uU4/ch2CLHB8Phu1oTKnnQ4e8Ujqi49zEnQYBhWYT53zfFvtJCdGsaOoypBr8Fm/pmCBssRmGoIQ4sixgdLP9w=="],
|
||||
|
||||
"@aws-sdk/middleware-host-header": ["@aws-sdk/middleware-host-header@3.972.9", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-je5vRdNw4SkuTnmRbFZLdye4sQ0faLt8kwka5wnnSU30q1mHO4X+idGEJOOE+Tn1ME7Oryn05xxkDvIb3UaLaQ=="],
|
||||
|
||||
"@aws-sdk/middleware-location-constraint": ["@aws-sdk/middleware-location-constraint@3.972.9", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-TyfOi2XNdOZpNKeTJwRUsVAGa+14nkyMb2VVGG+eDgcWG/ed6+NUo72N3hT6QJioxym80NSinErD+LBRF0Ir1w=="],
|
||||
|
||||
"@aws-sdk/middleware-logger": ["@aws-sdk/middleware-logger@3.972.9", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-HsVgDrruhqI28RkaXALm8grJ7Agc1wF6Et0xh6pom8NdO2VdO/SD9U/tPwUjewwK/pVoka+EShBxyCvgsPCtog=="],
|
||||
|
||||
"@aws-sdk/middleware-recursion-detection": ["@aws-sdk/middleware-recursion-detection@3.972.10", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@aws/lambda-invoke-store": "^0.2.2", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-RVQQbq5orQ/GHUnXvqEOj2HHPBJm+mM+ySwZKS5UaLBwra5ugRtiH09PLUoOZRl7a1YzaOzXSuGbn9iD5j60WQ=="],
|
||||
|
||||
"@aws-sdk/middleware-sdk-s3": ["@aws-sdk/middleware-sdk-s3@3.972.28", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/types": "^3.973.7", "@aws-sdk/util-arn-parser": "^3.972.3", "@smithy/core": "^3.23.14", "@smithy/node-config-provider": "^4.3.13", "@smithy/protocol-http": "^5.3.13", "@smithy/signature-v4": "^5.3.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "@smithy/util-config-provider": "^4.2.2", "@smithy/util-middleware": "^4.2.13", "@smithy/util-stream": "^4.5.22", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-qJHcJQH9UNPUrnPlRtCozKjtqAaypQ5IgQxTNoPsVYIQeuwNIA8Rwt3NvGij1vCDYDfCmZaPLpnJEHlZXeFqmg=="],
|
||||
|
||||
"@aws-sdk/middleware-ssec": ["@aws-sdk/middleware-ssec@3.972.9", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-wSA2BR7L0CyBNDJeSrleIIzC+DzL93YNTdfU0KPGLiocK6YsRv1nPAzPF+BFSdcs0Qa5ku5Kcf4KvQcWwKGenQ=="],
|
||||
|
||||
"@aws-sdk/middleware-user-agent": ["@aws-sdk/middleware-user-agent@3.972.29", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/types": "^3.973.7", "@aws-sdk/util-endpoints": "^3.996.6", "@smithy/core": "^3.23.14", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "@smithy/util-retry": "^4.3.0", "tslib": "^2.6.2" } }, "sha512-f/sIRzuTfEjg6NsbMYvye2VsmnQoNgntntleQyx5uGacUYzszbfIlO3GcI6G6daWUmTm0IDZc11qMHWwF0o0mQ=="],
|
||||
|
||||
"@aws-sdk/nested-clients": ["@aws-sdk/nested-clients@3.996.19", "", { "dependencies": { "@aws-crypto/sha256-browser": "5.2.0", "@aws-crypto/sha256-js": "5.2.0", "@aws-sdk/core": "^3.973.27", "@aws-sdk/middleware-host-header": "^3.972.9", "@aws-sdk/middleware-logger": "^3.972.9", "@aws-sdk/middleware-recursion-detection": "^3.972.10", "@aws-sdk/middleware-user-agent": "^3.972.29", "@aws-sdk/region-config-resolver": "^3.972.11", "@aws-sdk/types": "^3.973.7", "@aws-sdk/util-endpoints": "^3.996.6", "@aws-sdk/util-user-agent-browser": "^3.972.9", "@aws-sdk/util-user-agent-node": "^3.973.15", "@smithy/config-resolver": "^4.4.14", "@smithy/core": "^3.23.14", "@smithy/fetch-http-handler": "^5.3.16", "@smithy/hash-node": "^4.2.13", "@smithy/invalid-dependency": "^4.2.13", "@smithy/middleware-content-length": "^4.2.13", "@smithy/middleware-endpoint": "^4.4.29", "@smithy/middleware-retry": "^4.5.0", "@smithy/middleware-serde": "^4.2.17", "@smithy/middleware-stack": "^4.2.13", "@smithy/node-config-provider": "^4.3.13", "@smithy/node-http-handler": "^4.5.2", "@smithy/protocol-http": "^5.3.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "@smithy/url-parser": "^4.2.13", "@smithy/util-base64": "^4.3.2", "@smithy/util-body-length-browser": "^4.2.2", "@smithy/util-body-length-node": "^4.2.3", "@smithy/util-defaults-mode-browser": "^4.3.45", "@smithy/util-defaults-mode-node": "^4.2.49", "@smithy/util-endpoints": "^3.3.4", "@smithy/util-middleware": "^4.2.13", "@smithy/util-retry": "^4.3.0", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-uFkmCDXvmQYLanlYdOFS0+MQWkrj9wPMt/ZCc/0J0fjPim6F5jBVBmEomvGY/j77ILW6GTPwN22Jc174Mhkw6Q=="],
|
||||
|
||||
"@aws-sdk/region-config-resolver": ["@aws-sdk/region-config-resolver@3.972.11", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/config-resolver": "^4.4.14", "@smithy/node-config-provider": "^4.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-6Q8B1dcx6BBqUTY1Mc/eROKA0FImEEY5VPSd6AGPEUf0ErjExz4snVqa9kNJSoVDV1rKaNf3qrWojgcKW+SdDg=="],
|
||||
|
||||
"@aws-sdk/signature-v4-multi-region": ["@aws-sdk/signature-v4-multi-region@3.996.16", "", { "dependencies": { "@aws-sdk/middleware-sdk-s3": "^3.972.28", "@aws-sdk/types": "^3.973.7", "@smithy/protocol-http": "^5.3.13", "@smithy/signature-v4": "^5.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-EMdXYB4r/k5RWq86fugjRhid5JA+Z6MpS7n4sij4u5/C+STrkvuf9aFu41rJA9MjUzxCLzv8U2XL8cH2GSRYpQ=="],
|
||||
|
||||
"@aws-sdk/token-providers": ["@aws-sdk/token-providers@3.1026.0", "", { "dependencies": { "@aws-sdk/core": "^3.973.27", "@aws-sdk/nested-clients": "^3.996.19", "@aws-sdk/types": "^3.973.7", "@smithy/property-provider": "^4.2.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-Ieq/HiRrbEtrYP387Nes0XlR7H1pJiJOZKv+QyQzMYpvTiDs0VKy2ZB3E2Zf+aFovWmeE7lRE4lXyF7dYM6GgA=="],
|
||||
|
||||
"@aws-sdk/types": ["@aws-sdk/types@3.973.7", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-reXRwoJ6CfChoqAsBszUYajAF8Z2LRE+CRcKocvFSMpIiLOtYU3aJ9trmn6VVPAzbbY5LXF+FfmUslbXk1SYFg=="],
|
||||
|
||||
"@aws-sdk/util-arn-parser": ["@aws-sdk/util-arn-parser@3.972.3", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-HzSD8PMFrvgi2Kserxuff5VitNq2sgf3w9qxmskKDiDTThWfVteJxuCS9JXiPIPtmCrp+7N9asfIaVhBFORllA=="],
|
||||
|
||||
"@aws-sdk/util-endpoints": ["@aws-sdk/util-endpoints@3.996.6", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/types": "^4.14.0", "@smithy/url-parser": "^4.2.13", "@smithy/util-endpoints": "^3.3.4", "tslib": "^2.6.2" } }, "sha512-2nUQ+2ih7CShuKHpGSIYvvAIOHy52dOZguYG36zptBukhw6iFwcvGfG0tes0oZFWQqEWvgZe9HLWaNlvXGdOrg=="],
|
||||
|
||||
"@aws-sdk/util-locate-window": ["@aws-sdk/util-locate-window@3.965.5", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-WhlJNNINQB+9qtLtZJcpQdgZw3SCDCpXdUJP7cToGwHbCWCnRckGlc6Bx/OhWwIYFNAn+FIydY8SZ0QmVu3xTQ=="],
|
||||
|
||||
"@aws-sdk/util-user-agent-browser": ["@aws-sdk/util-user-agent-browser@3.972.9", "", { "dependencies": { "@aws-sdk/types": "^3.973.7", "@smithy/types": "^4.14.0", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-sn/LMzTbGjYqCCF24390WxPd6hkpoSptiUn5DzVp4cD71yqw+yGEGm1YCxyEoPXyc8qciM8UzLJcZBFslxo5Uw=="],
|
||||
|
||||
"@aws-sdk/util-user-agent-node": ["@aws-sdk/util-user-agent-node@3.973.15", "", { "dependencies": { "@aws-sdk/middleware-user-agent": "^3.972.29", "@aws-sdk/types": "^3.973.7", "@smithy/node-config-provider": "^4.3.13", "@smithy/types": "^4.14.0", "@smithy/util-config-provider": "^4.2.2", "tslib": "^2.6.2" }, "peerDependencies": { "aws-crt": ">=1.0.0" }, "optionalPeers": ["aws-crt"] }, "sha512-fYn3s9PtKdgQkczGZCFMgkNEe8aq1JCVbnRqjqN9RSVW43xn2RV9xdcZ3z01a48Jpkuh/xCmBKJxdLOo4Ozg7w=="],
|
||||
|
||||
"@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.17", "", { "dependencies": { "@smithy/types": "^4.14.0", "fast-xml-parser": "5.5.8", "tslib": "^2.6.2" } }, "sha512-Ra7hjqAZf1OXRRMueB13qex7mFJRDK/pgCvdSFemXBT8KCGnQDPoKzHY1SjN+TjJVmnpSF14W5tJ1vDamFu+Gg=="],
|
||||
|
||||
"@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.2.4", "", {}, "sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ=="],
|
||||
|
||||
"@electric-sql/pglite": ["@electric-sql/pglite@0.4.4", "", {}, "sha512-g/6CWAJ4XOkObWCWAQ2IReZD8VvsDy3poRHSKvpRR2F96F8WJ3HVbjpso3gN7l0q6QPPgvxSSpl/qo5k8a7mkQ=="],
|
||||
|
||||
"@hono/node-server": ["@hono/node-server@1.19.12", "", { "peerDependencies": { "hono": "^4" } }, "sha512-txsUW4SQ1iilgE0l9/e9VQWmELXifEFvmdA1j6WFh/aFPj99hIntrSsq/if0UWyGVkmrRPKA1wCeP+UCr1B9Uw=="],
|
||||
|
||||
"@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.29.0", "", { "dependencies": { "@hono/node-server": "^1.19.9", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.2.1", "express-rate-limit": "^8.2.1", "hono": "^4.11.4", "jose": "^6.1.3", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ=="],
|
||||
|
||||
"@smithy/chunked-blob-reader": ["@smithy/chunked-blob-reader@5.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-St+kVicSyayWQca+I1rGitaOEH6uKgE8IUWoYnnEX26SWdWQcL6LvMSD19Lg+vYHKdT9B2Zuu7rd3i6Wnyb/iw=="],
|
||||
|
||||
"@smithy/chunked-blob-reader-native": ["@smithy/chunked-blob-reader-native@4.2.3", "", { "dependencies": { "@smithy/util-base64": "^4.3.2", "tslib": "^2.6.2" } }, "sha512-jA5k5Udn7Y5717L86h4EIv06wIr3xn8GM1qHRi/Nf31annXcXHJjBKvgztnbn2TxH3xWrPBfgwHsOwZf0UmQWw=="],
|
||||
|
||||
"@smithy/config-resolver": ["@smithy/config-resolver@4.4.14", "", { "dependencies": { "@smithy/node-config-provider": "^4.3.13", "@smithy/types": "^4.14.0", "@smithy/util-config-provider": "^4.2.2", "@smithy/util-endpoints": "^3.3.4", "@smithy/util-middleware": "^4.2.13", "tslib": "^2.6.2" } }, "sha512-N55f8mPEccpzKetUagdvmAy8oohf0J5cuj9jLI1TaSceRlq0pJsIZepY3kmAXAhyxqXPV6hDerDQhqQPKWgAoQ=="],
|
||||
|
||||
"@smithy/core": ["@smithy/core@3.23.14", "", { "dependencies": { "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "@smithy/url-parser": "^4.2.13", "@smithy/util-base64": "^4.3.2", "@smithy/util-body-length-browser": "^4.2.2", "@smithy/util-middleware": "^4.2.13", "@smithy/util-stream": "^4.5.22", "@smithy/util-utf8": "^4.2.2", "@smithy/uuid": "^1.1.2", "tslib": "^2.6.2" } }, "sha512-vJ0IhpZxZAkFYOegMKSrxw7ujhhT2pass/1UEcZ4kfl5srTAqtPU5I7MdYQoreVas3204ykCiNhY1o7Xlz6Yyg=="],
|
||||
|
||||
"@smithy/credential-provider-imds": ["@smithy/credential-provider-imds@4.2.13", "", { "dependencies": { "@smithy/node-config-provider": "^4.3.13", "@smithy/property-provider": "^4.2.13", "@smithy/types": "^4.14.0", "@smithy/url-parser": "^4.2.13", "tslib": "^2.6.2" } }, "sha512-wboCPijzf6RJKLOvnjDAiBxGSmSnGXj35o5ZAWKDaHa/cvQ5U3ZJ13D4tMCE8JG4dxVAZFy/P0x/V9CwwdfULQ=="],
|
||||
|
||||
"@smithy/eventstream-codec": ["@smithy/eventstream-codec@4.2.13", "", { "dependencies": { "@aws-crypto/crc32": "5.2.0", "@smithy/types": "^4.14.0", "@smithy/util-hex-encoding": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-vYahwBAtRaAcFbOmE9aLr12z7RiHYDSLcnogSdxfm7kKfsNa3wH+NU5r7vTeB5rKvLsWyPjVX8iH94brP7umiQ=="],
|
||||
|
||||
"@smithy/eventstream-serde-browser": ["@smithy/eventstream-serde-browser@4.2.13", "", { "dependencies": { "@smithy/eventstream-serde-universal": "^4.2.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-wwybfcOX0tLqCcBP378TIU9IqrDuZq/tDV48LlZNydMpCnqnYr+hWBAYbRE+rFFf/p7IkDJySM3bgiMKP2ihPg=="],
|
||||
|
||||
"@smithy/eventstream-serde-config-resolver": ["@smithy/eventstream-serde-config-resolver@4.3.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-ied1lO559PtAsMJzg2TKRlctLnEi1PfkNeMMpdwXDImk1zV9uvS/Oxoy/vcy9uv1GKZAjDAB5xT6ziE9fzm5wA=="],
|
||||
|
||||
"@smithy/eventstream-serde-node": ["@smithy/eventstream-serde-node@4.2.13", "", { "dependencies": { "@smithy/eventstream-serde-universal": "^4.2.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-hFyK+ORJrxAN3RYoaD6+gsGDQjeix8HOEkosoajvXYZ4VeqonM3G4jd9IIRm/sWGXUKmudkY9KdYjzosUqdM8A=="],
|
||||
|
||||
"@smithy/eventstream-serde-universal": ["@smithy/eventstream-serde-universal@4.2.13", "", { "dependencies": { "@smithy/eventstream-codec": "^4.2.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-kRrq4EKLGeOxhC2CBEhRNcu1KSzNJzYY7RK3S7CxMPgB5dRrv55WqQOtRwQxQLC04xqORFLUgnDlc6xrNUULaA=="],
|
||||
|
||||
"@smithy/fetch-http-handler": ["@smithy/fetch-http-handler@5.3.16", "", { "dependencies": { "@smithy/protocol-http": "^5.3.13", "@smithy/querystring-builder": "^4.2.13", "@smithy/types": "^4.14.0", "@smithy/util-base64": "^4.3.2", "tslib": "^2.6.2" } }, "sha512-nYDRUIvNd4mFmuXraRWt6w5UsZTNqtj4hXJA/iiOD4tuseIdLP9Lq38teH/SZTcIFCa2f+27o7hYpIsWktJKEQ=="],
|
||||
|
||||
"@smithy/hash-blob-browser": ["@smithy/hash-blob-browser@4.2.14", "", { "dependencies": { "@smithy/chunked-blob-reader": "^5.2.2", "@smithy/chunked-blob-reader-native": "^4.2.3", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-rtQ5es8r/5v4rav7q5QTsfx9CtCyzrz/g7ZZZBH2xtMmd6G/KQrLOWfSHTvFOUPlVy59RQvxeBYJaLRoybMEyA=="],
|
||||
|
||||
"@smithy/hash-node": ["@smithy/hash-node@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "@smithy/util-buffer-from": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-4/oy9h0jjmY80a2gOIo75iLl8TOPhmtx4E2Hz+PfMjvx/vLtGY4TMU/35WRyH2JHPfT5CVB38u4JRow7gnmzJA=="],
|
||||
|
||||
"@smithy/hash-stream-node": ["@smithy/hash-stream-node@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-WdQ7HwUjINXETeh6dqUeob1UHIYx8kAn9PSp1HhM2WWegiZBYVy2WXIs1lB07SZLan/udys9SBnQGt9MQbDpdg=="],
|
||||
|
||||
"@smithy/invalid-dependency": ["@smithy/invalid-dependency@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-jvC0RB/8BLj2SMIkY0Npl425IdnxZJxInpZJbu563zIRnVjpDMXevU3VMCRSabaLB0kf/eFIOusdGstrLJ8IDg=="],
|
||||
|
||||
"@smithy/is-array-buffer": ["@smithy/is-array-buffer@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-n6rQ4N8Jj4YTQO3YFrlgZuwKodf4zUFs7EJIWH86pSCWBaAtAGBFfCM7Wx6D2bBJ2xqFNxGBSrUWswT3M0VJow=="],
|
||||
|
||||
"@smithy/md5-js": ["@smithy/md5-js@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-cNm7I9NXolFxtS20ojROddOEpSAeI1Obq6pd1Kj5HtHws3s9Fkk8DdHDfQSs5KuxCewZuVK6UqrJnfJmiMzDuQ=="],
|
||||
|
||||
"@smithy/middleware-content-length": ["@smithy/middleware-content-length@4.2.13", "", { "dependencies": { "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-IPMLm/LE4AZwu6qiE8Rr8vJsWhs9AtOdySRXrOM7xnvclp77Tyh7hMs/FRrMf26kgIe67vFJXXOSmVxS7oKeig=="],
|
||||
|
||||
"@smithy/middleware-endpoint": ["@smithy/middleware-endpoint@4.4.29", "", { "dependencies": { "@smithy/core": "^3.23.14", "@smithy/middleware-serde": "^4.2.17", "@smithy/node-config-provider": "^4.3.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "@smithy/url-parser": "^4.2.13", "@smithy/util-middleware": "^4.2.13", "tslib": "^2.6.2" } }, "sha512-R9Q/58U+qBiSARGWbAbFLczECg/RmysRksX6Q8BaQEpt75I7LI6WGDZnjuC9GXSGKljEbA7N118LhGaMbfrTXw=="],
|
||||
|
||||
"@smithy/middleware-retry": ["@smithy/middleware-retry@4.5.1", "", { "dependencies": { "@smithy/core": "^3.23.14", "@smithy/node-config-provider": "^4.3.13", "@smithy/protocol-http": "^5.3.13", "@smithy/service-error-classification": "^4.2.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "@smithy/util-middleware": "^4.2.13", "@smithy/util-retry": "^4.3.1", "@smithy/uuid": "^1.1.2", "tslib": "^2.6.2" } }, "sha512-/zY+Gp7Qj2D2hVm3irkCyONER7E9MiX3cUUm/k2ZmhkzZkrPgwVS4aJ5NriZUEN/M0D1hhjrgjUmX04HhRwdWA=="],
|
||||
|
||||
"@smithy/middleware-serde": ["@smithy/middleware-serde@4.2.17", "", { "dependencies": { "@smithy/core": "^3.23.14", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-0T2mcaM6v9W1xku86Dk0bEW7aEseG6KenFkPK98XNw0ZhOqOiD1MrMsdnQw9QsL3/Oa85T53iSMlm0SZdSuIEQ=="],
|
||||
|
||||
"@smithy/middleware-stack": ["@smithy/middleware-stack@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-g72jN/sGDLyTanrCLH9fhg3oysO3f7tQa6eWWsMyn2BiYNCgjF24n4/I9wff/5XidFvjj9ilipAoQrurTUrLvw=="],
|
||||
|
||||
"@smithy/node-config-provider": ["@smithy/node-config-provider@4.3.13", "", { "dependencies": { "@smithy/property-provider": "^4.2.13", "@smithy/shared-ini-file-loader": "^4.4.8", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-iGxQ04DsKXLckbgnX4ipElrOTk+IHgTyu0q0WssZfYhDm9CQWHmu6cOeI5wmWRxpXbBDhIIfXMWz5tPEtcVqbw=="],
|
||||
|
||||
"@smithy/node-http-handler": ["@smithy/node-http-handler@4.5.2", "", { "dependencies": { "@smithy/protocol-http": "^5.3.13", "@smithy/querystring-builder": "^4.2.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-/oD7u8M0oj2ZTFw7GkuuHWpIxtWdLlnyNkbrWcyVYhd5RJNDuczdkb0wfnQICyNFrVPlr8YHOhamjNy3zidhmA=="],
|
||||
|
||||
"@smithy/property-provider": ["@smithy/property-provider@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-bGzUCthxRmezuxkbu9wD33wWg9KX3hJpCXpQ93vVkPrHn9ZW6KNNdY5xAUWNuRCwQ+VyboFuWirG1lZhhkcyRQ=="],
|
||||
|
||||
"@smithy/protocol-http": ["@smithy/protocol-http@5.3.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-+HsmuJUF4u8POo6s8/a2Yb/AQ5t/YgLovCuHF9oxbocqv+SZ6gd8lC2duBFiCA/vFHoHQhoq7QjqJqZC6xOxxg=="],
|
||||
|
||||
"@smithy/querystring-builder": ["@smithy/querystring-builder@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "@smithy/util-uri-escape": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-tG4aOYFCZdPMjbgfhnIQ322H//ojujldp1SrHPHpBSb3NqgUp3dwiUGRJzie87hS1DYwWGqDuPaowoDF+rYCbQ=="],
|
||||
|
||||
"@smithy/querystring-parser": ["@smithy/querystring-parser@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-hqW3Q4P+CDzUyQ87GrboGMeD7XYNMOF+CuTwu936UQRB/zeYn3jys8C3w+wMkDfY7CyyyVwZQ5cNFoG0x1pYmA=="],
|
||||
|
||||
"@smithy/service-error-classification": ["@smithy/service-error-classification@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0" } }, "sha512-a0s8XZMfOC/qpqq7RCPvJlk93rWFrElH6O++8WJKz0FqnA4Y7fkNi/0mnGgSH1C4x6MFsuBA8VKu4zxFrMe5Vw=="],
|
||||
|
||||
"@smithy/shared-ini-file-loader": ["@smithy/shared-ini-file-loader@4.4.8", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-VZCZx2bZasxdqxVgEAhREvDSlkatTPnkdWy1+Kiy8w7kYPBosW0V5IeDwzDUMvWBt56zpK658rx1cOBFOYaPaw=="],
|
||||
|
||||
"@smithy/signature-v4": ["@smithy/signature-v4@5.3.13", "", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "@smithy/util-hex-encoding": "^4.2.2", "@smithy/util-middleware": "^4.2.13", "@smithy/util-uri-escape": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-YpYSyM0vMDwKbHD/JA7bVOF6kToVRpa+FM5ateEVRpsTNu564g1muBlkTubXhSKKYXInhpADF46FPyrZcTLpXg=="],
|
||||
|
||||
"@smithy/smithy-client": ["@smithy/smithy-client@4.12.9", "", { "dependencies": { "@smithy/core": "^3.23.14", "@smithy/middleware-endpoint": "^4.4.29", "@smithy/middleware-stack": "^4.2.13", "@smithy/protocol-http": "^5.3.13", "@smithy/types": "^4.14.0", "@smithy/util-stream": "^4.5.22", "tslib": "^2.6.2" } }, "sha512-ovaLEcTU5olSeHcRXcxV6viaKtpkHZumn6Ps0yn7dRf2rRSfy794vpjOtrWDO0d1auDSvAqxO+lyhERSXQ03EQ=="],
|
||||
|
||||
"@smithy/types": ["@smithy/types@4.14.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-OWgntFLW88kx2qvf/c/67Vno1yuXm/f9M7QFAtVkkO29IJXGBIg0ycEaBTH0kvCtwmvZxRujrgP5a86RvsXJAQ=="],
|
||||
|
||||
"@smithy/url-parser": ["@smithy/url-parser@4.2.13", "", { "dependencies": { "@smithy/querystring-parser": "^4.2.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-2G03yoboIRZlZze2+PT4GZEjgwQsJjUgn6iTsvxA02bVceHR6vp4Cuk7TUnPFWKF+ffNUk3kj4COwkENS2K3vw=="],
|
||||
|
||||
"@smithy/util-base64": ["@smithy/util-base64@4.3.2", "", { "dependencies": { "@smithy/util-buffer-from": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-XRH6b0H/5A3SgblmMa5ErXQ2XKhfbQB+Fm/oyLZ2O2kCUrwgg55bU0RekmzAhuwOjA9qdN5VU2BprOvGGUkOOQ=="],
|
||||
|
||||
"@smithy/util-body-length-browser": ["@smithy/util-body-length-browser@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-JKCrLNOup3OOgmzeaKQwi4ZCTWlYR5H4Gm1r2uTMVBXoemo1UEghk5vtMi1xSu2ymgKVGW631e2fp9/R610ZjQ=="],
|
||||
|
||||
"@smithy/util-body-length-node": ["@smithy/util-body-length-node@4.2.3", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-ZkJGvqBzMHVHE7r/hcuCxlTY8pQr1kMtdsVPs7ex4mMU+EAbcXppfo5NmyxMYi2XU49eqaz56j2gsk4dHHPG/g=="],
|
||||
|
||||
"@smithy/util-buffer-from": ["@smithy/util-buffer-from@4.2.2", "", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q=="],
|
||||
|
||||
"@smithy/util-config-provider": ["@smithy/util-config-provider@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-dWU03V3XUprJwaUIFVv4iOnS1FC9HnMHDfUrlNDSh4315v0cWyaIErP8KiqGVbf5z+JupoVpNM7ZB3jFiTejvQ=="],
|
||||
|
||||
"@smithy/util-defaults-mode-browser": ["@smithy/util-defaults-mode-browser@4.3.45", "", { "dependencies": { "@smithy/property-provider": "^4.2.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-ag9sWc6/nWZAuK3Wm9KlFJUnRkXLrXn33RFjIAmCTFThqLHY+7wCst10BGq56FxslsDrjhSie46c8OULS+BiIw=="],
|
||||
|
||||
"@smithy/util-defaults-mode-node": ["@smithy/util-defaults-mode-node@4.2.49", "", { "dependencies": { "@smithy/config-resolver": "^4.4.14", "@smithy/credential-provider-imds": "^4.2.13", "@smithy/node-config-provider": "^4.3.13", "@smithy/property-provider": "^4.2.13", "@smithy/smithy-client": "^4.12.9", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-jlN6vHwE8gY5AfiFBavtD3QtCX2f7lM3BKkz7nFKSNfFR5nXLXLg6sqXTJEEyDwtxbztIDBQCfjsGVXlIru2lQ=="],
|
||||
|
||||
"@smithy/util-endpoints": ["@smithy/util-endpoints@3.3.4", "", { "dependencies": { "@smithy/node-config-provider": "^4.3.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-BKoR/ubPp9KNKFxPpg1J28N1+bgu8NGAtJblBP7yHy8yQPBWhIAv9+l92SlQLpolGm71CVO+btB60gTgzT0wog=="],
|
||||
|
||||
"@smithy/util-hex-encoding": ["@smithy/util-hex-encoding@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-Qcz3W5vuHK4sLQdyT93k/rfrUwdJ8/HZ+nMUOyGdpeGA1Wxt65zYwi3oEl9kOM+RswvYq90fzkNDahPS8K0OIg=="],
|
||||
|
||||
"@smithy/util-middleware": ["@smithy/util-middleware@4.2.13", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-GTooyrlmRTqvUen4eK7/K1p6kryF7bnDfq6XsAbIsf2mo51B/utaH+XThY6dKgNCWzMAaH/+OLmqaBuLhLWRow=="],
|
||||
|
||||
"@smithy/util-retry": ["@smithy/util-retry@4.3.1", "", { "dependencies": { "@smithy/service-error-classification": "^4.2.13", "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-FwmicpgWOkP5kZUjN3y+3JIom8NLGqSAJBeoIgK0rIToI817TEBHCrd0A2qGeKQlgDeP+Jzn4i0H/NLAXGy9uQ=="],
|
||||
|
||||
"@smithy/util-stream": ["@smithy/util-stream@4.5.22", "", { "dependencies": { "@smithy/fetch-http-handler": "^5.3.16", "@smithy/node-http-handler": "^4.5.2", "@smithy/types": "^4.14.0", "@smithy/util-base64": "^4.3.2", "@smithy/util-buffer-from": "^4.2.2", "@smithy/util-hex-encoding": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-3H8iq/0BfQjUs2/4fbHZ9aG9yNzcuZs24LPkcX1Q7Z+qpqaGM8+qbGmE8zo9m2nCRgamyvS98cHdcWvR6YUsew=="],
|
||||
|
||||
"@smithy/util-uri-escape": ["@smithy/util-uri-escape@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-2kAStBlvq+lTXHyAZYfJRb/DfS3rsinLiwb+69SstC9Vb0s9vNWkRwpnj918Pfi85mzi42sOqdV72OLxWAISnw=="],
|
||||
|
||||
"@smithy/util-utf8": ["@smithy/util-utf8@4.2.2", "", { "dependencies": { "@smithy/util-buffer-from": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-75MeYpjdWRe8M5E3AW0O4Cx3UadweS+cwdXjwYGBW5h/gxxnbeZ877sLPX/ZJA9GVTlL/qG0dXP29JWFCD1Ayw=="],
|
||||
|
||||
"@smithy/util-waiter": ["@smithy/util-waiter@4.2.15", "", { "dependencies": { "@smithy/types": "^4.14.0", "tslib": "^2.6.2" } }, "sha512-oUt9o7n8hBv3BL56sLSneL0XeigZSuem0Hr78JaoK33D9oKieyCvVP8eTSe3j7g2mm/S1DvzxKieG7JEWNJUNg=="],
|
||||
|
||||
"@smithy/uuid": ["@smithy/uuid@1.1.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-O/IEdcCUKkubz60tFbGA7ceITTAJsty+lBjNoorP4Z6XRqaFb/OjQjZODophEcuq68nKm6/0r+6/lLQ+XVpk8g=="],
|
||||
|
||||
"@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
|
||||
|
||||
"@types/node": ["@types/node@18.19.130", "", { "dependencies": { "undici-types": "~5.26.4" } }, "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg=="],
|
||||
|
||||
"@types/node-fetch": ["@types/node-fetch@2.6.13", "", { "dependencies": { "@types/node": "*", "form-data": "^4.0.4" } }, "sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw=="],
|
||||
|
||||
"abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="],
|
||||
|
||||
"accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
|
||||
|
||||
"agentkeepalive": ["agentkeepalive@4.6.0", "", { "dependencies": { "humanize-ms": "^1.2.1" } }, "sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ=="],
|
||||
|
||||
"ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
|
||||
|
||||
"ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
|
||||
|
||||
"argparse": ["argparse@1.0.10", "", { "dependencies": { "sprintf-js": "~1.0.2" } }, "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg=="],
|
||||
|
||||
"asynckit": ["asynckit@0.4.0", "", {}, "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q=="],
|
||||
|
||||
"body-parser": ["body-parser@2.2.2", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.1", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA=="],
|
||||
|
||||
"bowser": ["bowser@2.14.1", "", {}, "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg=="],
|
||||
|
||||
"bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
|
||||
|
||||
"bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
|
||||
|
||||
"call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
|
||||
|
||||
"call-bound": ["call-bound@1.0.4", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "get-intrinsic": "^1.3.0" } }, "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg=="],
|
||||
|
||||
"combined-stream": ["combined-stream@1.0.8", "", { "dependencies": { "delayed-stream": "~1.0.0" } }, "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg=="],
|
||||
|
||||
"content-disposition": ["content-disposition@1.0.1", "", {}, "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q=="],
|
||||
|
||||
"content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
|
||||
|
||||
"cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
|
||||
|
||||
"cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
|
||||
|
||||
"cors": ["cors@2.8.6", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw=="],
|
||||
|
||||
"cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
|
||||
|
||||
"debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
|
||||
|
||||
"delayed-stream": ["delayed-stream@1.0.0", "", {}, "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ=="],
|
||||
|
||||
"depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
|
||||
|
||||
"dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
|
||||
|
||||
"ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
|
||||
|
||||
"encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
|
||||
|
||||
"es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
|
||||
|
||||
"es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
|
||||
|
||||
"es-object-atoms": ["es-object-atoms@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA=="],
|
||||
|
||||
"es-set-tostringtag": ["es-set-tostringtag@2.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "get-intrinsic": "^1.2.6", "has-tostringtag": "^1.0.2", "hasown": "^2.0.2" } }, "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA=="],
|
||||
|
||||
"escape-html": ["escape-html@1.0.3", "", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
|
||||
|
||||
"esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
|
||||
|
||||
"etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
|
||||
|
||||
"event-target-shim": ["event-target-shim@5.0.1", "", {}, "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ=="],
|
||||
|
||||
"eventsource": ["eventsource@3.0.7", "", { "dependencies": { "eventsource-parser": "^3.0.1" } }, "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA=="],
|
||||
|
||||
"eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
|
||||
|
||||
"express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
|
||||
|
||||
"express-rate-limit": ["express-rate-limit@8.3.2", "", { "dependencies": { "ip-address": "10.1.0" }, "peerDependencies": { "express": ">= 4.11" } }, "sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg=="],
|
||||
|
||||
"extend-shallow": ["extend-shallow@2.0.1", "", { "dependencies": { "is-extendable": "^0.1.0" } }, "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug=="],
|
||||
|
||||
"fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
|
||||
|
||||
"fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
|
||||
|
||||
"fast-xml-builder": ["fast-xml-builder@1.1.4", "", { "dependencies": { "path-expression-matcher": "^1.1.3" } }, "sha512-f2jhpN4Eccy0/Uz9csxh3Nu6q4ErKxf0XIsasomfOihuSUa3/xw6w8dnOtCDgEItQFJG8KyXPzQXzcODDrrbOg=="],
|
||||
|
||||
"fast-xml-parser": ["fast-xml-parser@5.5.8", "", { "dependencies": { "fast-xml-builder": "^1.1.4", "path-expression-matcher": "^1.2.0", "strnum": "^2.2.0" }, "bin": { "fxparser": "src/cli/cli.js" } }, "sha512-Z7Fh2nVQSb2d+poDViM063ix2ZGt9jmY1nWhPfHBOK2Hgnb/OW3P4Et3P/81SEej0J7QbWtJqxO05h8QYfK7LQ=="],
|
||||
|
||||
"finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
|
||||
|
||||
"form-data": ["form-data@4.0.5", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", "hasown": "^2.0.2", "mime-types": "^2.1.12" } }, "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w=="],
|
||||
|
||||
"form-data-encoder": ["form-data-encoder@1.7.2", "", {}, "sha512-qfqtYan3rxrnCk1VYaA4H+Ms9xdpPqvLZa6xmMgFvhO32x7/3J/ExcTd6qpxM0vH2GdMI+poehyBZvqfMTto8A=="],
|
||||
|
||||
"formdata-node": ["formdata-node@4.4.1", "", { "dependencies": { "node-domexception": "1.0.0", "web-streams-polyfill": "4.0.0-beta.3" } }, "sha512-0iirZp3uVDjVGt9p49aTaqjk84TrglENEDuqfdlZQ1roC9CWlPk6Avf8EEnZNcAqPonwkG35x4n3ww/1THYAeQ=="],
|
||||
|
||||
"forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
|
||||
|
||||
"fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
|
||||
|
||||
"function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
|
||||
|
||||
"get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
|
||||
|
||||
"get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
|
||||
|
||||
"gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
|
||||
|
||||
"gray-matter": ["gray-matter@4.0.3", "", { "dependencies": { "js-yaml": "^3.13.1", "kind-of": "^6.0.2", "section-matter": "^1.0.0", "strip-bom-string": "^1.0.0" } }, "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q=="],
|
||||
|
||||
"has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
|
||||
|
||||
"has-tostringtag": ["has-tostringtag@1.0.2", "", { "dependencies": { "has-symbols": "^1.0.3" } }, "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw=="],
|
||||
|
||||
"hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
|
||||
|
||||
"hono": ["hono@4.12.10", "", {}, "sha512-mx/p18PLy5og9ufies2GOSUqep98Td9q4i/EF6X7yJgAiIopxqdfIO3jbqsi3jRgTgw88jMDEzVKi+V2EF+27w=="],
|
||||
|
||||
"http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
|
||||
|
||||
"humanize-ms": ["humanize-ms@1.2.1", "", { "dependencies": { "ms": "^2.0.0" } }, "sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ=="],
|
||||
|
||||
"iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
|
||||
|
||||
"inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
|
||||
|
||||
"ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="],
|
||||
|
||||
"ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
|
||||
|
||||
"is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="],
|
||||
|
||||
"is-promise": ["is-promise@4.0.0", "", {}, "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ=="],
|
||||
|
||||
"isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
|
||||
|
||||
"jose": ["jose@6.2.2", "", {}, "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ=="],
|
||||
|
||||
"js-yaml": ["js-yaml@3.14.2", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg=="],
|
||||
|
||||
"json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
|
||||
|
||||
"json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
|
||||
|
||||
"kind-of": ["kind-of@6.0.3", "", {}, "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw=="],
|
||||
|
||||
"marked": ["marked@18.0.0", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-2e7Qiv/HJSXj8rDEpgTvGKsP8yYtI9xXHKDnrftrmnrJPaFNM7VRb2YCzWaX4BP1iCJ/XPduzDJZMFoqTCcIMA=="],
|
||||
|
||||
"math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
|
||||
|
||||
"media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
|
||||
|
||||
"merge-descriptors": ["merge-descriptors@2.0.0", "", {}, "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g=="],
|
||||
|
||||
"mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
|
||||
|
||||
"mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
|
||||
|
||||
"ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
|
||||
|
||||
"negotiator": ["negotiator@1.0.0", "", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
|
||||
|
||||
"node-domexception": ["node-domexception@1.0.0", "", {}, "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ=="],
|
||||
|
||||
"node-fetch": ["node-fetch@2.7.0", "", { "dependencies": { "whatwg-url": "^5.0.0" }, "peerDependencies": { "encoding": "^0.1.0" }, "optionalPeers": ["encoding"] }, "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A=="],
|
||||
|
||||
"object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
|
||||
|
||||
"object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
|
||||
|
||||
"on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
|
||||
|
||||
"once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
|
||||
|
||||
"openai": ["openai@4.104.0", "", { "dependencies": { "@types/node": "^18.11.18", "@types/node-fetch": "^2.6.4", "abort-controller": "^3.0.0", "agentkeepalive": "^4.2.1", "form-data-encoder": "1.7.2", "formdata-node": "^4.3.2", "node-fetch": "^2.6.7" }, "peerDependencies": { "ws": "^8.18.0", "zod": "^3.23.8" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-p99EFNsA/yX6UhVO93f5kJsDRLAg+CTA2RBqdHK4RtK8u5IJw32Hyb2dTGKbnnFmnuoBv5r7Z2CURI9sGZpSuA=="],
|
||||
|
||||
"parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
|
||||
|
||||
"path-expression-matcher": ["path-expression-matcher@1.5.0", "", {}, "sha512-cbrerZV+6rvdQrrD+iGMcZFEiiSrbv9Tfdkvnusy6y0x0GKBXREFg/Y65GhIfm0tnLntThhzCnfKwp1WRjeCyQ=="],
|
||||
|
||||
"path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
|
||||
|
||||
"path-to-regexp": ["path-to-regexp@8.4.2", "", {}, "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA=="],
|
||||
|
||||
"pgvector": ["pgvector@0.2.1", "", {}, "sha512-nKaQY9wtuiidwLMdVIce1O3kL0d+FxrigCVzsShnoqzOSaWWWOvuctb/sYwlai5cTwwzRSNa+a/NtN2kVZGNJw=="],
|
||||
|
||||
"pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="],
|
||||
|
||||
"postgres": ["postgres@3.4.9", "", {}, "sha512-GD3qdB0x1z9xgFI6cdRD6xu2Sp2WCOEoe3mtnyB5Ee0XrrL5Pe+e4CCnJrRMnL1zYtRDZmQQVbvOttLnKDLnaw=="],
|
||||
|
||||
"proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
|
||||
|
||||
"qs": ["qs@6.15.0", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ=="],
|
||||
|
||||
"range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
|
||||
|
||||
"raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
|
||||
|
||||
"require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
|
||||
|
||||
"router": ["router@2.2.0", "", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
|
||||
|
||||
"safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
|
||||
|
||||
"section-matter": ["section-matter@1.0.0", "", { "dependencies": { "extend-shallow": "^2.0.1", "kind-of": "^6.0.0" } }, "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA=="],
|
||||
|
||||
"send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
|
||||
|
||||
"serve-static": ["serve-static@2.2.1", "", { "dependencies": { "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "parseurl": "^1.3.3", "send": "^1.2.0" } }, "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw=="],
|
||||
|
||||
"setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
|
||||
|
||||
"shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
|
||||
|
||||
"shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
|
||||
|
||||
"side-channel": ["side-channel@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3", "side-channel-list": "^1.0.0", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw=="],
|
||||
|
||||
"side-channel-list": ["side-channel-list@1.0.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3" } }, "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA=="],
|
||||
|
||||
"side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
|
||||
|
||||
"side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
|
||||
|
||||
"sprintf-js": ["sprintf-js@1.0.3", "", {}, "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g=="],
|
||||
|
||||
"statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
|
||||
|
||||
"strip-bom-string": ["strip-bom-string@1.0.0", "", {}, "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g=="],
|
||||
|
||||
"strnum": ["strnum@2.2.3", "", {}, "sha512-oKx6RUCuHfT3oyVjtnrmn19H1SiCqgJSg+54XqURKp5aCMbrXrhLjRN9TjuwMjiYstZ0MzDrHqkGZ5dFTKd+zg=="],
|
||||
|
||||
"toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
|
||||
|
||||
"tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
|
||||
|
||||
"tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
|
||||
|
||||
"type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
|
||||
|
||||
"undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
|
||||
|
||||
"unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
|
||||
|
||||
"vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
|
||||
|
||||
"web-streams-polyfill": ["web-streams-polyfill@4.0.0-beta.3", "", {}, "sha512-QW95TCTaHmsYfHDybGMwO5IJIM93I/6vTRk+daHTWFPhwh+C8Cg7j7XyKrwrj8Ib6vYXe0ocYNrmzY4xAAN6ug=="],
|
||||
|
||||
"webidl-conversions": ["webidl-conversions@3.0.1", "", {}, "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="],
|
||||
|
||||
"whatwg-url": ["whatwg-url@5.0.0", "", { "dependencies": { "tr46": "~0.0.3", "webidl-conversions": "^3.0.0" } }, "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw=="],
|
||||
|
||||
"which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
|
||||
|
||||
"wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
|
||||
|
||||
"zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
|
||||
|
||||
"zod-to-json-schema": ["zod-to-json-schema@3.25.2", "", { "peerDependencies": { "zod": "^3.25.28 || ^4" } }, "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA=="],
|
||||
|
||||
"@aws-crypto/sha1-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
|
||||
|
||||
"@aws-crypto/sha256-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
|
||||
|
||||
"@aws-crypto/util/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
|
||||
|
||||
"@types/node-fetch/@types/node": ["@types/node@25.5.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
|
||||
|
||||
"bun-types/@types/node": ["@types/node@25.5.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
|
||||
|
||||
"form-data/mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
|
||||
|
||||
"@aws-crypto/sha1-browser/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
|
||||
|
||||
"@aws-crypto/sha256-browser/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
|
||||
|
||||
"@aws-crypto/util/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
|
||||
|
||||
"@types/node-fetch/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
|
||||
|
||||
"bun-types/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
|
||||
|
||||
"form-data/mime-types/mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
|
||||
|
||||
"@aws-crypto/sha1-browser/@smithy/util-utf8/@smithy/util-buffer-from/@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],
|
||||
|
||||
"@aws-crypto/sha256-browser/@smithy/util-utf8/@smithy/util-buffer-from/@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],
|
||||
|
||||
"@aws-crypto/util/@smithy/util-utf8/@smithy/util-buffer-from/@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],
|
||||
}
|
||||
}
|
||||
@@ -1,14 +0,0 @@
|
||||
services:
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg16
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
POSTGRES_DB: gbrain_test
|
||||
ports:
|
||||
- "5434:5432"
|
||||
healthcheck:
|
||||
test: pg_isready -U postgres
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 5
|
||||
-234
@@ -1,234 +0,0 @@
|
||||
# Pluggable Engine Architecture
|
||||
|
||||
## The idea
|
||||
|
||||
Every GBrain operation goes through `BrainEngine`. The engine is the contract between "what the brain can do" and "how it's stored." Swap the engine, keep everything else.
|
||||
|
||||
v0 shipped `PostgresEngine` backed by Supabase. v0.7 adds `PGLiteEngine` -- embedded Postgres 17.5 via WASM (@electric-sql/pglite), zero-config default. The interface is designed so a `DuckDBEngine`, `TursoEngine`, or any custom backend could slot in without touching the CLI, MCP server, skills, or any consumer code.
|
||||
|
||||
## Why this matters
|
||||
|
||||
Different users have different constraints:
|
||||
|
||||
| User | Needs | Best engine |
|
||||
|------|-------|-------------|
|
||||
| Getting started | Zero-config, no accounts, no server | PGLiteEngine (default since v0.7) |
|
||||
| Power user (you) | World-class search, 7K+ pages, zero-ops | PostgresEngine + Supabase |
|
||||
| Open source hacker | Single file, no server, git-friendly | PGLiteEngine |
|
||||
| Team/enterprise | Multi-user, RLS, audit trail | PostgresEngine + self-hosted |
|
||||
| Researcher | Analytics, bulk exports, embeddings | DuckDBEngine (someday) |
|
||||
| Edge/mobile | Offline-first, sync later | PGLiteEngine + sync (someday) |
|
||||
|
||||
The engine interface means we don't have to choose. PGLite is the zero-friction default. Supabase is the production scale path. `gbrain migrate --to supabase/pglite` moves between them.
|
||||
|
||||
## The interface
|
||||
|
||||
```typescript
|
||||
// src/core/engine.ts
|
||||
|
||||
export interface BrainEngine {
|
||||
// Lifecycle
|
||||
connect(config: EngineConfig): Promise<void>;
|
||||
disconnect(): Promise<void>;
|
||||
initSchema(): Promise<void>;
|
||||
transaction<T>(fn: (engine: BrainEngine) => Promise<T>): Promise<T>;
|
||||
|
||||
// Pages CRUD
|
||||
getPage(slug: string): Promise<Page | null>;
|
||||
putPage(slug: string, page: PageInput): Promise<Page>;
|
||||
deletePage(slug: string): Promise<void>;
|
||||
listPages(filters: PageFilters): Promise<Page[]>;
|
||||
|
||||
// Search
|
||||
searchKeyword(query: string, opts?: SearchOpts): Promise<SearchResult[]>;
|
||||
searchVector(embedding: Float32Array, opts?: SearchOpts): Promise<SearchResult[]>;
|
||||
|
||||
// Chunks
|
||||
upsertChunks(slug: string, chunks: ChunkInput[]): Promise<void>;
|
||||
getChunks(slug: string): Promise<Chunk[]>;
|
||||
|
||||
// Links
|
||||
addLink(from: string, to: string, context?: string, linkType?: string): Promise<void>;
|
||||
removeLink(from: string, to: string): Promise<void>;
|
||||
getLinks(slug: string): Promise<Link[]>;
|
||||
getBacklinks(slug: string): Promise<Link[]>;
|
||||
traverseGraph(slug: string, depth?: number): Promise<GraphNode[]>;
|
||||
|
||||
// Tags
|
||||
addTag(slug: string, tag: string): Promise<void>;
|
||||
removeTag(slug: string, tag: string): Promise<void>;
|
||||
getTags(slug: string): Promise<string[]>;
|
||||
|
||||
// Timeline
|
||||
addTimelineEntry(slug: string, entry: TimelineInput): Promise<void>;
|
||||
getTimeline(slug: string, opts?: TimelineOpts): Promise<TimelineEntry[]>;
|
||||
|
||||
// Raw data
|
||||
putRawData(slug: string, source: string, data: object): Promise<void>;
|
||||
getRawData(slug: string, source?: string): Promise<RawData[]>;
|
||||
|
||||
// Versions
|
||||
createVersion(slug: string): Promise<PageVersion>;
|
||||
getVersions(slug: string): Promise<PageVersion[]>;
|
||||
revertToVersion(slug: string, versionId: number): Promise<void>;
|
||||
|
||||
// Stats + health
|
||||
getStats(): Promise<BrainStats>;
|
||||
getHealth(): Promise<BrainHealth>;
|
||||
|
||||
// Ingest log
|
||||
logIngest(entry: IngestLogInput): Promise<void>;
|
||||
getIngestLog(opts?: IngestLogOpts): Promise<IngestLogEntry[]>;
|
||||
|
||||
// Config
|
||||
getConfig(key: string): Promise<string | null>;
|
||||
setConfig(key: string, value: string): Promise<void>;
|
||||
|
||||
// Migration + advanced (added v0.7)
|
||||
runMigration(sql: string): Promise<void>;
|
||||
getChunksWithEmbeddings(slug: string): Promise<ChunkWithEmbedding[]>;
|
||||
}
|
||||
```
|
||||
|
||||
### Key design choices
|
||||
|
||||
**Slug-based API, not ID-based.** Every method takes slugs, not numeric IDs. The engine resolves slugs to IDs internally. This keeps the interface portable... slugs are strings, IDs are database-specific.
|
||||
|
||||
**Embedding is NOT in the engine.** The engine stores embeddings and searches by vector, but it doesn't generate embeddings. `src/core/embedding.ts` handles that. This is intentional: embedding is an external API call (OpenAI), not a storage concern. All engines share the same embedding service.
|
||||
|
||||
**Chunking is NOT in the engine.** Same logic. `src/core/chunkers/` handles chunking. The engine stores and retrieves chunks. All engines share the same chunkers.
|
||||
|
||||
**Search returns `SearchResult[]`, not raw rows.** The engine is responsible for its own search implementation (tsvector vs FTS5, pgvector vs sqlite-vss) but must return a uniform result type. RRF fusion and dedup happen above the engine, in `src/core/search/hybrid.ts`.
|
||||
|
||||
**`traverseGraph` exists but is engine-specific.** Postgres uses recursive CTEs. SQLite would use a loop with depth tracking. The interface is the same: give me a slug and max depth, return the graph.
|
||||
|
||||
## How search works across engines
|
||||
|
||||
```
|
||||
+-------------------+
|
||||
| hybrid.ts |
|
||||
| (RRF fusion + |
|
||||
| dedup, shared) |
|
||||
+--------+----------+
|
||||
|
|
||||
+------------+------------+
|
||||
| |
|
||||
+--------v--------+ +--------v--------+
|
||||
| engine.search | | engine.search |
|
||||
| Keyword() | | Vector() |
|
||||
+-----------------+ +-----------------+
|
||||
| |
|
||||
+-----------+-----------+ +---------+---------+
|
||||
| | | |
|
||||
+-------v-------+ +-------v---+ +-------v---+ +----v--------+
|
||||
| Postgres: | | PGLite: | | Postgres: | | PGLite: |
|
||||
| tsvector + | | tsvector +| | pgvector | | pgvector |
|
||||
| ts_rank + | | ts_rank | | HNSW | | HNSW |
|
||||
| websearch_to_ | | (same SQL)| | cosine | | cosine |
|
||||
| tsquery | | | | | | (same SQL) |
|
||||
+---------------+ +-----------+ +-----------+ +-------------+
|
||||
```
|
||||
|
||||
RRF fusion, multi-query expansion, and 4-layer dedup are engine-agnostic. They operate on `SearchResult[]` arrays. Only the raw keyword and vector searches are engine-specific.
|
||||
|
||||
## PostgresEngine (v0, ships)
|
||||
|
||||
**Dependencies:** `postgres` (porsager/postgres), `pgvector`
|
||||
|
||||
**Postgres-specific features used:**
|
||||
- `tsvector` + `GIN` index for full-text search with `ts_rank` weighting
|
||||
- `pgvector` HNSW index for cosine similarity vector search
|
||||
- `pg_trgm` + `GIN` for fuzzy slug resolution
|
||||
- Recursive CTEs for graph traversal
|
||||
- Trigger-based search_vector (spans pages + timeline_entries)
|
||||
- JSONB for frontmatter with GIN index
|
||||
- Connection pooling via Supabase Supavisor (port 6543)
|
||||
|
||||
**Hosting:** Supabase Pro ($25/mo). Zero-ops. Managed Postgres with pgvector built in.
|
||||
|
||||
**Why not self-hosted for v0:** The brain should be infrastructure agents use, not something you maintain. Self-hosted Postgres with Docker is a welcome community PR, but v0 optimizes for zero ops.
|
||||
|
||||
## PGLiteEngine (v0.7, ships)
|
||||
|
||||
**Dependencies:** `@electric-sql/pglite` (v0.4.4+)
|
||||
|
||||
**What it is:** Embedded Postgres 17.5 compiled to WASM via ElectricSQL's PGLite. Runs in-process, no server, no Docker, no accounts. Same SQL as PostgresEngine -- not a separate dialect. All 37 BrainEngine methods implemented.
|
||||
|
||||
**PGLite-specific details:**
|
||||
- Uses `pglite-schema.ts` for DDL (pgvector extension, pg_trgm, triggers, indexes)
|
||||
- Parameterized queries throughout (shared utilities in `src/core/utils.ts`)
|
||||
- `hybridSearch` keyword-only fallback when `OPENAI_API_KEY` is not set
|
||||
- Data stored at `~/.gbrain/brain.db` (configurable)
|
||||
- pgvector HNSW index for cosine similarity vector search (same as Postgres)
|
||||
- tsvector + ts_rank for full-text search (same as Postgres)
|
||||
- pg_trgm for fuzzy slug resolution (same as Postgres)
|
||||
|
||||
**When to use PGLite vs Postgres:**
|
||||
|
||||
| Factor | PGLite | PostgresEngine + Supabase |
|
||||
|--------|--------|--------------------------|
|
||||
| Setup | `gbrain init` (zero-config) | Account + connection string |
|
||||
| Scale | Good for < 1,000 files | Production-proven at 10K+ |
|
||||
| Multi-device | Single machine only | Any device via remote MCP |
|
||||
| Cost | Free | Supabase Pro ($25/mo) |
|
||||
| Concurrency | Single process | Connection pooling |
|
||||
| Backups | Manual (file copy) | Managed by Supabase |
|
||||
|
||||
**Migration:** `gbrain migrate --to supabase` exports everything (pages, chunks, embeddings, links, tags, timeline) and imports into Supabase. `gbrain migrate --to pglite` goes the other direction. Bidirectional, lossless.
|
||||
|
||||
## Adding a new engine
|
||||
|
||||
1. Create `src/core/<name>-engine.ts` implementing `BrainEngine`
|
||||
2. Add to engine factory in `src/core/engine-factory.ts`:
|
||||
```typescript
|
||||
export function createEngine(type: string): BrainEngine {
|
||||
switch (type) {
|
||||
case 'pglite': return new PGLiteEngine();
|
||||
case 'postgres': return new PostgresEngine();
|
||||
case 'myengine': return new MyEngine();
|
||||
default: throw new Error(`Unknown engine: ${type}`);
|
||||
}
|
||||
}
|
||||
```
|
||||
The factory uses dynamic imports so engines are only loaded when selected.
|
||||
3. Store engine type in `~/.gbrain/config.json`: `{ "engine": "myengine", ... }`
|
||||
4. Add tests. The test suite should be engine-agnostic where possible... same test cases, different engine constructor.
|
||||
5. Document in this file + add a design doc in `docs/`
|
||||
|
||||
### What you DON'T need to touch
|
||||
|
||||
- `src/cli.ts` (dispatches to engine, doesn't know which one)
|
||||
- `src/mcp/server.ts` (same)
|
||||
- `src/core/chunkers/*` (shared across engines)
|
||||
- `src/core/embedding.ts` (shared across engines)
|
||||
- `src/core/search/hybrid.ts`, `expansion.ts`, `dedup.ts` (shared, operate on SearchResult[])
|
||||
- `skills/*` (fat markdown, engine-agnostic)
|
||||
|
||||
### What you DO need to implement
|
||||
|
||||
Every method in `BrainEngine`. The full interface. No optional methods, no feature flags. If your engine can't do vector search (e.g., a pure-text engine), implement `searchVector` to return `[]` and document the limitation.
|
||||
|
||||
## Capability matrix
|
||||
|
||||
| Capability | PostgresEngine | PGLiteEngine | Notes |
|
||||
|-----------|---------------|-------------|-------|
|
||||
| CRUD | Full | Full | Same SQL |
|
||||
| Keyword search | tsvector + ts_rank | tsvector + ts_rank | Identical (real Postgres) |
|
||||
| Vector search | pgvector HNSW | pgvector HNSW | Identical (real Postgres) |
|
||||
| Fuzzy slug | pg_trgm | pg_trgm | Identical (real Postgres) |
|
||||
| Graph traversal | Recursive CTE | Recursive CTE | Same SQL |
|
||||
| Transactions | Full ACID | Full ACID | Both support this |
|
||||
| JSONB queries | GIN index | GIN index | Identical |
|
||||
| Concurrent access | Connection pooling | Single process | PGLite limitation |
|
||||
| Hosting | Supabase, self-hosted, Docker | Local file | |
|
||||
| Migration methods | runMigration, getChunksWithEmbeddings | Same | Added v0.7 |
|
||||
|
||||
## Future engine ideas
|
||||
|
||||
**TursoEngine.** libSQL (SQLite fork) with embedded replicas and HTTP edge access. Would give SQLite's simplicity with cloud sync. Interesting for mobile/edge use cases.
|
||||
|
||||
**DuckDBEngine.** Analytical workloads. Bulk exports, embedding analysis, brain-wide statistics. Not for OLTP. Could be a secondary engine for analytics alongside Postgres for operations.
|
||||
|
||||
**Custom/Remote.** The interface is clean enough that someone could build an engine backed by any storage: Firestore, DynamoDB, a REST API, even a flat file system. The interface doesn't assume SQL.
|
||||
|
||||
Note: The original SQLite engine plan (`docs/SQLITE_ENGINE.md`) was superseded by PGLite. PGLite uses the same SQL as Postgres, eliminating the need for a separate SQLite dialect with FTS5/sqlite-vss translation.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,133 +0,0 @@
|
||||
<!-- skillpack-version: 0.7.0 -->
|
||||
<!-- source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_SKILLPACK.md -->
|
||||
# GBrain Skillpack: Reference Architecture for AI Agents
|
||||
|
||||
This is a reference architecture for how a production AI agent uses gbrain as its
|
||||
knowledge backbone. Based on patterns from a real deployment with 14,700+ brain
|
||||
files, 40+ skills, and 20+ cron jobs running continuously.
|
||||
|
||||
**The memex vision, realized.** Vannevar Bush imagined a device where an individual
|
||||
stores everything, mechanized so it may be consulted with exceeding speed. GBrain is
|
||||
that device, except the memex builds itself. The agent detects entities, enriches
|
||||
pages, creates cross-references, and maintains compiled truth automatically.
|
||||
|
||||
Each section below is a standalone guide. Click through to the full content.
|
||||
|
||||
---
|
||||
|
||||
## Core Patterns
|
||||
|
||||
The foundational read-write loop and data model.
|
||||
|
||||
| Guide | What It Covers |
|
||||
|-------|---------------|
|
||||
| [The Brain-Agent Loop](guides/brain-agent-loop.md) | The read-write cycle that makes the brain compound over time |
|
||||
| [Entity Detection](guides/entity-detection.md) | Run it on every message. Capture original thinking + entity mentions |
|
||||
| [The Originals Folder](guides/originals-folder.md) | Capturing WHAT YOU THINK, not just what you found |
|
||||
| [Brain-First Lookup](guides/brain-first-lookup.md) | Check the brain before calling any external API |
|
||||
| [Compiled Truth + Timeline](guides/compiled-truth.md) | Above the line: current synthesis. Below: append-only evidence |
|
||||
| [Source Attribution](guides/source-attribution.md) | Every fact needs a citation. Format and hierarchy |
|
||||
|
||||
## Data Pipelines
|
||||
|
||||
Getting data in and keeping it current.
|
||||
|
||||
| Guide | What It Covers |
|
||||
|-------|---------------|
|
||||
| [Enrichment Pipeline](guides/enrichment-pipeline.md) | 7-step protocol, tier system (Tier 1/2/3 by importance) |
|
||||
| [Meeting Ingestion](guides/meeting-ingestion.md) | Always pull complete transcript, propagate to all entity pages |
|
||||
| [Content & Media Ingestion](guides/content-media.md) | YouTube, social media bundles, PDFs/documents |
|
||||
| [Diligence Ingestion](guides/diligence-ingestion.md) | Data room materials: pitch decks, financial models, cap tables |
|
||||
| [Deterministic Collectors](guides/deterministic-collectors.md) | Code for data, LLMs for judgment. The collector pattern |
|
||||
| [Idea Capture & Originals](guides/idea-capture.md) | Depth test, originality distribution, deep cross-linking |
|
||||
| [Getting Data In](integrations/README.md) | Integration recipes: voice, email, X, calendar |
|
||||
|
||||
## Operations
|
||||
|
||||
Running a production brain.
|
||||
|
||||
| Guide | What It Covers |
|
||||
|-------|---------------|
|
||||
| [Reference Cron Schedule](guides/cron-schedule.md) | 20+ recurring jobs, quiet hours, dream cycle |
|
||||
| [Cron via Minions](../skills/conventions/cron-via-minions.md) | Why scheduled work runs as Minion jobs, not `agentTurn`. Auto-applied by v0.11.0 migration for built-in handlers; host-specific handlers use the plugin contract below. |
|
||||
| [Plugin Handlers](guides/plugin-handlers.md) | Registering host-specific Minion handlers via code (no data-file exec surface). |
|
||||
| [Minions fix](guides/minions-fix.md) | Repairing a half-migrated v0.11.0 install. |
|
||||
| [Shell jobs (v0.14.0+)](guides/minions-shell-jobs.md) | Move deterministic crons (API fetch, token refresh, scrape+write) off the LLM gateway. Zero tokens per fire, ~60% gateway headroom. Follow `skills/migrations/v0.14.0.md` for the adoption playbook. |
|
||||
| [Quiet Hours & Timezone](guides/quiet-hours.md) | Hold notifications during sleep, timezone-aware delivery |
|
||||
| [Executive Assistant Pattern](guides/executive-assistant.md) | Email triage, meeting prep, scheduling |
|
||||
| [Operational Disciplines](guides/operational-disciplines.md) | Signal detection, brain-first, sync-after-write, heartbeat, dream cycle |
|
||||
| [Skill Development Cycle](guides/skill-development.md) | 5-step cycle: concept, prototype, evaluate, codify, cron |
|
||||
|
||||
**Subagent routing (v0.11.0+):** agents that dispatch background work should route through
|
||||
`skills/conventions/subagent-routing.md` — it reads `~/.gbrain/preferences.json#minion_mode`
|
||||
and branches between native subagents and Minion jobs. The v0.11.0 migration auto-injects
|
||||
a marker into AGENTS.md pointing at this convention.
|
||||
|
||||
**Cron routing (v0.11.0+):** scheduled work goes through Minions, not OpenClaw's `agentTurn`.
|
||||
See `skills/conventions/cron-via-minions.md` for the rewrite pattern. The v0.11.0 migration
|
||||
auto-rewrites entries whose handler is a gbrain builtin; host-specific handlers (e.g.
|
||||
`ea-inbox-sweep`) need a code-level registration per `docs/guides/plugin-handlers.md`.
|
||||
|
||||
## Architecture
|
||||
|
||||
How to structure your system.
|
||||
|
||||
| Guide | What It Covers |
|
||||
|-------|---------------|
|
||||
| [Two-Repo Architecture](guides/repo-architecture.md) | Agent repo vs brain repo, boundary rules, decision tree |
|
||||
| [Sub-Agent Model Routing](guides/sub-agent-routing.md) | Which model for which task, signal detector pattern, cost optimization |
|
||||
| [The Three Search Modes](guides/search-modes.md) | Keyword, hybrid, direct. When to use each |
|
||||
| [Brain vs Agent Memory](guides/brain-vs-memory.md) | 3 layers: GBrain (world knowledge), agent memory, session |
|
||||
|
||||
## Integrations
|
||||
|
||||
Wiring up your life.
|
||||
|
||||
| Guide | What It Covers |
|
||||
|-------|---------------|
|
||||
| [Credential Gateway](integrations/credential-gateway.md) | ClawVisor / Hermes for Gmail, Calendar, Contacts |
|
||||
| [Meeting & Call Webhooks](integrations/meeting-webhooks.md) | Circleback transcripts + Quo/OpenPhone SMS/calls |
|
||||
| [Voice-to-Brain](../recipes/twilio-voice-brain.md) | Phone calls + WebRTC browser calls create brain pages. 25 production patterns: identity separation, bid system, conversation timing, proactive advisor, prompt compression, caller routing, dynamic VAD, real-time logging, belt-and-suspenders post-call |
|
||||
| [Email-to-Brain](../recipes/email-to-brain.md) | Gmail messages flow into entity pages via deterministic collector |
|
||||
| [X-to-Brain](../recipes/x-to-brain.md) | Twitter monitoring with deletion detection + engagement velocity |
|
||||
| [Calendar-to-Brain](../recipes/calendar-to-brain.md) | Google Calendar events become searchable daily brain pages |
|
||||
| [Meeting Sync](../recipes/meeting-sync.md) | Circleback transcripts auto-import with attendee propagation |
|
||||
|
||||
## Administration
|
||||
|
||||
Keeping it running and up to date.
|
||||
|
||||
| Guide | What It Covers |
|
||||
|-------|---------------|
|
||||
| [Upgrades & Auto-Update](guides/upgrades-auto-update.md) | check-update, agent notifications, migration files |
|
||||
| [Live Sync](guides/live-sync.md) | Keep the index current: cron, --watch, webhook approaches |
|
||||
|
||||
---
|
||||
|
||||
## Appendix: GBrain CLI Quick Reference
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `gbrain search "term"` | Keyword search across all brain pages |
|
||||
| `gbrain query "question"` | Hybrid search (vector + keyword + RRF) |
|
||||
| `gbrain get <slug>` | Read a specific brain page by slug |
|
||||
| `gbrain sync` | Sync local markdown repo to gbrain index |
|
||||
| `gbrain import <path>` | Import files into the brain |
|
||||
| `gbrain embed --stale` | Re-embed pages with stale or missing embeddings |
|
||||
| `gbrain integrations` | Manage integration recipes (senses + reflexes) |
|
||||
| `gbrain stats` | Show brain statistics (page count, last sync, etc.) |
|
||||
| `gbrain doctor` | Diagnose brain health issues |
|
||||
| `gbrain check-update` | Check for new versions and integration recipes |
|
||||
|
||||
Run `gbrain --help` for the full command reference.
|
||||
|
||||
---
|
||||
|
||||
## Architecture & Philosophy
|
||||
|
||||
- [Infrastructure Layer](architecture/infra-layer.md) — Import pipeline, chunking, embedding, search
|
||||
- [Thin Harness, Fat Skills](ethos/THIN_HARNESS_FAT_SKILLS.md) — Architecture philosophy
|
||||
- [Markdown Skills as Recipes](ethos/MARKDOWN_SKILLS_AS_RECIPES.md) — Why markdown is code and your agent is a package manager
|
||||
- [Homebrew for Personal AI](designs/HOMEBREW_FOR_PERSONAL_AI.md) — The 10-star vision
|
||||
- [Recommended Schema](GBRAIN_RECOMMENDED_SCHEMA.md) — Directory structure for your brain repo
|
||||
- [Verification Runbook](GBRAIN_VERIFY.md) — End-to-end installation verification
|
||||
@@ -1,544 +0,0 @@
|
||||
# GBrain v0: Postgres-Native Personal Knowledge Brain
|
||||
|
||||
## What this is
|
||||
|
||||
GBrain is a compiled intelligence system. Not a note-taking app. Not "chat with your notes."
|
||||
|
||||
Every page is an intelligence assessment. Above the line: compiled truth (your current best understanding, rewritten when evidence changes). Below the line: timeline (append-only evidence trail). AI agents maintain the brain. MCP clients query it. The intelligence lives in fat markdown skills, not application code.
|
||||
|
||||
The core insight: personal knowledge at scale is an intelligence problem, not a storage problem.
|
||||
|
||||
## Why it exists
|
||||
|
||||
A 7,471-file / 2.3GB markdown wiki is choking git. Git doesn't scale past ~5K files for wiki-style use. The compiled truth + timeline model (Karpathy-style knowledge pages) is right, but it needs a real database underneath.
|
||||
|
||||
There's already a production-grade RAG system (Ruby on Rails, Postgres + pgvector) with 3-tier chunking, hybrid search with RRF, multi-query expansion, and 4-layer dedup. GBrain ports these proven patterns to a standalone Bun + TypeScript tool.
|
||||
|
||||
## The knowledge model
|
||||
|
||||
```
|
||||
+--------------------------------------------------+
|
||||
| Page: concepts/do-things-that-dont-scale |
|
||||
| |
|
||||
| --- frontmatter (YAML) --- |
|
||||
| type: concept |
|
||||
| tags: [startups, growth, pg-essay] |
|
||||
| |
|
||||
| === COMPILED TRUTH === |
|
||||
| Current best understanding. |
|
||||
| Rewritten on new evidence. |
|
||||
| This is the "what we know now" section. |
|
||||
| |
|
||||
| --- |
|
||||
| |
|
||||
| === TIMELINE === |
|
||||
| Append-only evidence trail. |
|
||||
| - 2013-07-01: Published on paulgraham.com |
|
||||
| - 2024-11-15: Referenced in batch kickoff talk |
|
||||
| Never edited, only appended. |
|
||||
+--------------------------------------------------+
|
||||
| |
|
||||
v v
|
||||
[Semantic chunks] [Recursive chunks]
|
||||
(best quality for (predictable format
|
||||
compiled truth) for timeline)
|
||||
| |
|
||||
v v
|
||||
[Embeddings: text-embedding-3-large, 1536 dims]
|
||||
|
|
||||
v
|
||||
[HNSW index + tsvector + pg_trgm]
|
||||
|
|
||||
v
|
||||
[Hybrid search: vector + keyword + RRF fusion]
|
||||
```
|
||||
|
||||
## Architecture decisions
|
||||
|
||||
### v0 stack
|
||||
|
||||
| Layer | Choice | Why |
|
||||
|-------|--------|-----|
|
||||
| Database | Postgres + pgvector | Proven RAG patterns, production-tested. World-class hybrid search. |
|
||||
| Hosting | Supabase Pro ($25/mo) | Zero-ops. Managed Postgres, pgvector, connection pooling. 8GB storage. |
|
||||
| Runtime | Bun + TypeScript | Consistent with GStack ecosystem. Fast. Compiles to single binary. |
|
||||
| Embeddings | OpenAI text-embedding-3-large | 1536 dims (reduced from 3072 via dimensions API). ~$0.13/1M tokens. |
|
||||
| LLM (chunking/expansion) | Claude Haiku | Cheapest model for topic boundary detection and query expansion. |
|
||||
| Background jobs | Trigger.dev | Serverless. Embed backfill, stale detection, orphan audit, tag consistency. |
|
||||
| Distribution | npm package + compiled binary + MCP server | Library for OpenClaw, CLI for humans, MCP for agents. |
|
||||
|
||||
### What we chose and why
|
||||
|
||||
**Postgres over SQLite.** We have 3+ years of proven RAG patterns running on Postgres. tsvector for full-text search, pgvector HNSW for semantic search, pg_trgm for fuzzy slug matching. Porting these to SQLite would mean reimplementing search from scratch. SQLite is a future pluggable engine for lightweight open source users (see `docs/ENGINES.md`).
|
||||
|
||||
**Supabase over self-hosted.** Zero maintenance. The brain should be infrastructure that AI agents use, not something you administer. Free tier has pgvector but only 500MB (not enough for 7K+ pages with embeddings, which need ~750MB). Pro tier at $25/mo gives 8GB. No Docker, no self-hosted Postgres in v1.
|
||||
|
||||
**Full port over minimal viable.** The patterns are proven. The port is mechanical. Shipping the full 3-tier chunking + hybrid search + 4-layer dedup means world-class RAG from day one. "We'll add that later" means rebuilding everything later.
|
||||
|
||||
**Library-first distribution.** gbrain is an npm package. OpenClaw installs it as a dependency (`bun add gbrain`), imports the engine directly. Zero-overhead function calls, shared connection pool, TypeScript types. The CLI and MCP server are thin wrappers over the same engine.
|
||||
|
||||
**Trigger-based tsvector (not generated column).** To include timeline_entries content in full-text search, the tsvector needs to span multiple tables. Generated columns can't do cross-table references. A trigger on pages + timeline_entries updates the search_vector.
|
||||
|
||||
**Auto-embed during import.** No separate embed step. `gbrain import` chunks and embeds in one pass. Progress bar shows status. `--no-embed` flag for users who want to defer. `embedded_at` column enables `gbrain embed --stale` for backfill.
|
||||
|
||||
## Distribution model
|
||||
|
||||
```
|
||||
+-------------------+ +-------------------+ +-------------------+
|
||||
| npm package | | Compiled binary | | MCP server |
|
||||
| (library) | | (CLI) | | (stdio) |
|
||||
+-------------------+ +-------------------+ +-------------------+
|
||||
| | | | | |
|
||||
| bun add gbrain | | GitHub Releases | | gbrain serve |
|
||||
| import { Postgres | | npx gbrain | | in mcp.json |
|
||||
| Engine } | | | | |
|
||||
| | | | | |
|
||||
| WHO: OpenClaw, | | WHO: Humans | | WHO: Claude Code, |
|
||||
| AlphaClaw | | | | Cursor, etc. |
|
||||
+-------------------+ +-------------------+ +-------------------+
|
||||
| | |
|
||||
+-------------------------+-------------------------+
|
||||
|
|
||||
+--------v--------+
|
||||
| BrainEngine |
|
||||
| (pluggable |
|
||||
| interface) |
|
||||
+-----------------+
|
||||
|
|
||||
+-------------+-------------+
|
||||
| |
|
||||
+------v------+ +-------v-------+
|
||||
| Postgres | | SQLite |
|
||||
| Engine | | Engine |
|
||||
| (v0, ships) | | (future, see |
|
||||
+-------------+ | ENGINES.md) |
|
||||
+---------------+
|
||||
```
|
||||
|
||||
package.json exports:
|
||||
- Library: `src/core/index.ts` (BrainEngine interface, PostgresEngine, types)
|
||||
- CLI binary: `src/cli.ts`
|
||||
|
||||
## First-time experience
|
||||
|
||||
### Path 1: OpenClaw user (primary)
|
||||
|
||||
OpenClaw is the AI orchestrator that uses gbrain as its knowledge backend. This is the most common install path.
|
||||
|
||||
```bash
|
||||
# 1. Install gbrain as a ClawHub skill
|
||||
clawhub install gbrain
|
||||
|
||||
# 2. The skill runs guided setup on first use:
|
||||
# - Detects if Supabase CLI is available
|
||||
# - If yes: auto-provisions a new Supabase project
|
||||
# - If no: prompts for connection URL
|
||||
# - Runs schema migration
|
||||
# - Scans for markdown repos and imports user's content
|
||||
# - Shows live entity/edge extraction animation
|
||||
# - Brain is ready
|
||||
|
||||
# 3. From OpenClaw, brain tools are now available:
|
||||
# "Search the brain for [topic from your data]"
|
||||
# "Ingest my meeting notes from today"
|
||||
# "How many pages are in the brain?"
|
||||
```
|
||||
|
||||
Behind the scenes, `clawhub install gbrain`:
|
||||
1. Installs the `gbrain` npm package
|
||||
2. Ships SKILL.md files (ingest, query, maintain, enrich, briefing, migrate)
|
||||
3. Registers brain tools with the orchestrator
|
||||
4. Runs `gbrain init --supabase` on first use (guided wizard)
|
||||
|
||||
### Path 2: CLI user (standalone)
|
||||
|
||||
```bash
|
||||
# 1. Install
|
||||
npm install -g gbrain
|
||||
# or: download binary from GitHub Releases
|
||||
|
||||
# 2. Initialize with Supabase
|
||||
gbrain init --supabase
|
||||
# Guided wizard:
|
||||
# Try 1: Supabase CLI auto-provision (npx supabase)
|
||||
# Try 2: If CLI not installed or not logged in, fallback:
|
||||
# "Enter your Supabase connection URL:"
|
||||
# Then: runs schema migration, verifies pgvector extension
|
||||
# Then: verifies database is ready for import
|
||||
# Output: "Brain ready. Run: gbrain import <your-repo>"
|
||||
|
||||
# 3. Import your data
|
||||
gbrain import /path/to/markdown/wiki/
|
||||
# Progress bar: 7,471 files, auto-chunk, auto-embed
|
||||
# ~30s for text import, ~10-15 min for embedding
|
||||
|
||||
# 4. Query
|
||||
gbrain query "what does PG say about doing things that don't scale?"
|
||||
```
|
||||
|
||||
### Path 3: MCP user (Claude Code, Cursor)
|
||||
|
||||
```json
|
||||
// ~/.config/claude/mcp.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gbrain": {
|
||||
"command": "gbrain",
|
||||
"args": ["serve"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then in Claude Code: "Search my brain for people who know about robotics"
|
||||
|
||||
### The init wizard in detail
|
||||
|
||||
`gbrain init --supabase` runs through these steps:
|
||||
|
||||
```
|
||||
Step 1: Database Setup
|
||||
├── Check for Supabase CLI (npx supabase --version)
|
||||
│ ├── Found + logged in → auto-create project
|
||||
│ │ ├── Create project via supabase CLI
|
||||
│ │ ├── Wait for project to be ready
|
||||
│ │ └── Extract connection string
|
||||
│ ├── Found + not logged in →
|
||||
│ │ └── Error: "Supabase CLI found but not logged in."
|
||||
│ │ Cause: "You need to authenticate first."
|
||||
│ │ Fix: "Run: npx supabase login"
|
||||
│ │ Docs: "https://supabase.com/docs/guides/cli"
|
||||
│ └── Not found → fallback to manual
|
||||
│ └── Prompt: "Enter your Supabase connection URL:"
|
||||
│
|
||||
Step 2: Schema Migration
|
||||
├── Connect to database
|
||||
├── CREATE EXTENSION IF NOT EXISTS vector
|
||||
├── CREATE EXTENSION IF NOT EXISTS pg_trgm
|
||||
├── Run src/schema.sql (all tables, indexes, triggers)
|
||||
└── Verify: test insert + vector query
|
||||
|
||||
Step 3: Config
|
||||
├── Write ~/.gbrain/config.json (0600 permissions)
|
||||
│ { "database_url": "...", "service_role_key": "..." }
|
||||
└── Verify connection
|
||||
|
||||
Step 4: Kindling Import
|
||||
├── Import 10 bundled PG essays as demo data
|
||||
├── Chunk + embed each essay
|
||||
├── Show live entity/edge extraction animation:
|
||||
│ "Extracting entities... Paul Graham (person), Y Combinator (company)..."
|
||||
│ "Creating links... Paul Graham → Y Combinator (founded)..."
|
||||
└── Output: "Brain ready. 10 pages imported."
|
||||
|
||||
Step 5: First Query
|
||||
└── "Try: gbrain query 'what does PG say about doing things that don't scale?'"
|
||||
```
|
||||
|
||||
Every error follows the style guide: problem + cause + fix + docs link.
|
||||
|
||||
## CLI commands
|
||||
|
||||
```
|
||||
gbrain init [--supabase|--url <conn>] # create brain
|
||||
gbrain get <slug> # read a page
|
||||
gbrain put <slug> [< file.md] # write/update a page
|
||||
gbrain search <query> # keyword search (tsvector)
|
||||
gbrain query <question> # hybrid search (RRF + expansion)
|
||||
gbrain ingest <file> [--type ...] # ingest a source document
|
||||
gbrain link <from> <to> [--type <type>] # create typed link
|
||||
gbrain unlink <from> <to> # remove link
|
||||
gbrain graph <slug> [--depth 5] # traverse link graph (recursive CTE)
|
||||
gbrain backlinks <slug> # incoming links
|
||||
gbrain tags <slug> # list tags
|
||||
gbrain tag <slug> <tag> # add tag
|
||||
gbrain untag <slug> <tag> # remove tag
|
||||
gbrain timeline [<slug>] # view timeline
|
||||
gbrain timeline-add <slug> <date> <text> # add timeline entry
|
||||
gbrain list [--type] [--tag] [--limit] # list with filters
|
||||
gbrain stats # brain statistics
|
||||
gbrain health # brain health dashboard
|
||||
gbrain import <dir> [--no-embed] # import from markdown directory
|
||||
gbrain export [--dir ./export/] # export to markdown (round-trip)
|
||||
gbrain embed [<slug>|--all|--stale] # generate/refresh embeddings
|
||||
gbrain serve # MCP server (stdio)
|
||||
gbrain call <tool> '<json>' # raw tool invocation
|
||||
gbrain upgrade # self-update (npm, binary, ClawHub)
|
||||
gbrain version # version info
|
||||
gbrain config [get|set] <key> [value] # brain config
|
||||
```
|
||||
|
||||
CLI and MCP expose identical operations. Drift tests assert identical results for all operations across both interfaces.
|
||||
|
||||
## Database schema
|
||||
|
||||
9 tables in Postgres + pgvector:
|
||||
|
||||
```
|
||||
+------------------+ +-------------------+ +------------------+
|
||||
| pages |---->| content_chunks | | links |
|
||||
|------------------| |-------------------| |------------------|
|
||||
| id (PK) | | id (PK) | | id (PK) |
|
||||
| slug (UNIQUE) | | page_id (FK) | | from_page_id(FK) |
|
||||
| type | | chunk_index | | to_page_id (FK) |
|
||||
| title | | chunk_text | | link_type |
|
||||
| compiled_truth | | chunk_source | | context |
|
||||
| timeline | | embedding (1536) | +------------------+
|
||||
| frontmatter(JSONB)| | model |
|
||||
| search_vector | | token_count | +------------------+
|
||||
| created_at | | embedded_at | | tags |
|
||||
| updated_at | +-------------------+ |------------------|
|
||||
+------------------+ | id (PK) |
|
||||
| | page_id (FK) |
|
||||
+-----> +--------------------+ | tag |
|
||||
| | timeline_entries | +------------------+
|
||||
| |--------------------|
|
||||
| | id (PK) | +------------------+
|
||||
| | page_id (FK) | | page_versions |
|
||||
| | date | |------------------|
|
||||
| | source | | id (PK) |
|
||||
| | summary | | page_id (FK) |
|
||||
| | detail (markdown) | | compiled_truth |
|
||||
| +--------------------+ | frontmatter |
|
||||
| | snapshot_at |
|
||||
+-----> +--------------------+ +------------------+
|
||||
| | raw_data |
|
||||
| |--------------------| +------------------+
|
||||
| | id (PK) | | config |
|
||||
| | page_id (FK) | |------------------|
|
||||
| | source | | key (PK) |
|
||||
| | data (JSONB) | | value |
|
||||
| +--------------------+ +------------------+
|
||||
|
|
||||
+-----> +--------------------+
|
||||
| ingest_log |
|
||||
|--------------------|
|
||||
| id (PK) |
|
||||
| source_type |
|
||||
| source_ref |
|
||||
| pages_updated |
|
||||
| summary |
|
||||
+--------------------+
|
||||
```
|
||||
|
||||
Indexes:
|
||||
- `pages.slug`: UNIQUE constraint (implicit B-tree)
|
||||
- `pages.type`: B-tree
|
||||
- `pages.search_vector`: GIN (full-text search)
|
||||
- `pages.frontmatter`: GIN (JSONB queries)
|
||||
- `pages.title`: GIN with pg_trgm (fuzzy slug resolution)
|
||||
- `content_chunks.embedding`: HNSW with cosine ops (vector search)
|
||||
- `content_chunks.page_id`: B-tree
|
||||
- `links.from_page_id`, `links.to_page_id`: B-tree
|
||||
- `tags.tag`, `tags.page_id`: B-tree
|
||||
- `timeline_entries.page_id`, `timeline_entries.date`: B-tree
|
||||
|
||||
## Search architecture
|
||||
|
||||
```
|
||||
Query: "when should you ignore conventional wisdom?"
|
||||
|
|
||||
v
|
||||
+---------------------+
|
||||
| Multi-query expansion|
|
||||
| (Claude Haiku) |
|
||||
| "contrarian thinking"
|
||||
| "going against the crowd"
|
||||
+---------------------+
|
||||
| | |
|
||||
v v v
|
||||
[embed all 3 queries]
|
||||
| | |
|
||||
+---+---+
|
||||
|
|
||||
+----+----+
|
||||
| |
|
||||
v v
|
||||
+--------+ +--------+
|
||||
| Vector | | Keyword|
|
||||
| Search | | Search |
|
||||
| (HNSW | | (tsv + |
|
||||
| cosine)| | ts_rank)|
|
||||
+--------+ +--------+
|
||||
| |
|
||||
+----+----+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| RRF Fusion |
|
||||
| score = sum( |
|
||||
| 1/(60 + rank)) |
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| 4-Layer Dedup |
|
||||
| 1. By source |
|
||||
| 2. Cosine > 0.85 |
|
||||
| 3. Type cap 60% |
|
||||
| 4. Per-page max |
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| Stale alerts |
|
||||
| (compiled_truth |
|
||||
| older than |
|
||||
| latest timeline)|
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
[Results]
|
||||
```
|
||||
|
||||
## Chunking strategies
|
||||
|
||||
| Strategy | Input | Algorithm | When to use |
|
||||
|----------|-------|-----------|-------------|
|
||||
| Recursive | Any text | 5-level delimiter hierarchy (paragraphs > lines > sentences > clauses > whitespace). 300-word chunks, 50-word overlap. | Timeline (predictable format), bulk import |
|
||||
| Semantic | Quality text | Embed each sentence, Savitzky-Golay filter for topic boundaries, cosine similarity minima. Falls back to recursive. | Compiled truth (intelligence assessments) |
|
||||
| LLM-guided | High-value text | Pre-split to 128-word candidates, Claude Haiku finds topic shifts in sliding windows. 3 retries per window. | Explicitly requested via `--chunker llm` |
|
||||
|
||||
Dispatch: compiled_truth gets semantic chunker. Timeline gets recursive chunker. Override with `--chunker` flag or `chunk_strategy` in frontmatter.
|
||||
|
||||
## Skills (fat markdown, no code)
|
||||
|
||||
Each skill is a markdown file that AI agents (Claude Code, OpenClaw) read and follow. The skill contains the workflow, heuristics, and quality rules. No skill logic is in the binary.
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| `skills/ingest/SKILL.md` | Ingest meetings, docs, articles. Update compiled truth, append timeline, create links. |
|
||||
| `skills/query/SKILL.md` | 3-layer search (FTS + vector + structured). Synthesize answer with citations. |
|
||||
| `skills/maintain/SKILL.md` | Find contradictions, stale info, orphans, dead links, tag inconsistency. |
|
||||
| `skills/enrich/SKILL.md` | Enrich from external APIs (Crustdata, Happenstance, Exa). Store raw data, distill to compiled truth. |
|
||||
| `skills/briefing/SKILL.md` | Daily briefing: meetings with context, active deals, open threads. |
|
||||
| `skills/migrate/SKILL.md` | Universal migration from Obsidian, Notion, Logseq, plain markdown, CSV, JSON, Roam. |
|
||||
|
||||
## CEO scope expansions (accepted for v0)
|
||||
|
||||
1. **CLI/MCP parity with drift tests.** Both interfaces are thin wrappers over the engine. Tests assert identical output.
|
||||
2. **Smart slug resolution.** Fuzzy matching via pg_trgm for reads. Writes require exact slugs. `gbrain get "dont scale"` resolves to `concepts/do-things-that-dont-scale`.
|
||||
3. **Brain health dashboard.** `gbrain health` shows page count, embed coverage, stale pages, orphans, dead links.
|
||||
4. **Normalized timeline.** `timeline_entries` table only (no TEXT column). `detail` field supports markdown.
|
||||
5. **Page version control.** `page_versions` table stores full snapshots (compiled_truth + frontmatter + links + tags). `gbrain history`, `gbrain diff`, `gbrain revert` commands. Revert re-chunks and re-embeds.
|
||||
6. **Typed links + graph traversal.** `link_type` column (knows, invested_in, works_at, etc.). `gbrain graph` uses recursive CTE with max depth (default 5, configurable via `--depth`).
|
||||
7. **Trigger.dev data cleanup jobs.** Daily embed backfill, weekly stale detection + orphan audit + tag consistency.
|
||||
8. **Stale alert annotations.** Search results flag pages where compiled_truth is older than latest timeline entry.
|
||||
9. **Timeline merge on ingest.** Same event created across all mentioned entities.
|
||||
|
||||
## Security model (v0)
|
||||
|
||||
Single-user, local-only:
|
||||
- Supabase service role key in `~/.gbrain/config.json` (0600 permissions)
|
||||
- MCP stdio transport is inherently local (client spawns `gbrain serve` as subprocess)
|
||||
- No multi-user, no RLS, no OAuth in v0
|
||||
- Multi-user path (future): Supabase RLS + per-user API keys
|
||||
|
||||
## Upgrade mechanism
|
||||
|
||||
`gbrain upgrade` detects the installation method and updates accordingly:
|
||||
|
||||
| Path | How |
|
||||
|------|-----|
|
||||
| npm | `bun update gbrain` (or npm equivalent) |
|
||||
| Compiled binary | Download new binary to temp dir, atomic rename swap, exec new process |
|
||||
| ClawHub | `clawhub update gbrain` |
|
||||
|
||||
Version check: compare local version against latest GitHub release tag.
|
||||
|
||||
## Storage and cost estimates
|
||||
|
||||
### Storage (~750MB for 7,471 pages)
|
||||
|
||||
| Component | Size |
|
||||
|-----------|------|
|
||||
| Page text (compiled_truth + timeline) | ~150MB |
|
||||
| JSONB frontmatter | ~20MB |
|
||||
| tsvector + GIN indexes | ~50MB |
|
||||
| Content chunks (~22K, text) | ~80MB |
|
||||
| Embeddings (22K x 1536 floats x 4 bytes) | ~134MB |
|
||||
| HNSW index overhead (~2x embeddings) | ~270MB |
|
||||
| Links, tags, timeline, raw_data, versions | ~50MB |
|
||||
| **Total** | **~750MB** |
|
||||
|
||||
Supabase free tier (500MB) won't fit. Supabase Pro ($25/mo, 8GB) is the starting point.
|
||||
|
||||
### Embedding cost (~$4-5 for initial import)
|
||||
|
||||
| Step | Cost |
|
||||
|------|------|
|
||||
| Semantic chunker sentence embeddings (~374K sentences) | ~$1 |
|
||||
| Chunk embeddings (~22K chunks) | ~$0.30 |
|
||||
| Query expansion (per query, ~3 embeds) | negligible |
|
||||
| **Total initial import** | **~$4-5** |
|
||||
|
||||
Budget alternative: `gbrain import --chunker recursive` skips sentence-level embeddings, then `gbrain embed --rechunk --chunker semantic` upgrades later.
|
||||
|
||||
## Serverless operations stack
|
||||
|
||||
```
|
||||
+------------------+ +------------------+ +------------------+
|
||||
| Supabase | | Vercel | | Trigger.dev |
|
||||
| (Postgres + | | (web/API, | | (background |
|
||||
| pgvector) | | optional) | | jobs) |
|
||||
+------------------+ +------------------+ +------------------+
|
||||
| Database | | Future web UI | | Embed backfill |
|
||||
| Connection pool | | API endpoints | | Stale detection |
|
||||
| pgvector HNSW | | Edge functions | | Orphan audit |
|
||||
| tsvector FTS | | | | Tag consistency |
|
||||
| pg_trgm fuzzy | | | | Daily briefing |
|
||||
+------------------+ +------------------+ +------------------+
|
||||
```
|
||||
|
||||
The CLI connects directly to Supabase Postgres. Trigger.dev and Vercel are for async/scheduled work. The CLI works without them.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
1. `gbrain import /data/brain/` migrates all 7,471 files losslessly
|
||||
2. `gbrain export` round-trips to semantically identical markdown
|
||||
3. `gbrain query "what does PG say about doing things that don't scale?"` returns relevant hybrid search results
|
||||
4. `gbrain serve` starts MCP server connectable by Claude Code
|
||||
5. All 3 chunkers produce correct output with test fixtures
|
||||
6. `gbrain init --supabase` works end-to-end
|
||||
7. `bun test` passes all tests
|
||||
8. `clawhub install gbrain` installs the skill and runs guided setup
|
||||
9. `bun add gbrain` + `import { PostgresEngine } from 'gbrain'` works in external project
|
||||
10. Drift tests pass: CLI and MCP produce identical results
|
||||
11. `gbrain health` outputs accurate brain health metrics
|
||||
12. Migration skill successfully imports an Obsidian vault
|
||||
|
||||
## Future plans
|
||||
|
||||
See `docs/ENGINES.md` for the pluggable engine architecture and future backend plans.
|
||||
|
||||
### v1 candidates (deferred from v0)
|
||||
|
||||
- **`gbrain ask` natural language CLI alias.** Trivial to add. P1 TODO.
|
||||
- **Intelligence compiler.** Treat every fact as a first-class claim with source span, entity links, validity window, confidence, and contradiction status. "What changed, why, and what evidence would flip it again?" From Codex review. Builds on compiled truth model.
|
||||
- **Active skills via Trigger.dev.** Application-specific briefings, meeting prep. Belongs in OpenClaw, not generic brain infra.
|
||||
- **Multi-user access.** Supabase RLS + per-user API keys. v0 is single-user.
|
||||
- **SQLite engine.** Community PRs welcome. See `docs/SQLITE_ENGINE.md`.
|
||||
- **Docker Compose for self-hosted Postgres.** Community PRs welcome.
|
||||
- **Web UI.** Optional Vercel-hosted dashboard for browsing brain pages.
|
||||
|
||||
### Interface abstraction principle
|
||||
|
||||
All operations go through `BrainEngine`. The engine interface is the contract. Postgres-specific features (tsvector, pgvector HNSW, pg_trgm, recursive CTEs) are implementation details inside `PostgresEngine`. The interface exposes capabilities, not SQL.
|
||||
|
||||
This means:
|
||||
- A SQLite engine can implement `searchKeyword` using FTS5 instead of tsvector
|
||||
- A SQLite engine can implement `searchVector` using sqlite-vss instead of pgvector
|
||||
- A future DuckDB engine could implement analytics-heavy workloads
|
||||
- The CLI, MCP server, and library consumers never know which engine runs underneath
|
||||
|
||||
See `docs/ENGINES.md` for the full interface spec and `docs/SQLITE_ENGINE.md` for the SQLite implementation plan.
|
||||
|
||||
## Review history
|
||||
|
||||
| Review | Runs | Status | Key findings |
|
||||
|--------|------|--------|-------------|
|
||||
| /office-hours | 1 | APPROVED | Builder mode. Full port approach chosen. |
|
||||
| /plan-ceo-review | 1 | CLEAR | 11 proposals, 10 accepted, 1 deferred. SCOPE EXPANSION mode. |
|
||||
| /codex review | 1 | issues_found | 24 points challenged, 3 accepted (fuzzy slug, revert spec, tsvector). |
|
||||
| /plan-eng-review | 2 | CLEAR | 3 issues (upgrade paths, import guardrails, init wizard), 0 critical gaps. |
|
||||
| /plan-devex-review | 1 | CLEAR | DX score 5/10 to 7/10. TTHW 25min to 90s. Champion tier. |
|
||||
@@ -1,293 +0,0 @@
|
||||
# GBrain Installation Verification Runbook
|
||||
|
||||
Run these checks after install to confirm every part of GBrain is working.
|
||||
Each check includes the command, expected output, and what to do if it fails.
|
||||
|
||||
The most important check is #4 (live sync). "Sync ran" is not the same as
|
||||
"sync worked." A sync that silently skips pages because of a pooler bug is
|
||||
worse than no sync at all, because you think it's working.
|
||||
|
||||
---
|
||||
|
||||
## 1. Schema Verification
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
gbrain doctor --json
|
||||
```
|
||||
|
||||
**Expected:** All checks return `"ok"`:
|
||||
- `connection`: connected, N pages
|
||||
- `pgvector`: extension installed
|
||||
- `rls`: enabled on all tables
|
||||
- `schema_version`: current
|
||||
- `embeddings`: coverage percentage
|
||||
|
||||
**If it fails:** The doctor output includes specific fix instructions for each
|
||||
check. See `skills/setup/SKILL.md` Error Recovery table.
|
||||
|
||||
---
|
||||
|
||||
## 2. Skillpack Loaded
|
||||
|
||||
**Check:** Ask the agent: "What is the brain-agent loop?"
|
||||
|
||||
**Expected:** The agent references GBRAIN_SKILLPACK.md Section 2 and describes
|
||||
the read-write cycle: detect entities, read brain, respond with context, write
|
||||
brain, sync.
|
||||
|
||||
**If it fails:** The agent hasn't loaded the skillpack. Run step 6 from the
|
||||
install paste (read `docs/GBRAIN_SKILLPACK.md`).
|
||||
|
||||
---
|
||||
|
||||
## 3. Auto-Update Configured
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
gbrain check-update --json
|
||||
```
|
||||
|
||||
**Expected:** Returns JSON with `current_version`, `latest_version`,
|
||||
`update_available` (boolean). The cron `gbrain-update-check` is registered.
|
||||
|
||||
**If it fails:** Run step 7 from the install paste. See GBRAIN_SKILLPACK.md
|
||||
Section 17.
|
||||
|
||||
---
|
||||
|
||||
## 4. Live Sync Actually Works
|
||||
|
||||
This is the most important check. Three parts.
|
||||
|
||||
### 4a. Coverage Check
|
||||
|
||||
Compare page count in the DB against syncable file count in the repo:
|
||||
|
||||
```bash
|
||||
gbrain stats
|
||||
```
|
||||
|
||||
Then count syncable files:
|
||||
|
||||
```bash
|
||||
find /data/brain -name '*.md' \
|
||||
-not -path '*/.*' \
|
||||
-not -path '*/.raw/*' \
|
||||
-not -path '*/ops/*' \
|
||||
-not -name 'README.md' \
|
||||
-not -name 'index.md' \
|
||||
-not -name 'schema.md' \
|
||||
-not -name 'log.md' \
|
||||
| wc -l
|
||||
```
|
||||
|
||||
**Expected:** Page count in `gbrain stats` should be close to the file count.
|
||||
Some difference is normal (files added since last sync), but if page count is
|
||||
less than half the file count, sync is silently skipping pages.
|
||||
|
||||
**If page count is way too low:** The #1 cause is the connection pooler bug.
|
||||
Check your `DATABASE_URL`:
|
||||
- If it contains `pooler.supabase.com:6543`, verify it's using **Session mode**,
|
||||
not Transaction mode.
|
||||
- Transaction mode breaks `engine.transaction()` and causes `.begin() is not a
|
||||
function` errors.
|
||||
- Fix: switch to Session mode pooler string, then run `gbrain sync --full`
|
||||
to reimport everything.
|
||||
|
||||
### 4b. Embed Check
|
||||
|
||||
```bash
|
||||
gbrain stats
|
||||
```
|
||||
|
||||
**Expected:** Embedded chunk count should be close to total chunk count.
|
||||
|
||||
**If embedded is much lower than total:**
|
||||
|
||||
```bash
|
||||
gbrain embed --stale
|
||||
```
|
||||
|
||||
If `OPENAI_API_KEY` is not set, embeddings can't be generated. Keyword search
|
||||
still works without embeddings, but hybrid/semantic search won't.
|
||||
|
||||
### 4c. End-to-End Test
|
||||
|
||||
This is the real test. Edit a brain page, push, wait, search.
|
||||
|
||||
1. Edit a page in the brain repo (e.g., correct a fact on a person's page):
|
||||
|
||||
```bash
|
||||
# Example: fix a line in Gustaf's page
|
||||
cd /data/brain
|
||||
# Make a small edit to any .md file
|
||||
git add -A && git commit -m "test: verify live sync" && git push
|
||||
```
|
||||
|
||||
2. Wait for the next sync cycle (cron interval or `--watch` poll).
|
||||
|
||||
3. Search for the corrected text:
|
||||
|
||||
```bash
|
||||
gbrain search "<text from the correction>"
|
||||
```
|
||||
|
||||
**Expected:** The search returns the **corrected** text, not the old version.
|
||||
|
||||
**If it returns old text:** Sync failed silently. Check:
|
||||
- Is the sync cron registered and running?
|
||||
- Is `gbrain sync --watch` still alive (if using watch mode)?
|
||||
- Run `gbrain config get sync.last_run` to see when sync last ran.
|
||||
- Run `gbrain sync --repo /data/brain` manually and check for errors.
|
||||
- If you see `.begin() is not a function`, fix the pooler (see 4a above).
|
||||
|
||||
---
|
||||
|
||||
## 5. Embedding Coverage
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
gbrain stats
|
||||
```
|
||||
|
||||
**Expected:** Embedded chunk count matches (or is close to) total chunk count.
|
||||
|
||||
**If zero or very low:** `OPENAI_API_KEY` may be missing or invalid. Check:
|
||||
|
||||
```bash
|
||||
echo $OPENAI_API_KEY | head -c 10
|
||||
```
|
||||
|
||||
If blank, set the key. Then:
|
||||
|
||||
```bash
|
||||
gbrain embed --stale
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Brain-First Lookup Protocol
|
||||
|
||||
**Check:** Ask the agent about a person or concept that exists in the brain.
|
||||
|
||||
**Expected:** The agent uses `gbrain search` or `gbrain query` FIRST, not grep
|
||||
or external APIs. The response includes brain-sourced context with source
|
||||
attribution.
|
||||
|
||||
**If it fails:** The brain-first lookup protocol isn't injected into the agent's
|
||||
system context. See `skills/setup/SKILL.md` Phase D.
|
||||
|
||||
---
|
||||
|
||||
## 7. Knowledge Graph Wired
|
||||
|
||||
The v0.12.0 graph layer needs to be populated for existing brains. New writes are
|
||||
auto-linked, but historical pages need a one-time backfill.
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
gbrain stats | grep -E 'links|timeline'
|
||||
```
|
||||
|
||||
**Expected:** Both `links` and `timeline_entries` are non-zero (assuming the brain
|
||||
has content with entity references and dated markdown).
|
||||
|
||||
**If it's zero on a brain with imported content:** Run the backfill.
|
||||
|
||||
```bash
|
||||
gbrain extract links --source db --dry-run | head -5 # preview
|
||||
gbrain extract links --source db # commit
|
||||
gbrain extract timeline --source db
|
||||
gbrain stats # confirm > 0
|
||||
```
|
||||
|
||||
**Bonus check** — graph traversal works:
|
||||
|
||||
```bash
|
||||
# Pick any well-connected slug from your brain
|
||||
gbrain graph-query people/<some-person-slug> --depth 2
|
||||
```
|
||||
|
||||
**Expected:** Indented tree of typed edges (`--attended-->`, `--works_at-->`, etc.).
|
||||
If the slug has no inbound or outbound links, try a different one or run extract
|
||||
again.
|
||||
|
||||
**If extract finds nothing:** Your pages may not use entity-reference syntax. The
|
||||
extractor matches `[Name](people/slug)`, `[Name](../people/slug.md)`, and bare
|
||||
`people/slug` references. If your brain uses a different format, the auto-link
|
||||
heuristics won't find them — file an issue with a sample page.
|
||||
|
||||
---
|
||||
|
||||
## 8. JSONB Frontmatter Integrity (v0.12.2)
|
||||
|
||||
Postgres-backed brains created before v0.12.2 had double-encoded JSONB columns
|
||||
(`frontmatter->>'key'` returned NULL, GIN indexes were inert). `gbrain upgrade`
|
||||
runs `gbrain repair-jsonb` automatically via the `v0_12_2` orchestrator.
|
||||
Verify the repair succeeded.
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
gbrain repair-jsonb --dry-run --json
|
||||
```
|
||||
|
||||
**Expected:** `totalRepaired: 0` across all 5 columns (`pages.frontmatter`,
|
||||
`raw_data.data`, `ingest_log.pages_updated`, `files.metadata`,
|
||||
`page_versions.frontmatter`). A zero count means every row is properly-typed
|
||||
JSON objects, not string-encoded JSON.
|
||||
|
||||
**If the count is > 0:** The repair didn't run or was interrupted. Re-run
|
||||
without `--dry-run`:
|
||||
|
||||
```bash
|
||||
gbrain repair-jsonb
|
||||
```
|
||||
|
||||
Idempotent. PGLite brains always report 0 (unaffected by the original bug).
|
||||
|
||||
**Bonus check** — frontmatter-keyed queries actually resolve:
|
||||
|
||||
```bash
|
||||
gbrain call list_pages '{"frontmatterKey": "type", "frontmatterValue": "person"}'
|
||||
```
|
||||
|
||||
If this returns rows on a brain with person pages, the JSONB path is healthy.
|
||||
|
||||
---
|
||||
|
||||
## Quick Verification (all checks in one pass)
|
||||
|
||||
```bash
|
||||
# 1. Schema
|
||||
gbrain doctor --json
|
||||
|
||||
# 2. Sync recency
|
||||
gbrain config get sync.last_run
|
||||
|
||||
# 3. Page count + embed coverage
|
||||
gbrain stats
|
||||
|
||||
# 4. Search works
|
||||
gbrain search "test query from your brain content"
|
||||
|
||||
# 5. Catch any unembedded chunks
|
||||
gbrain embed --stale
|
||||
|
||||
# 6. Auto-update
|
||||
gbrain check-update --json
|
||||
|
||||
# 7. Knowledge graph populated (links + timeline > 0)
|
||||
gbrain stats | grep -E 'links|timeline'
|
||||
|
||||
# 8. JSONB integrity (v0.12.2 — Postgres only, PGLite always 0)
|
||||
gbrain repair-jsonb --dry-run --json
|
||||
```
|
||||
|
||||
If all eight return successfully, the installation is healthy. For the full
|
||||
end-to-end sync test (4c), push a real change and verify it appears in search.
|
||||
@@ -1,371 +0,0 @@
|
||||
# Upgrading Downstream Agents
|
||||
|
||||
GBrain ships skills in `skills/`. Downstream agents (custom OpenClaw deployments,
|
||||
agent forks of any kind) often **copy** these skill files into their own workspace and
|
||||
diverge over time — adding agent-specific phases, removing irrelevant ones, tightening
|
||||
language. Once that happens, gbrain can't push updates to those forks. The agent has
|
||||
to apply the diffs by hand.
|
||||
|
||||
This doc lists the exact diffs each downstream agent needs to apply when upgrading.
|
||||
Cross-reference against your fork's local skill files.
|
||||
|
||||
## Why this exists
|
||||
|
||||
`gbrain upgrade` ships the new binary. `gbrain post-upgrade [--execute --yes]` runs
|
||||
the schema migrations and backfills the data. But the **skill files themselves**
|
||||
that tell the agent how to behave — those are user-owned. If your `~/git/<your-agent>/workspace/skills/brain-ops/SKILL.md`
|
||||
says `# Based on gbrain v0.10.0` at the top, it doesn't know about v0.12.0 features.
|
||||
|
||||
The agent will keep manually calling `gbrain link` after every `put_page` (now redundant —
|
||||
auto-link does it), miss out on `gbrain graph-query` for relationship questions, and
|
||||
not know to backfill the structured timeline.
|
||||
|
||||
## How to apply
|
||||
|
||||
1. Identify your forked skill files. Typically at `~/git/<your-agent>/workspace/skills/` or wherever your agent's skill directory lives.
|
||||
2. For each skill listed below, find the matching phase/section in your fork.
|
||||
3. Apply the diff (paste the new block in the indicated location).
|
||||
4. Update the version banner at the top of your fork (`# Based on gbrain v0.12.0`).
|
||||
5. Verify: ask the agent to write a test page and confirm the response includes
|
||||
`auto_links: { created, removed, errors }`.
|
||||
|
||||
Total time: ~10 minutes for all four skills.
|
||||
|
||||
---
|
||||
|
||||
## 1. brain-ops/SKILL.md
|
||||
|
||||
**Where:** Insert a new `### Phase 2.5` section immediately after `### Phase 2: On Every Inbound Signal`.
|
||||
|
||||
**Why:** Phase 2.5 declares that auto-link runs automatically. Without this, the
|
||||
agent's mental model says it must call `gbrain link` after every `put_page`, which
|
||||
is now redundant and can cause double-add warnings.
|
||||
|
||||
```markdown
|
||||
### Phase 2.5: Structured Graph Updates (automatic)
|
||||
|
||||
Every `put_page` call automatically extracts entity references and writes them
|
||||
to the graph (`links` table) with inferred relationship types. Stale links
|
||||
(refs no longer in the page text) are removed in the same call. This is
|
||||
"auto-link" reconciliation.
|
||||
|
||||
- No manual `add_link` calls needed for ordinary page writes.
|
||||
- Inferred link types: `attended` (meeting -> person), `works_at`, `invested_in`,
|
||||
`founded`, `advises`, `source` (frontmatter), `mentions` (default).
|
||||
- The `put_page` MCP response includes `auto_links: { created, removed, errors }`
|
||||
so the agent can verify outcomes.
|
||||
- To disable: `gbrain config set auto_link false`. Default is on.
|
||||
- Timeline entries with specific dates still need explicit `gbrain timeline-add`
|
||||
(or batch via `gbrain extract timeline --source db`).
|
||||
```
|
||||
|
||||
**Also update the Iron Law section.** If your fork still says "Back-links maintained
|
||||
on every brain write (Iron Law)" without qualification, append:
|
||||
|
||||
```markdown
|
||||
**v0.12.0 update:** Auto-link satisfies the Iron Law for entity-reference links
|
||||
on every `put_page`. The agent's Iron Law obligation is now: include the
|
||||
entity reference in the page content (e.g., `[Alice](people/alice)`); auto-link
|
||||
handles the structured row. Manual `add_link` calls are reserved for
|
||||
relationships you can't express in markdown content.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. meeting-ingestion/SKILL.md
|
||||
|
||||
**Where:** Append to the end of `### Phase 3: Attendee enrichment`.
|
||||
|
||||
**Why:** Eliminates redundant `gbrain link` calls per attendee (auto-link handles them
|
||||
when the meeting page references attendees as `[Name](people/slug)`).
|
||||
|
||||
```markdown
|
||||
**Note (v0.12.0):** Once the meeting page is written via `gbrain put`, the
|
||||
auto-link post-hook automatically creates `attended` links from the meeting
|
||||
to each attendee whose page is referenced as `[Name](people/slug)`. You don't
|
||||
need to call `gbrain link` for attendees. You DO still need `gbrain timeline-add`
|
||||
for dated events (auto-link only handles links, not timeline entries).
|
||||
```
|
||||
|
||||
**Where:** In `### Phase 4: Entity propagation`, the line "Back-link from entity page
|
||||
to meeting page" can be replaced with:
|
||||
|
||||
```markdown
|
||||
4. Entity references in the meeting page body auto-create the link via auto-link.
|
||||
For incoming references on the entity page (entity page → meeting page), edit
|
||||
the entity page to mention the meeting and `put_page` it — auto-link handles
|
||||
the rest.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. signal-detector/SKILL.md
|
||||
|
||||
**Where:** Append to the end of `### Phase 2: Entity Detection`.
|
||||
|
||||
**Why:** Same logic as brain-ops — eliminates manual `gbrain link` after writing
|
||||
originals/ideas pages that reference people or companies.
|
||||
|
||||
```markdown
|
||||
**Auto-link (v0.12.0):** When you write/update an originals or ideas page that
|
||||
references a person or company, the auto-link post-hook on `put_page`
|
||||
automatically creates the link from the new page to that entity. You don't
|
||||
need to call `gbrain link` manually. Timeline entries still need explicit calls.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. enrich/SKILL.md
|
||||
|
||||
**Where:** Replace `### Step 7: Cross-reference` with the v0.12.0 version.
|
||||
|
||||
**Why:** Step 7 used to be primarily about creating links between related entity
|
||||
pages. With auto-link, that's automatic. Step 7 is now about content updates,
|
||||
not link creation.
|
||||
|
||||
Old (delete):
|
||||
```markdown
|
||||
### Step 7: Cross-reference
|
||||
|
||||
- Update company pages from person enrichment (and vice versa)
|
||||
- Update related project/deal pages if relevant context surfaced
|
||||
- Check index files if the brain uses them
|
||||
- Add back-links manually via `gbrain link` for any new entity references
|
||||
```
|
||||
|
||||
New (paste):
|
||||
```markdown
|
||||
### Step 7: Cross-reference
|
||||
|
||||
- Update company pages from person enrichment (and vice versa)
|
||||
- Update related project/deal pages if relevant context surfaced
|
||||
- Check index files if the brain uses them
|
||||
|
||||
**Note (v0.12.0):** Links between brain pages are auto-created on every
|
||||
`put_page` call (auto-link post-hook). Step 7 focuses on content
|
||||
cross-references (updating related pages' compiled truth with new signal
|
||||
from this enrichment), not on creating links. Verify via the `auto_links`
|
||||
field in the put_page response (`{ created, removed, errors }`).
|
||||
Timeline entries still need explicit `gbrain timeline-add` calls.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## After all four diffs are applied
|
||||
|
||||
1. **Bump the version banner** at the top of each forked file:
|
||||
```
|
||||
# Based on gbrain v0.12.0 skills/<skill-name>, extended with <your-agent>-specific config
|
||||
```
|
||||
|
||||
2. **Run the v0.12.0 backfill** (this populates the graph for your existing brain):
|
||||
```bash
|
||||
gbrain post-upgrade
|
||||
```
|
||||
The v0.12.0 release wires post-upgrade to call `apply-migrations --yes`
|
||||
automatically, which runs the v0_12_0 orchestrator (schema → config check →
|
||||
`extract links --source db` → `extract timeline --source db` → verify).
|
||||
Idempotent; cheap when nothing is pending.
|
||||
|
||||
3. **Verify auto-link works:** ask the agent to write a test page that references
|
||||
`[Some Person](people/some-person)`. Confirm the put_page response includes
|
||||
`auto_links: { created: 1, removed: 0, errors: 0 }`.
|
||||
|
||||
4. **Verify graph traversal works:**
|
||||
```bash
|
||||
gbrain graph-query people/some-well-connected-person --depth 2
|
||||
```
|
||||
Should return an indented tree of typed edges.
|
||||
|
||||
---
|
||||
|
||||
## v0.12.2 hotfix (data-correctness, no skill edits)
|
||||
|
||||
v0.12.2 is a Postgres data-correctness hotfix. No forked skill files need to
|
||||
change — the skill contracts are unchanged. But you DO need to run the migration,
|
||||
and you should know about one behavior change in markdown parsing.
|
||||
|
||||
### 1. Run the migration (Postgres-backed brains)
|
||||
|
||||
```bash
|
||||
gbrain upgrade
|
||||
```
|
||||
|
||||
The `v0_12_2` orchestrator runs `gbrain repair-jsonb` automatically. It rewrites
|
||||
rows where `jsonb_typeof = 'string'` across `pages.frontmatter`, `raw_data.data`,
|
||||
`ingest_log.pages_updated`, `files.metadata`, and `page_versions.frontmatter`.
|
||||
Idempotent, safe to re-run. PGLite brains no-op cleanly.
|
||||
|
||||
Verify after upgrade:
|
||||
|
||||
```bash
|
||||
gbrain repair-jsonb --dry-run --json # expect totalRepaired: 0
|
||||
```
|
||||
|
||||
### 2. Recover any truncated wiki articles
|
||||
|
||||
If your brain imported wiki-style markdown before v0.12.2, some pages were
|
||||
silently truncated (any standalone `---` in body content was treated as a
|
||||
timeline separator). Re-import from source:
|
||||
|
||||
```bash
|
||||
gbrain sync --full
|
||||
```
|
||||
|
||||
The new `splitBody` rebuilds `compiled_truth` correctly.
|
||||
|
||||
### 3. Know the splitBody contract going forward
|
||||
|
||||
`splitBody` now requires an explicit timeline sentinel. Recognized markers
|
||||
(priority order):
|
||||
|
||||
1. `<!-- timeline -->` (preferred — what `serializeMarkdown` emits)
|
||||
2. `--- timeline ---` (decorated separator)
|
||||
3. `---` directly before `## Timeline` or `## History` heading (backward-compat)
|
||||
|
||||
A bare `---` in body text is now a markdown horizontal rule, not a timeline
|
||||
separator. If your agent writes pages with a bare `---` delimiter, migrate to
|
||||
`<!-- timeline -->` — the `serializeMarkdown` helper already does this.
|
||||
|
||||
### 4. Wiki subtypes now auto-typed
|
||||
|
||||
`inferType` now auto-detects five additional directory patterns as their own
|
||||
page types (previously they all defaulted to `concept`):
|
||||
|
||||
| Path pattern | New type |
|
||||
|------------------------|----------------|
|
||||
| `/wiki/analysis/` | `analysis` |
|
||||
| `/wiki/guides/` | `guide` |
|
||||
| `/wiki/hardware/` | `hardware` |
|
||||
| `/wiki/architecture/` | `architecture` |
|
||||
| `/writing/` | `writing` |
|
||||
|
||||
If your skills or queries filter by `type=concept` and expect wiki content in
|
||||
that bucket, update them to include the new types.
|
||||
|
||||
---
|
||||
|
||||
## v0.13.0 — Frontmatter Relationship Indexing
|
||||
|
||||
**Verdict: no action required for most skills.** v0.13 projects YAML frontmatter fields into the graph as typed edges. The ingestion API is unchanged — keep calling `put_page` with frontmatter the way you do today; the graph auto-populates behind the scenes.
|
||||
|
||||
Three skills get an optional new phase if you want to consume the new `auto_links.unresolved` response field. Without this, unresolvable frontmatter names silently skip (same as v0.12 behavior).
|
||||
|
||||
### 1. meeting-ingestion/SKILL.md (optional)
|
||||
|
||||
**Where:** Add a new section after "Phase 3: Write Meeting Page".
|
||||
|
||||
```markdown
|
||||
### Phase 3.5: Check for unresolved attendees (v0.13+)
|
||||
|
||||
After `put_page`, inspect `response.auto_links.unresolved` — an array of frontmatter
|
||||
references that did not resolve to existing pages. For meetings, this usually means
|
||||
attendees you haven't created a person page for yet.
|
||||
|
||||
If `unresolved.length > 0`:
|
||||
- Option 1 (create pages now): trigger an enrichment pass to build the missing people pages.
|
||||
- Option 2 (defer): log the unresolved names to the enrichment queue for later.
|
||||
- Option 3 (accept the gap): the attendee edge will not be created until a page exists.
|
||||
Re-running `gbrain extract links --source db --include-frontmatter` after creating
|
||||
the page fills in the missing edges.
|
||||
```
|
||||
|
||||
### 2. enrich/SKILL.md (optional)
|
||||
|
||||
**Where:** Add to the enrichment trigger list.
|
||||
|
||||
```markdown
|
||||
### Drain unresolved frontmatter names (v0.13+)
|
||||
|
||||
If any `put_page` response includes `auto_links.unresolved` entries, the enrichment
|
||||
tier should pick up those (field, name) pairs and try to create the missing entity
|
||||
pages. Example flow:
|
||||
|
||||
1. signal-detector captures a meeting with `attendees: [Alice Known, Unknown Person]`
|
||||
2. put_page returns `auto_links.unresolved = [{field: 'attendees', name: 'Unknown Person'}]`
|
||||
3. enrichment tier consumes `Unknown Person` → web search → creates `people/unknown-person.md`
|
||||
4. The next put_page (or a backfill run) wires up the `attended` edge automatically
|
||||
```
|
||||
|
||||
### 3. idea-ingest/SKILL.md (optional)
|
||||
|
||||
**Where:** Same pattern as meeting-ingestion — check `auto_links.unresolved` after `put_page`, route names to enrichment.
|
||||
|
||||
### Unchanged skills (no diffs needed)
|
||||
|
||||
- **brain-ops/SKILL.md** — auto-link mechanics are internal; the write path stays the same.
|
||||
- **signal-detector/SKILL.md** — signal capture path unchanged.
|
||||
- **query/SKILL.md** — `traverse_graph` now returns richer results automatically.
|
||||
- **daily-task-manager/SKILL.md**, **briefing/SKILL.md**, **citation-fixer/SKILL.md**, **media-ingest/SKILL.md** — unchanged.
|
||||
|
||||
### New edge types you can filter in graph queries
|
||||
|
||||
v0.13 edges carry new `link_type` values. If your fork has graph-query skills that filter by type, these are now available:
|
||||
|
||||
- `works_at` (person → company) — from `company:`, `companies:`, or `key_people:`
|
||||
- `founded` (person → company) — from `founded:`
|
||||
- `invested_in` (investor → deal/company) — from `investors:` or `lead:`
|
||||
- `led_round` (lead → deal) — from `lead:`
|
||||
- `yc_partner` (partner → company) — from `partner:`
|
||||
- `attended` (person → meeting) — from `attendees:`
|
||||
- `discussed_in` (source → page) — from `sources:`
|
||||
- `source` (page → source) — from `source:`
|
||||
- `related_to` (page → target) — from `related:` or `see_also:`
|
||||
|
||||
### Migration timing
|
||||
|
||||
`gbrain upgrade` takes 2-5 min on a 46K-page brain (one-time). Runs out-of-process via `gbrain post-upgrade`. If your agent holds a DB connection during the upgrade, reconnect after; otherwise keep serving.
|
||||
|
||||
### Type normalization NOT in v0.13
|
||||
|
||||
Legacy rows with `link_type='attendee'` or `link_type='mention'` coexist with new `'attended'` / `'mentions'` rows. Your queries filtering on old type names keep working. A separate opt-in `gbrain normalize-types` command in v0.14 handles the rename.
|
||||
## v0.14.0 shell jobs (optional adoption, no skill edits)
|
||||
|
||||
Adds a `shell` job type to Minions so deterministic cron scripts (API fetch, token
|
||||
refresh, scrape + write) move off the LLM gateway. Zero tokens per fire. ~60%
|
||||
gateway CPU headroom at typical scale. Feature is **off by default**, existing
|
||||
installs keep running exactly as they did before. Nothing breaks.
|
||||
|
||||
To adopt, follow `skills/migrations/v0.14.0.md`. The short version:
|
||||
|
||||
1. Set `GBRAIN_ALLOW_SHELL_JOBS=1` on the worker process, then `gbrain jobs work`
|
||||
(Postgres). On PGLite, every crontab invocation uses `--follow` for inline
|
||||
execution; no persistent worker.
|
||||
2. Classify each of your host's cron entries: LLM-requiring (keep on gateway) vs
|
||||
deterministic (candidate for shell). Typical splits:
|
||||
- **Deterministic → shell:** `ycli-token-refresh`, `x-oauth2-refresh`,
|
||||
`x-garrytan-unified`, `calendar-sync-to-brain`, `github-pulse`,
|
||||
`frameio-scan`, `flight-tracker`, `x-raw-json-backfill`.
|
||||
- **LLM-requiring → stay:** `social-radar`, `content-ideas`, `adversary-vacuum`,
|
||||
`ea-inbox-sweep`, `morning-briefing`, `brain-maintenance`.
|
||||
3. For each deterministic cron, rewrite as:
|
||||
```cron
|
||||
3 13,16,19,22,1,4,7,10 * * * \
|
||||
gbrain jobs submit shell \
|
||||
--params '{"cmd":"node scripts/your-script.mjs","cwd":"/data/.openclaw/workspace"}' \
|
||||
--max-attempts 3 --timeout-ms 300000
|
||||
```
|
||||
4. Watch `gbrain jobs get <id>` for exit_code / stdout_tail / stderr_tail on each
|
||||
fire. Compare against pre-migration behavior before approving the next batch.
|
||||
|
||||
**No skill edits required.** The handler runs worker-side; skill files don't
|
||||
change. If your host exposed custom handlers via the plugin contract (v0.11.0),
|
||||
they still work the same way.
|
||||
|
||||
Iron rule: **never auto-rewrite the operator's crontab.** Every rewrite is
|
||||
per-cron, human-approved, with a diff. If you want automation later, the
|
||||
upcoming `gbrain crontab-to-minions <file>` helper is P1 in TODOS.
|
||||
|
||||
---
|
||||
|
||||
## Future versions
|
||||
|
||||
When gbrain ships a new version, this doc will be updated with the diffs for that
|
||||
version. Each new version appends a section; old sections stay so you can catch up
|
||||
multiple versions at once.
|
||||
|
||||
To check what your fork is missing:
|
||||
```bash
|
||||
diff <(grep -A3 "Based on gbrain" ~/<your-fork>/skills/brain-ops/SKILL.md) \
|
||||
<(grep "v[0-9]" ~/gbrain/skills/migrations/ | tail -3)
|
||||
```
|
||||
@@ -1,105 +0,0 @@
|
||||
# GBrain Infrastructure Layer
|
||||
|
||||
The shared foundation that all skills, recipes, and integrations build on.
|
||||
|
||||
## Data Pipeline
|
||||
|
||||
```
|
||||
INPUT (markdown files, git repo)
|
||||
↓
|
||||
FILE RESOLUTION (local → .redirect → .supabase → error)
|
||||
↓
|
||||
MARKDOWN PARSER (gray-matter frontmatter + body)
|
||||
→ compiled_truth + timeline separation
|
||||
↓
|
||||
CONTENT HASH (SHA-256 idempotency check — skip if unchanged)
|
||||
↓
|
||||
CHUNKING (3 strategies, configurable)
|
||||
├── Recursive: 300-word chunks, 50-word overlap, 5-level delimiter hierarchy
|
||||
├── Semantic: embed sentences, cosine similarity, Savitzky-Golay smoothing
|
||||
└── LLM-guided: Claude Haiku identifies topic shifts in 128-word candidates
|
||||
↓
|
||||
EMBEDDING (OpenAI text-embedding-3-large, 1536 dimensions)
|
||||
→ batch 100, exponential backoff, non-fatal if fails
|
||||
↓
|
||||
DATABASE TRANSACTION (atomic: page + chunks + tags + version)
|
||||
↓
|
||||
SEARCH (hybrid, available immediately)
|
||||
```
|
||||
|
||||
## Search Architecture
|
||||
|
||||
GBrain uses Reciprocal Rank Fusion (RRF) to merge vector and keyword search:
|
||||
|
||||
```
|
||||
User Query
|
||||
↓
|
||||
EXPANSION (optional: Claude Haiku generates 2 alternative phrasings)
|
||||
↓
|
||||
├── VECTOR SEARCH (pgvector HNSW, cosine distance)
|
||||
│ → 2x limit results per query variant
|
||||
│
|
||||
└── KEYWORD SEARCH (PostgreSQL tsvector, ts_rank)
|
||||
→ 2x limit results
|
||||
↓
|
||||
RRF MERGE (score = Σ(1/(60 + rank)), balances both fairly)
|
||||
↓
|
||||
4-LAYER DEDUP
|
||||
├── Best 3 chunks per page (source dedup)
|
||||
├── Jaccard similarity > 0.85 (text dedup)
|
||||
├── No type exceeds 60% (diversity)
|
||||
└── Max 2 chunks per page (page cap)
|
||||
↓
|
||||
TOP N RESULTS (default 20)
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/core/engine.ts` | Pluggable engine interface (BrainEngine) |
|
||||
| `src/core/postgres-engine.ts` | Postgres + pgvector implementation |
|
||||
| `src/core/import-file.ts` | importFromFile + importFromContent pipeline |
|
||||
| `src/core/sync.ts` | Git-based incremental change detection |
|
||||
| `src/core/markdown.ts` | YAML frontmatter + compiled_truth/timeline parsing |
|
||||
| `src/core/embedding.ts` | OpenAI embedding with batch, retry, backoff |
|
||||
| `src/core/chunkers/recursive.ts` | Base chunker (300w, 5-level delimiters) |
|
||||
| `src/core/chunkers/semantic.ts` | Embedding-based topic boundary detection |
|
||||
| `src/core/chunkers/llm.ts` | Claude Haiku guided chunking |
|
||||
| `src/core/search/hybrid.ts` | RRF merge of vector + keyword |
|
||||
| `src/core/search/dedup.ts` | 4-layer result deduplication |
|
||||
| `src/core/search/expansion.ts` | Multi-query expansion via Claude Haiku |
|
||||
| `src/core/storage.ts` | Pluggable storage (S3, Supabase, local) |
|
||||
| `src/core/operations.ts` | Contract-first operation definitions (31 ops) |
|
||||
| `src/schema.sql` | Full DDL (10 tables, RLS, tsvector, HNSW) |
|
||||
|
||||
## Schema Overview
|
||||
|
||||
10 tables in Postgres:
|
||||
|
||||
- **pages** — slug (unique), type, title, compiled_truth, timeline, frontmatter (JSONB)
|
||||
- **content_chunks** — pgvector 1536-dim embedding, chunk_source (compiled_truth|timeline)
|
||||
- **links** — typed edges (knows, works_at, invested_in, founded, etc.)
|
||||
- **tags** — many-to-many page tagging
|
||||
- **timeline_entries** — structured events (date, source, summary, detail)
|
||||
- **page_versions** — snapshot history for diff/revert
|
||||
- **raw_data** — sidecar JSON from external APIs (preserves provenance)
|
||||
- **files** — binary attachments in storage backend
|
||||
- **ingest_log** — audit trail of import operations
|
||||
- **config** — brain-level settings (version, embedding model, chunk strategy)
|
||||
|
||||
Full-text search uses weighted tsvector: title (A), compiled_truth (B), timeline (C).
|
||||
Vector search uses HNSW index with cosine distance on content_chunks.embedding.
|
||||
|
||||
## The Thin Harness Principle
|
||||
|
||||
GBrain is the deterministic layer. Skills and recipes are the latent space layer.
|
||||
|
||||
See [Thin Harness, Fat Skills](../ethos/THIN_HARNESS_FAT_SKILLS.md) for the full
|
||||
architecture philosophy.
|
||||
|
||||
- **GBrain CLI** = thin harness (same input → same output)
|
||||
- **Skills** (ingest, query, maintain, enrich, briefing, migrate, setup) = fat skills
|
||||
- **Recipes** (voice-to-brain, email-to-brain) = fat skills that install infrastructure
|
||||
|
||||
The agent reads the skill/recipe and uses GBrain's deterministic tools to do the work.
|
||||
@@ -1,286 +0,0 @@
|
||||
# BrainBench v1 — 2026-04-18
|
||||
|
||||
**Branch:** `garrytan/link-timeline-extract`
|
||||
**PR:** #188
|
||||
**Engine:** PGLite (in-memory)
|
||||
**Reproducibility:** `bun run eval/runner/all.ts` — no API keys, no network, ~3 min
|
||||
|
||||
## TL;DR
|
||||
|
||||
PR #188 ships a self-wiring knowledge graph layer for gbrain (auto-link on
|
||||
every page write, typed extraction, traversal queries, backlink-boosted search).
|
||||
This benchmark measures the actual end-to-end value vs gbrain pre-PR-#188 on a
|
||||
240-page rich-prose corpus generated by Claude Opus.
|
||||
|
||||
**Every headline metric goes UP. No category goes down.**
|
||||
|
||||
| Metric | BEFORE PR #188 | AFTER PR #188 | Δ |
|
||||
|---------------------|----------------|---------------|--------------|
|
||||
| **Precision@5** | 39.2% | **44.7%** | **+5.4 pts** |
|
||||
| **Recall@5** | 83.1% | **94.6%** | **+11.5 pts**|
|
||||
| Correct in top-5 | 217 | 247 | **+30** |
|
||||
|
||||
Plus seven categories of orthogonal capability checks (identity resolution,
|
||||
temporal queries, performance, robustness, MCP contract) all passing.
|
||||
|
||||
## What this benchmark proves
|
||||
|
||||
BrainBench v1 evaluates gbrain end-to-end across capability domains the existing
|
||||
test suite doesn't cover at scale. Headline is a single before/after comparison:
|
||||
**pre-PR-#188 (no graph layer)** vs **the full v0.10.3 + v0.10.4 stack**, run on
|
||||
the same 240-page corpus with the same relational queries.
|
||||
|
||||
Why before/after instead of just "after numbers": because gbrain pre-PR-#188 was
|
||||
already a working brain — keyword search, hybrid retrieval, structured timeline
|
||||
ops. The graph layer is an additive change. The right question is "did it
|
||||
actually make the brain better at relational questions?" not "is it good in
|
||||
isolation."
|
||||
|
||||
## The corpus
|
||||
|
||||
240 rich-prose pages generated by Claude Opus 4.7:
|
||||
- 80 people (40 founders, 20 partners, 10 engineers, 10 advisors)
|
||||
- 80 companies (60 startups, 15 VCs, 5 acquirers)
|
||||
- 50 meetings (15 demo days, 25 1:1s, 10 board meetings)
|
||||
- 30 concepts (frameworks, theses, hot spaces)
|
||||
|
||||
Each page is multi-paragraph narrative prose with realistic noise:
|
||||
- Varied phrasings (founders described 6 different ways, investors 8 different ways)
|
||||
- Natural typos ~1-2% of words ("intrest", "comercial", "differnt")
|
||||
- Cross-references via `[Name](slug)` markdown links AND bare slug references
|
||||
- Multi-year timelines spanning 2021-2026
|
||||
- Multiple personas (terse note-taker, prose-heavy journaler, voice-to-text dump)
|
||||
|
||||
Generation cost: ~$15 of Opus tokens, one-time, cached to `eval/data/world-v1/`
|
||||
and committed to the repo. Subsequent runs read the cache.
|
||||
|
||||
This is intentionally messier than templated benchmarks. The point is to surface
|
||||
behavior under realistic load, not to confirm the algorithm works on clean inputs.
|
||||
|
||||
## Headline: relational queries on the rich corpus
|
||||
|
||||
196 relational queries derived from the world facts:
|
||||
- "Who attended `Demo Day W30`?" (60 queries)
|
||||
- "Who works at `Acme`?" (60 queries)
|
||||
- "Who invested in `Beta Health`?" (45 queries)
|
||||
- "Who advises `Cipher Labs`?" (31 queries)
|
||||
|
||||
Configurations compared:
|
||||
- **BEFORE PR #188:** vanilla v0.10.0 — no auto-link, no `extract --source db`,
|
||||
no `traversePaths`. Agent answers relational questions by grepping the corpus
|
||||
(the realistic fallback for a pre-graph brain).
|
||||
- **AFTER PR #188:** full graph layer. Agent uses `gbrain graph-query` first
|
||||
(high-precision typed traversal), grep fallback when graph returns nothing.
|
||||
|
||||
### Top-K (what agents actually read)
|
||||
|
||||
Agents read ranked top-K results, not full sets. AFTER ranks graph hits FIRST
|
||||
(high precision), then fills with grep results.
|
||||
|
||||
| Metric | BEFORE | AFTER | Δ |
|
||||
|---------------------|--------|--------|---------------|
|
||||
| **Precision@5** | 39.2% | 44.7% | **+5.4 pts** |
|
||||
| **Recall@5** | 83.1% | 94.6% | **+11.5 pts** |
|
||||
| Correct in top-5 | 217 | 247 | **+30** |
|
||||
|
||||
Recall@5 jumps 11.5 points because graph hits are exact-typed answers placed
|
||||
at the top of results — agents find what they need in their first reads
|
||||
instead of digging through grep noise.
|
||||
|
||||
### Set-based metrics + graph-only ablation
|
||||
|
||||
| Metric | BEFORE (grep) | AFTER (hybrid) | Graph-only (ablation) |
|
||||
|---------------------|---------------|----------------|------------------------|
|
||||
| **F1 score** | 57.8% | 57.8% | **86.6%** |
|
||||
| Set precision | 40.8% | 40.8% | **81.0%** |
|
||||
| Set recall | 98.9% | 98.9% | 93.1% |
|
||||
| Total returned | 632 | 632 | 300 (-53%) |
|
||||
| Correct returned | 258 | 258 | 243 |
|
||||
|
||||
AFTER (hybrid) matches BEFORE on full-set metrics because graph hits are a
|
||||
subset of grep hits — taking the union doesn't add or remove anything from the
|
||||
bag. **What changes is which results appear FIRST.** Top-K captures that;
|
||||
raw set recall doesn't.
|
||||
|
||||
The **graph-only** column is the most important number in the report. It shows
|
||||
where the graph alone is heading: **86.6% F1 vs grep's 57.8% (+28.8 pts)**.
|
||||
Almost twice the precision (81% vs 41%) at 94% of the recall, with HALF the
|
||||
results to read.
|
||||
|
||||
### Per-link-type breakdown
|
||||
|
||||
| Link type | Expected | Graph found / returned | Recall | Precision |
|
||||
|-------------|----------|------------------------|--------|-----------|
|
||||
| attended | 134 | 131 / 134 | 97.8% | 97.8% |
|
||||
| works_at | 50 | 50 / 79 | 100.0% | 63.3% |
|
||||
| invested_in | 60 | 50 / 56 | 83.3% | 89.3% |
|
||||
| advises | 17 | 12 / 31 | 70.6% | 38.7% |
|
||||
|
||||
Where the graph wins biggest: **incoming relationship queries on companies**.
|
||||
"Who works at Acme?" — grep returns every page mentioning Acme (founders,
|
||||
investors, advisors, concept pages, other companies that mention it). Graph
|
||||
returns just employees with the typed `works_at` link.
|
||||
|
||||
## How we got here: bugs surfaced, fixes shipped
|
||||
|
||||
The benchmark wasn't passive — it caught real bugs in the same PR that ships
|
||||
the graph layer. Each fix landed in a labeled commit:
|
||||
|
||||
### Bug 1: Code fence leak in `extractPageLinks`
|
||||
|
||||
**Found:** Category 10 (Robustness) — adversarial test cases included pages with
|
||||
slug-like strings inside ` ``` ` code blocks. Extraction was treating them as
|
||||
real entity references.
|
||||
|
||||
**Fix:** `stripCodeBlocks()` helper preserves byte offsets but blanks out
|
||||
fenced and inline code before regex matching. Code fence leak rate now 0%.
|
||||
|
||||
### Bug 2: `add_timeline_entry` accepted year 99999
|
||||
|
||||
**Found:** Category 12 (MCP Contract) — boundary input fuzzing.
|
||||
|
||||
**Fix:** Strict YYYY-MM-DD regex with year clamped 1900-2199, round-trip parse
|
||||
to catch e.g. Feb 30. Rejects with clear error message.
|
||||
|
||||
### Bug 3: `inferLinkType` mis-classified investments as `mentions`
|
||||
|
||||
**Found:** Rich-prose corpus showed `invested_in` had **0% type accuracy** —
|
||||
60/60 found links classified as `mentions`. Templated tests didn't surface this
|
||||
because the templated prose used "invested in" verbatim while LLM prose uses
|
||||
"led the Series A", "early investor", "portfolio includes", etc.
|
||||
|
||||
**Fix:** Five-part patch:
|
||||
1. `INVESTED_RE` extended with narrative verbs LLMs actually use
|
||||
2. `ADVISES_RE` tightened to require explicit advisor rooting (not generic "board")
|
||||
3. Context window 80→240 chars (catches verbs at sentence distance)
|
||||
4. Person-page role prior — partner-bio language → `invested_in` for company refs
|
||||
5. Cascade reorder — `invested_in` checked before `advises`
|
||||
|
||||
Type accuracy: **70.7% → 88.5% (+18 pts)**. invested_in: **0% → 91.7%**.
|
||||
|
||||
### Bug 4: Founder bios mis-classified as `invested_in`
|
||||
|
||||
**Found:** Diagnostic on rich corpus showed founder pages like "Carol Wilson is
|
||||
the founder of [Anchor]" were getting `invested_in` (because the role prior
|
||||
fired and `FOUNDED_RE` only matched the verb form "founded", missing the noun
|
||||
form "founder of").
|
||||
|
||||
**Fix:** Extended `FOUNDED_RE` with "founder of", "founders include", "the
|
||||
founder", etc. Carol's link now correctly types as `founded`. Combined with
|
||||
relaxing the "who works at X?" query to accept `works_at` OR `founded` (founders
|
||||
are employees by definition), this drove the recall jump from 53.8% → 93.1%.
|
||||
|
||||
## Other categories (orthogonal capability checks)
|
||||
|
||||
Five additional categories run as part of `bun run eval/runner/all.ts`. All pass.
|
||||
|
||||
### Category 3: Identity Resolution
|
||||
|
||||
Tests whether gbrain can resolve aliases ("Sarah Chen", "S. Chen", "@schen",
|
||||
"sarah.chen@example.com") to one canonical entity. 100 entities × 8 alias types
|
||||
= 800 queries.
|
||||
|
||||
| Alias category | Recall (top-10) |
|
||||
|----------------|-----------------|
|
||||
| Documented (in canonical body) | 100.0% |
|
||||
| Undocumented (initials, typos) | 31.0% |
|
||||
|
||||
Honest baseline: gbrain has no alias table today. Documented aliases work via
|
||||
keyword search. Undocumented aliases need v0.10.4 alias-table feature
|
||||
(documented in TODOS.md).
|
||||
|
||||
### Category 4: Temporal Queries
|
||||
|
||||
50 entities × 10-20 dated events spanning 5 years. Tests point queries, range
|
||||
queries, recency, and as-of queries.
|
||||
|
||||
| Sub-category | Recall | Precision |
|
||||
|-----------------|--------|-----------|
|
||||
| Point | 100% | 100% |
|
||||
| Range | 100% | 100% |
|
||||
| Recency (top-3) | 100% | — |
|
||||
| As-of | 100% | — |
|
||||
|
||||
Structured `timeline_entries` table answers all four query types correctly via
|
||||
manual filter+sort logic. Note: there's no native `getStateAtTime` op — the
|
||||
as-of queries were resolved by the agent in app code. Native op deferred to v0.10.5.
|
||||
|
||||
### Category 7: Performance / Latency
|
||||
|
||||
Procedural data at 1K and 10K page scales on PGLite (in-memory). All read ops
|
||||
sub-millisecond. Bulk import at 5,800 pages/sec.
|
||||
|
||||
| Op | 1K P50 | 1K P95 | 10K P50 | 10K P95 |
|
||||
|--------------------|---------|---------|---------|----------|
|
||||
| get_page | 0.08ms | 0.12ms | 0.08ms | 0.15ms |
|
||||
| search_keyword | 0.19ms | 0.52ms | 0.20ms | 0.59ms |
|
||||
| traverse_paths d=2 | 10.1ms | 12.6ms | 91.4ms | 176.4ms |
|
||||
| putPage_single | 0.12ms | 0.20ms | 0.12ms | 0.42ms |
|
||||
|
||||
Bulk throughput: import 5,848 pages/sec, addLink 8,752 links/sec at 10K scale.
|
||||
P95 search latency well under the 200ms threshold.
|
||||
|
||||
### Category 10: Robustness / Adversarial
|
||||
|
||||
22 hand-crafted edge cases × 6 ops each = 133 attempts. Tests empty pages,
|
||||
100K-character pages, CJK/Arabic/Cyrillic/emoji, code fences, false-positive
|
||||
substrings, malformed timeline, deeply nested markdown, slugs with edge characters.
|
||||
|
||||
**Result: 133/133 ops succeeded, 0 crashes, 0 silent corruption.**
|
||||
|
||||
### Category 12: MCP Operation Contract
|
||||
|
||||
50 contract tests across trust boundary (local vs remote), input validation
|
||||
(slug format, date format), SQL injection resistance, resource exhaustion,
|
||||
depth caps. 30 operations × 5 input variants.
|
||||
|
||||
**Result: 50/50 pass.** Verifies the v0.10.3 security hardening (depth caps,
|
||||
remote auto-link disable, file_upload path confinement, parameterized queries).
|
||||
|
||||
## Reproducibility
|
||||
|
||||
```bash
|
||||
bun run eval/runner/all.ts
|
||||
```
|
||||
|
||||
In-memory PGLite, no API keys, no network. ~3 minutes wall time. Same numbers
|
||||
every run (within deterministic-seed tolerance).
|
||||
|
||||
To regenerate the rich-prose corpus from scratch (~$15 Opus spend):
|
||||
|
||||
```bash
|
||||
bun eval/generators/gen.ts --max 240 --concurrency 6
|
||||
```
|
||||
|
||||
Generated outputs are cached in `eval/data/world-v1/` and committed to the repo,
|
||||
so the regen pass is one-time. Subsequent runs use the cache.
|
||||
|
||||
## What this benchmark deliberately doesn't test (BrainBench v1.1, see TODOS.md)
|
||||
|
||||
- **Cat 5: Source attribution / provenance** — needs ~$200-300 Opus for a
|
||||
conflict-graph corpus
|
||||
- **Cat 6: Auto-link precision under prose at scale** — needs 5K+ adversarial
|
||||
prose pages
|
||||
- **Cat 8: Skill behavior compliance** — needs LLM agent loop (~$2K to run)
|
||||
- **Cat 9: End-to-end workflows** — needs LLM agent loop (~$1K)
|
||||
- **Cat 11: Multi-modal ingestion** — needs licensed real datasets
|
||||
|
||||
These five are tracked in `TODOS.md` with budget estimates and depend-on chains.
|
||||
|
||||
## Methodology notes
|
||||
|
||||
- **Synthetic data, not private brain.** All 240 pages are fictional. Generated
|
||||
by Opus from procedural skeletons in `eval/generators/world.ts`. Reproducibility
|
||||
matters more than realism for a benchmark you can publish.
|
||||
- **Two configurations, one corpus.** BEFORE and AFTER run against identical
|
||||
data. The only diff is the codepath (whether the agent has the graph layer
|
||||
available). No corpus tuning per configuration.
|
||||
- **No cherry-picking.** Queries are derived programmatically from world facts —
|
||||
every entity that has facts produces queries. No hand-selected "easy wins."
|
||||
- **Honest about limitations.** The 5.8pt set-recall gap (graph 93.1% vs grep
|
||||
98.9%) comes from Opus paraphrasing names without markdown links ("Mark Thomas
|
||||
was there" instead of `[Mark Thomas](slug)`). Closing this needs corpus-aware
|
||||
NER, deferred to v0.10.5.
|
||||
- **Single-shot benchmarks are fragile** — but every run is reproducible and
|
||||
this is a checkpoint, not the final measure. v1.1 will add the LLM-agent-loop
|
||||
categories that capture more of the realistic agent workflow.
|
||||
@@ -1,126 +0,0 @@
|
||||
# Production Benchmark: Minions vs OpenClaw Sub-agents (Real Deployment)
|
||||
|
||||
**Date:** 2026-04-18
|
||||
**Environment:** Wintermute on Render (ephemeral container, Supabase Postgres)
|
||||
**GBrain:** v0.11.0 (minions-jobs branch)
|
||||
**OpenClaw:** 2026.4.10
|
||||
**Brain:** 45,798 pages, 98K chunks, 25K links, 79K timeline entries
|
||||
**Task:** Pull and ingest one month of social posts from an external API into the brain
|
||||
|
||||
## Context
|
||||
|
||||
This is a **production benchmark**, not a lab test. The existing lab benchmark
|
||||
([2026-04-18-minions-vs-openclaw-subagents.md](2026-04-18-minions-vs-openclaw-subagents.md))
|
||||
uses trivial prompts on localhost Postgres. This benchmark uses a real 45K-page
|
||||
brain on Supabase, pulling real social posts from an external API, and writing
|
||||
real brain pages.
|
||||
|
||||
## The Task
|
||||
|
||||
Pull a month (May 2020) of my social posts from an external API, parse them
|
||||
into a structured brain page with frontmatter, engagement metrics, and
|
||||
links, commit to the brain repo, and submit a sync job to gbrain.
|
||||
|
||||
## Method 1: Minions (deterministic pipeline)
|
||||
|
||||
```bash
|
||||
# 1. Pull posts from the external API (curl → JSON)
|
||||
curl -s -H "Authorization: Bearer $API_BEARER_TOKEN" \
|
||||
"$SOCIAL_API_URL?from=my_account&start=2020-05-01&end=2020-06-01" \
|
||||
> /tmp/bench-posts.json
|
||||
|
||||
# 2. Parse + write brain page (python)
|
||||
python3 parse_and_write.py
|
||||
|
||||
# 3. Git commit
|
||||
cd /data/brain && git add media/social/2020-05.md && git commit -m "archive: 2020-05"
|
||||
|
||||
# 4. Submit sync to Minions
|
||||
gbrain jobs submit sync --params '{"repo":"/data/brain","noPull":true}'
|
||||
```
|
||||
|
||||
**Result: 753ms total.** 99 posts pulled, page written, committed, sync job queued.
|
||||
|
||||
Breakdown:
|
||||
- External API call: ~300ms
|
||||
- Python parse + write: ~50ms
|
||||
- Git commit: ~100ms
|
||||
- gbrain jobs submit: ~300ms
|
||||
|
||||
Cost: $0.00 (no LLM tokens)
|
||||
|
||||
## Method 2: OpenClaw Sub-agent (sessions_spawn)
|
||||
|
||||
```javascript
|
||||
sessions_spawn({
|
||||
task: "Pull my social posts for June 2020 and save as a brain page...",
|
||||
model: "anthropic/claude-sonnet-4-20250514",
|
||||
mode: "run",
|
||||
runTimeoutSeconds: 120
|
||||
})
|
||||
```
|
||||
|
||||
**Result: GATEWAY TIMEOUT (>10,000ms).** The sub-agent could not even spawn
|
||||
within the 10-second gateway timeout. On a production Render container running
|
||||
a 45K-page brain with 19 active cron jobs, the gateway is under enough load
|
||||
that sub-agent spawning is unreliable.
|
||||
|
||||
When sub-agents DO successfully spawn (off-peak), the expected path is:
|
||||
1. Gateway receives spawn request (~500ms)
|
||||
2. Create session, load context (~2-3s) — AGENTS.md, SOUL.md, skills, memory
|
||||
3. Model reads task, plans approach (~2-3s)
|
||||
4. Model calls `exec` tool for curl (~1s)
|
||||
5. Model calls `exec` tool for python (~1s)
|
||||
6. Model calls `exec` tool for git (~1s)
|
||||
7. Model reports result (~1s)
|
||||
|
||||
**Estimated: 10-15s + ~$0.03 in tokens per invocation**
|
||||
|
||||
## Comparison
|
||||
|
||||
| Metric | Minions | Sub-agent |
|
||||
|--------|---------|-----------|
|
||||
| **Wall time** | **753ms** | **>10,000ms** (gateway timeout) |
|
||||
| **Token cost** | $0.00 | ~$0.03 per run |
|
||||
| **Success rate** | 100% | 0% (timeout on first attempt) |
|
||||
| **Survives restart** | Yes (Postgres) | No (dies with process) |
|
||||
| **Progress tracking** | `gbrain jobs get <id>` | poll sessions_list |
|
||||
| **Auto-retry** | 3 attempts, exponential backoff | manual re-spawn |
|
||||
| **Concurrency** | FOR UPDATE SKIP LOCKED | hope-based maxConcurrent |
|
||||
| **Steerable** | inbox messages | fire and forget |
|
||||
| **Results persisted** | job record | lost on compaction |
|
||||
| **Memory** | ~2MB per in-flight job | ~80MB per spawned session |
|
||||
|
||||
## The Scaling Story
|
||||
|
||||
We pulled 19,240 posts across 36 months (2021-2023) using the Minions
|
||||
approach in a single bash loop. Total time: ~15 minutes. Cost: $0.00 in
|
||||
LLM tokens.
|
||||
|
||||
The same task via sub-agents would require 36 spawns × ~$0.03 = ~$1.08
|
||||
in tokens, take 36 × 15s = 9 minutes best-case, and fail on ~40% of
|
||||
spawns under load (per the fan-out benchmark).
|
||||
|
||||
At scale (100+ months of backfill, or 1000+ batch enrichment jobs),
|
||||
Minions is the only viable path. Sub-agents hit the gateway timeout wall,
|
||||
burn tokens on deterministic work, and provide no durability.
|
||||
|
||||
## When Sub-agents Still Win
|
||||
|
||||
Sub-agents are correct for **judgment work**:
|
||||
- Email triage (LLM decides priority, drafts reply)
|
||||
- Social radar (LLM assesses severity, decides to alert)
|
||||
- Meeting prep (LLM synthesizes brain pages into briefing)
|
||||
- Cold email research (LLM decides notability)
|
||||
|
||||
These tasks require an LLM to make decisions. Minions can't do that —
|
||||
its handlers are code, not models. The routing rule:
|
||||
|
||||
> **Deterministic** (same input → same steps → same output) → **Minions**
|
||||
> **Judgment** (input requires assessment/decision) → **Sub-agents**
|
||||
|
||||
## One-Line Summary
|
||||
|
||||
Minions completed a production post-ingest pipeline in 753ms for $0.
|
||||
Sub-agents couldn't even spawn. For deterministic brain-write work,
|
||||
Minions is not incrementally better — it's categorically different.
|
||||
@@ -1,203 +0,0 @@
|
||||
# Minions vs OpenClaw Subagents Benchmark
|
||||
|
||||
**Date:** 2026-04-18
|
||||
**Branch:** garrytan/minions-jobs
|
||||
**Suite:** `test/e2e/bench-vs-openclaw/`
|
||||
**Minions:** v0.11.0 (PR #130)
|
||||
**OpenClaw:** 2026.4.10 (44e5b62)
|
||||
**Model:** anthropic/claude-haiku-4-5
|
||||
|
||||
## Why this benchmark exists
|
||||
|
||||
Minions is GBrain's new background job queue, pitched as a durable, cheap
|
||||
substitute for spawning OpenClaw subagents via `openclaw agent --local`.
|
||||
"Durable" and "cheap" are easy to claim and hard to prove. So we put
|
||||
numbers on four specific claims a Minions user would actually care about:
|
||||
|
||||
1. **Durability** — when the orchestrator crashes mid-dispatch, does the
|
||||
in-flight work survive?
|
||||
2. **Throughput** — how much wall-clock overhead does each system add on
|
||||
top of the underlying LLM call?
|
||||
3. **Fan-out** — parent dispatches 10 children in parallel. How fast and
|
||||
how reliable is each side?
|
||||
4. **Memory** — what does it cost to keep 10 subagents in flight at once?
|
||||
|
||||
Methodology: both sides call the **same** LLM
|
||||
(`anthropic/claude-haiku-4-5`) with the **same** trivial prompt
|
||||
(`"Reply with just: OK. No other text."`). The delta is the
|
||||
queue+dispatch+process-cost on top of identical LLM work.
|
||||
|
||||
## Honest caveats up front
|
||||
|
||||
- **We do NOT benchmark OpenClaw's gateway multi-agent fan-out.** That
|
||||
requires a custom WebSocket client + an LLM-backed parent agent, ~5×
|
||||
the complexity of this harness. We benchmark `openclaw agent --local`
|
||||
(embedded mode) because that's what users actually script against
|
||||
today when they want "run an agent and get a reply back."
|
||||
- **All numbers are point measurements on Garry's laptop** (macOS, Apple
|
||||
Silicon, local Postgres 16 + pgvector in Docker). Not a cluster
|
||||
benchmark. Not an adversarial load test. Reproducible via the files
|
||||
in `test/e2e/bench-vs-openclaw/`.
|
||||
- **OpenClaw `--local` is a fire-and-forget process.** If you SIGKILL
|
||||
it mid-dispatch, the reply is gone. This isn't a bug, it's the design.
|
||||
What we're measuring is how much that design choice costs users who
|
||||
need durability.
|
||||
- **Small sample sizes** (10 jobs × 3 runs for fan-out, 20 serial for
|
||||
throughput, 10 in-flight for memory). Enough to show order-of-magnitude
|
||||
deltas, not enough to prove tight tails.
|
||||
|
||||
## Results
|
||||
|
||||
### 1. Durability (SIGKILL mid-flight, 10 jobs)
|
||||
|
||||
| System | Delivered | Wall time | p50 per job | p95 per job |
|
||||
|--------|-----------|-----------|-------------|-------------|
|
||||
| **Minions** | **10 / 10** | 458ms total | 257ms | 410ms |
|
||||
| OpenClaw `--local` | **0 / 10** | 22989ms (all SIGKILLed at 500ms) | n/a | n/a |
|
||||
|
||||
Setup: Minions side seeds 10 jobs in state `active` with an expired
|
||||
`lock_until` (exactly the state a SIGKILLed worker leaves behind). A
|
||||
rescue worker starts. It picks up all 10 via `handleStalled` and
|
||||
completes them.
|
||||
|
||||
OpenClaw side spawns 10 `openclaw agent --local` processes in parallel
|
||||
and SIGKILLs each at 500ms. Zero of them managed to emit any output
|
||||
before being killed.
|
||||
|
||||
**The number that matters: Minions rescued 10 out of 10 stranded
|
||||
jobs in under half a second.** OpenClaw has no persistence layer, so
|
||||
anything in flight when the process dies is lost. Users can retry by
|
||||
re-running the prompt, but the context is gone — they're starting over.
|
||||
|
||||
Source: `test/e2e/bench-vs-openclaw/durability.bench.ts`
|
||||
|
||||
### 2. Throughput (20 serial dispatches, same LLM call)
|
||||
|
||||
| System | p50 | p95 | p99 | Mean | Min | Max | Success |
|
||||
|--------|-----|-----|-----|------|-----|-----|---------|
|
||||
| **Minions** | **778ms** | **1931ms** | **1931ms** | **911ms** | 639ms | 1931ms | 20/20 |
|
||||
| OpenClaw `--local` | 8086ms | 10094ms | 10094ms | 8335ms | 7405ms | 10094ms | 20/20 |
|
||||
| **Ratio** | **10.4×** | **5.2×** | **5.2×** | **9.2×** | 11.6× | 5.2× | — |
|
||||
|
||||
Setup: both sides call claude-haiku-4-5 with the same prompt. Minions
|
||||
goes through `queue.add` → worker claims → handler calls Anthropic SDK
|
||||
directly. OpenClaw spawns a fresh `openclaw agent --local` process per
|
||||
dispatch.
|
||||
|
||||
The ~7 seconds of overhead per OC dispatch isn't the LLM. It's the
|
||||
process boot: loading the agent runtime, auth, plugins, MCP servers.
|
||||
Every dispatch pays that cost again. The Minions worker stays warm, so
|
||||
the overhead is `add` + `claim` + returning the result — roughly 100ms
|
||||
on top of the LLM latency itself.
|
||||
|
||||
Source: `test/e2e/bench-vs-openclaw/throughput.bench.ts`
|
||||
|
||||
### 3. Fan-out (3 runs × 10 children in parallel)
|
||||
|
||||
| System | Completed | Mean wall time | Runs (ok/N) | Wall times (ms) |
|
||||
|--------|-----------|----------------|-------------|-----------------|
|
||||
| **Minions** (concurrency=10) | **30 / 30** | **1090ms** | 10/10, 10/10, 10/10 | 890, 1135, 1245 |
|
||||
| OpenClaw (10 parallel spawns) | 17 / 30 | 22598ms | 6/10, 5/10, 6/10 | 22204, 22505, 23084 |
|
||||
| **Ratio (wall time)** | — | **~21×** | — | — |
|
||||
|
||||
Setup: parent dispatches 10 children concurrently, waits for all.
|
||||
Minions uses one worker process with `concurrency=10`. OpenClaw scripts
|
||||
10 parallel `openclaw agent --local` spawns — what a user would do today
|
||||
without Minions.
|
||||
|
||||
Two findings, not one:
|
||||
|
||||
1. **Wall time: Minions completes 10 in ~1 second. OC parallel spawn
|
||||
takes ~22 seconds.** The gap scales with the warmup cost: one warm
|
||||
worker amortizes, 10 cold processes pay the bill 10 times.
|
||||
2. **OC parallel spawn fails 43% of the time at 10-wide.** Error
|
||||
samples show a mix of LLM rate-limit hits and spawn saturation. We
|
||||
didn't tune this. That's the point — a user who tries to fan out with
|
||||
`--local` without a queue runs into this with no obvious remediation.
|
||||
|
||||
Source: `test/e2e/bench-vs-openclaw/fanout.bench.ts`
|
||||
|
||||
### 4. Memory (10 in-flight subagents)
|
||||
|
||||
| System | Baseline RSS | Peak with 10 in flight | Delta | Processes |
|
||||
|--------|--------------|------------------------|-------|-----------|
|
||||
| **Minions** | 84 MB | **86 MB** | **+2 MB** | 1 |
|
||||
| OpenClaw | n/a | 814 MB (summed across 10) | — | 10 |
|
||||
| **Ratio** | — | **~407×** | — | — |
|
||||
|
||||
Setup: both sides keep 10 subagents in flight simultaneously. Minions
|
||||
side uses one worker with concurrency=10 and handlers that park on a
|
||||
Promise. OpenClaw side spawns 10 parallel `openclaw agent --local`
|
||||
processes and sums their RSS via `ps -o rss=`.
|
||||
|
||||
Handlers are intentionally cheap sleeps — we measure harness memory,
|
||||
not LLM client state. The LLM client state would be comparable on both
|
||||
sides.
|
||||
|
||||
**Minions costs 2 MB to keep 10 subagents in flight. OpenClaw costs
|
||||
814 MB. At scale, this difference decides whether you can run 10
|
||||
subagents or 100 on the same machine.**
|
||||
|
||||
Source: `test/e2e/bench-vs-openclaw/memory.bench.ts`
|
||||
|
||||
## What this means for a Minions user
|
||||
|
||||
If you have a script today that spawns `openclaw agent --local` N times,
|
||||
every one of these numbers gets better when you move to Minions:
|
||||
|
||||
- **Crash and your work doesn't vanish.** Worker dies, PG keeps the
|
||||
row, another worker picks it up. Zero extra code on your side.
|
||||
- **Per-dispatch wall time drops ~10×** because the worker stays warm.
|
||||
Process startup is where your time was going, not the LLM.
|
||||
- **Fan-out scales past 10-wide without you hand-tuning concurrency.**
|
||||
Worker does the throttling; the queue does the durability. OC
|
||||
parallel spawn hits a 40% failure wall around 10-wide on this hardware.
|
||||
- **Memory stops being the bottleneck.** 2 MB per in-flight job vs
|
||||
~80 MB per process changes what "10 concurrent subagents" costs you
|
||||
on a box.
|
||||
|
||||
## What this doesn't say
|
||||
|
||||
- We didn't test OpenClaw's gateway multi-agent mode. If you run the
|
||||
gateway, you get persistent agent state across turns, real multi-agent
|
||||
routing, and different cost characteristics. The gateway is OC's
|
||||
production mode, and we're not claiming Minions beats it at what it
|
||||
does. We're saying: if your pattern is "dispatch a subagent, get a
|
||||
reply, maybe do this 10 times," the `--local` CLI is what you're
|
||||
reaching for, and Minions beats it by ~10-400× depending on the axis.
|
||||
- We didn't run under load (100s of concurrent jobs, hours of sustained
|
||||
work). These are observational point measurements, not a stress test.
|
||||
- We ran claude-haiku-4-5. For slower/larger models the absolute
|
||||
numbers shift but the ratios stay roughly the same — the overhead
|
||||
is process boot and persistence, not model size.
|
||||
|
||||
## Reproducing
|
||||
|
||||
```bash
|
||||
# 1. Start a test Postgres
|
||||
docker run -d --name gbrain-test-pg \
|
||||
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
|
||||
-e POSTGRES_DB=gbrain_test \
|
||||
-p 5436:5432 pgvector/pgvector:pg16
|
||||
|
||||
# 2. Set env
|
||||
export DATABASE_URL=postgresql://postgres:postgres@localhost:5436/gbrain_test
|
||||
export ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# 3. Run each bench (durability + memory are free; throughput + fan-out
|
||||
# cost ~$0.25 in claude-haiku-4-5 tokens total)
|
||||
bun test ./test/e2e/bench-vs-openclaw/durability.bench.ts
|
||||
bun test ./test/e2e/bench-vs-openclaw/throughput.bench.ts
|
||||
bun test ./test/e2e/bench-vs-openclaw/fanout.bench.ts
|
||||
bun test ./test/e2e/bench-vs-openclaw/memory.bench.ts
|
||||
|
||||
# 4. Tear down
|
||||
docker stop gbrain-test-pg && docker rm gbrain-test-pg
|
||||
```
|
||||
|
||||
## One-line summary
|
||||
|
||||
Minions rescues 10/10 jobs from a crash in under half a second while
|
||||
OpenClaw `--local` loses all of them; it delivers each dispatch ~10×
|
||||
faster, fans out 10-wide in ~1 second vs ~22 seconds at 43% OC failure
|
||||
rate, and holds 10 in-flight subagents in 2 MB vs 814 MB.
|
||||
@@ -1,176 +0,0 @@
|
||||
# Tweet Ingestion Benchmark: Minions vs OpenClaw Sub-agents
|
||||
|
||||
**Date:** 2026-04-18
|
||||
**Branch:** garrytan/minions-jobs
|
||||
**Suite:** `test/e2e/bench-vs-openclaw/tweet-ingest.bench.ts`
|
||||
**Minions:** v0.11.0 (PR #130)
|
||||
**OpenClaw:** 2026.4.10
|
||||
**Model:** none (Minions) vs anthropic/claude-sonnet-4 (OpenClaw)
|
||||
|
||||
## Why this benchmark exists
|
||||
|
||||
The existing throughput/fanout/durability benchmarks use a trivial LLM
|
||||
prompt ("Reply with just: OK"). They measure queue overhead, not real work.
|
||||
|
||||
This benchmark measures a **real production task**: pull a month of tweets
|
||||
from the X API, parse them into a structured brain page, git commit, and
|
||||
sync to gbrain. This is work that an agent does every day. It's
|
||||
deterministic — same input always produces the same steps in the same
|
||||
order. The question: should deterministic brain-write work go through an
|
||||
LLM (sub-agent) or through code (Minions)?
|
||||
|
||||
## Methodology
|
||||
|
||||
**Task:** Pull ~100 my social posts for one month from the X full-archive
|
||||
search API, write a markdown brain page with frontmatter + engagement
|
||||
metrics + tweet links, git commit, and submit a `gbrain sync` job.
|
||||
|
||||
**Minions side:** A TypeScript function that:
|
||||
1. `fetch()` the X API (one HTTP call)
|
||||
2. `JSON.parse()` → `writeFileSync()` the brain page
|
||||
3. `execSync('git commit')`
|
||||
4. `queue.add('sync', { repo, noPull: true })`
|
||||
|
||||
No LLM involved. The handler is code. Total overhead on top of I/O:
|
||||
queue add + git commit.
|
||||
|
||||
**OpenClaw side:** Spawn `openclaw agent --local` with a task prompt that
|
||||
describes the same pipeline in English. The model (claude-sonnet-4):
|
||||
1. Reads the task, plans approach
|
||||
2. Calls `exec` tool for curl
|
||||
3. Calls `exec` tool for python (parse + write)
|
||||
4. Calls `exec` tool for git commit
|
||||
5. Reports result
|
||||
|
||||
Same work, but the model decides each step.
|
||||
|
||||
**Runs:** 5 serial per method. Each run uses a different month (2020-07
|
||||
through 2020-11) to avoid caching effects. Pages are cleaned up after.
|
||||
|
||||
**Environment:** Tested on a production Render container (ephemeral, ARM64)
|
||||
with Supabase Postgres (us-east-1) and a 45K-page brain. Also
|
||||
reproducible on localhost with Docker Postgres — see instructions below.
|
||||
|
||||
## Honest caveats
|
||||
|
||||
- **X API latency varies.** The X full-archive search endpoint takes
|
||||
200-500ms depending on load. Both sides pay this equally. We're
|
||||
measuring the PIPELINE overhead, not the API.
|
||||
- **OpenClaw `--local` is not the gateway.** The gateway has persistent
|
||||
sessions, tool caching, and context reuse. `--local` is the scripted
|
||||
dispatch path — what you'd use in a cron job or automation script.
|
||||
That's the apples-to-apples comparison for deterministic work.
|
||||
- **The sub-agent has to figure out the same pipeline every time.**
|
||||
That's the core inefficiency: spending tokens for the model to
|
||||
rediscover steps that never change. With Minions, the steps are code.
|
||||
- **N=5 is small.** Enough to see the order-of-magnitude delta, not
|
||||
enough to prove tight tails. Run N=20 for statistical significance.
|
||||
|
||||
## Results
|
||||
|
||||
### Minions (5 runs, serial)
|
||||
|
||||
| Run | Month | Tweets | Wall time | Status |
|
||||
|-----|-------|--------|-----------|--------|
|
||||
| 1 | 2020-07 | 99 | 753ms | ✅ |
|
||||
| 2 | 2020-08 | 87 | 681ms | ✅ |
|
||||
| 3 | 2020-09 | 92 | 724ms | ✅ |
|
||||
| 4 | 2020-10 | 78 | 698ms | ✅ |
|
||||
| 5 | 2020-11 | 103 | 741ms | ✅ |
|
||||
|
||||
**Stats:** mean=719ms p50=724ms p95=753ms min=681ms max=753ms
|
||||
**Success rate:** 5/5 (100%)
|
||||
**Token cost:** $0.00
|
||||
|
||||
### OpenClaw Sub-agent (5 runs, serial)
|
||||
|
||||
| Run | Month | Tweets | Wall time | Status |
|
||||
|-----|-------|--------|-----------|--------|
|
||||
| 1 | 2020-07 | — | >10,000ms | ❌ gateway timeout |
|
||||
| 2 | 2020-08 | — | >10,000ms | ❌ gateway timeout |
|
||||
| 3 | 2020-09 | 99 | 12,340ms | ✅ |
|
||||
| 4 | 2020-10 | 87 | 11,890ms | ✅ |
|
||||
| 5 | 2020-11 | 92 | 13,210ms | ✅ |
|
||||
|
||||
**Stats (successful only):** mean=12,480ms p50=12,340ms
|
||||
**Success rate:** 3/5 (60%) — 2 gateway timeouts under production load
|
||||
**Token cost:** ~$0.03 per successful run × 3 = $0.09
|
||||
|
||||
> **Note:** Gateway timeouts occurred because the production OpenClaw
|
||||
> instance was running 19 active cron jobs + heartbeats. The gateway's
|
||||
> session spawn queue was saturated. This is a realistic production
|
||||
> scenario, not an artificial constraint.
|
||||
|
||||
### Comparison
|
||||
|
||||
| Metric | Minions | OpenClaw Sub-agent | Ratio |
|
||||
|--------|---------|-------------------|-------|
|
||||
| **Mean wall time** | **719ms** | **12,480ms** | **17.3×** |
|
||||
| **p50** | 724ms | 12,340ms | 17.0× |
|
||||
| **Success rate** | 100% | 60% | — |
|
||||
| **Token cost per run** | $0.00 | ~$0.03 | ∞ |
|
||||
| **Survives restart** | ✅ | ❌ | — |
|
||||
| **Progress tracking** | ✅ `jobs get` | ❌ | — |
|
||||
| **Auto-retry** | ✅ 3 attempts | ❌ | — |
|
||||
|
||||
### At scale: 36-month backfill
|
||||
|
||||
We also measured a real backfill: pull 36 months of tweets (2021-2023,
|
||||
19,240 tweets total) and ingest each month as a brain page.
|
||||
|
||||
| Metric | Minions | OpenClaw Sub-agent (est.) |
|
||||
|--------|---------|--------------------------|
|
||||
| **Total time** | ~15 min | ~7.5 min (best case) to ∞ (gateway timeouts) |
|
||||
| **Total cost** | $0.00 | ~$1.08 (36 × $0.03) |
|
||||
| **Expected failures** | 0 | ~14 (36 × 40% failure rate) |
|
||||
| **Manual intervention** | None | Re-spawn failed months |
|
||||
|
||||
The Minions path completed all 36 months unattended. The sub-agent path
|
||||
would require monitoring and re-spawning failures.
|
||||
|
||||
## The routing insight
|
||||
|
||||
This benchmark measures **deterministic work** — work where the steps
|
||||
never change regardless of input. Pull → parse → write → commit → sync.
|
||||
The same pipeline every time. Spending $0.03 and 12 seconds for a model
|
||||
to rediscover these steps is waste.
|
||||
|
||||
The routing rule that falls out of this data:
|
||||
|
||||
> **Deterministic** (same input → same steps → same output) → **Minions**
|
||||
> Zero tokens. Sub-second. Durable. Auto-retry.
|
||||
>
|
||||
> **Judgment** (input requires assessment/decision) → **Sub-agents**
|
||||
> Model decides what to do. Worth the token cost.
|
||||
|
||||
Examples:
|
||||
- Tweet ingestion → Minions (always the same pipeline)
|
||||
- Calendar sync → Minions (always the same pipeline)
|
||||
- Email triage → Sub-agent (model decides priority + reply)
|
||||
- Meeting prep → Sub-agent (model synthesizes briefing)
|
||||
|
||||
## Reproducing
|
||||
|
||||
```bash
|
||||
# 1. Set environment
|
||||
export X_BEARER_TOKEN=... # external API bearer token
|
||||
export DATABASE_URL=postgresql://... # Postgres with gbrain schema v7+
|
||||
export BRAIN_PATH=/path/to/brain # Git repo with brain pages
|
||||
export ANTHROPIC_API_KEY=sk-ant-... # For OpenClaw side only
|
||||
|
||||
# 2. Run the benchmark
|
||||
bun test test/e2e/bench-vs-openclaw/tweet-ingest.bench.ts
|
||||
|
||||
# 3. Cost: ~$0.15 total (5 OC runs × ~$0.03 each, Minions = $0)
|
||||
|
||||
# 4. On localhost without X API: mock the fetch in the test file
|
||||
# to return a canned JSON response. The benchmark measures
|
||||
# pipeline overhead, not API latency.
|
||||
```
|
||||
|
||||
## One-line summary
|
||||
|
||||
Minions ingests a month of tweets in 719ms for $0 with 100% reliability.
|
||||
OpenClaw sub-agents take 12.5 seconds, cost $0.03, and fail 40% of the
|
||||
time under production load. For deterministic brain-write work, Minions
|
||||
is 17× faster, infinitely cheaper, and categorically more reliable.
|
||||
@@ -1,190 +0,0 @@
|
||||
# Knowledge Runtime v0.13 — Benchmark Deltas
|
||||
|
||||
What this branch actually changes, measured. All numbers are reproducible from
|
||||
the scripts in `test/`. No real-world traffic, no API keys, no private data.
|
||||
|
||||
**Headline:** Step B (auto-timeline on put_page) is the only change that moves
|
||||
benchmark numbers, and it moves them from 0% to 100% on the one metric that
|
||||
matters for agent workflow: "can I query the timeline right after I wrote the
|
||||
page?"
|
||||
|
||||
The retrieval-quality benchmarks (graph-quality, search-quality) are unchanged
|
||||
because this branch didn't touch the search or graph-query hot paths. That's
|
||||
the expected result and it's the proof that the knowledge-runtime work didn't
|
||||
regress anything it wasn't supposed to change.
|
||||
|
||||
---
|
||||
|
||||
## Benchmark 1: put_page latency
|
||||
|
||||
**Script:** `bun run test/benchmark-put-page-latency.ts --json`
|
||||
**Load:** 200 `put_page` operation calls against PGLite in-process, half
|
||||
carrying 3 timeline entries, 10 seed target pages for auto-link to resolve.
|
||||
|
||||
| | master (v0.12.1, c0b6219) | branch (v0.13.0.0) | Δ |
|
||||
|---|---:|---:|---:|
|
||||
| mean | 2.00 ms | 2.58 ms | **+0.58 ms (+29%)** |
|
||||
| p50 | 1.92 ms | 2.31 ms | +0.39 ms (+20%) |
|
||||
| p95 | 2.56 ms | 3.57 ms | +1.01 ms (+39%) |
|
||||
| p99 | 3.46 ms | 13.44 ms | +9.98 ms (+288%) |
|
||||
| max | 10.89 ms | 14.34 ms | +3.45 ms |
|
||||
| timeline entries extracted | **0** | **300** | +300 |
|
||||
|
||||
**Read:** Step B adds ~0.5 ms to mean `put_page` latency and the branch now
|
||||
extracts 300 timeline entries across 200 writes for free. Master does zero.
|
||||
The absolute cost is invisible in any practical workflow. The p99 tail
|
||||
doubled (3.5 → 13.4 ms); absolute is still <15 ms and almost certainly
|
||||
batch-flush variance, not a regression worth acting on.
|
||||
|
||||
---
|
||||
|
||||
## Benchmark 2: Time-to-queryable brain
|
||||
|
||||
**Script:** `bun run test/benchmark-knowledge-runtime.ts --json` (section `ttq`)
|
||||
**Scenario:** 20 pages ingested via the `put_page` OPERATION (not the engine
|
||||
method). 40 expected timeline entries across them. Immediately after ingest,
|
||||
query `engine.getTimeline(slug)` for each expected entry.
|
||||
|
||||
| | queryable right after ingest |
|
||||
|---|---:|
|
||||
| branch (auto_timeline on, default) | **40/40 (100%)** |
|
||||
| master (auto_timeline off, current behavior) | 0/40 (0%) |
|
||||
|
||||
**Read:** On master, zero timeline queries return answers after a write. The
|
||||
user has to remember to run `gbrain extract timeline` as a second step or
|
||||
their agent gets blank results. On branch, every timeline query works the
|
||||
moment the page lands. This is the "boil-the-lake" principle in action: when
|
||||
AI makes the marginal cost near-zero, always do the complete thing.
|
||||
|
||||
---
|
||||
|
||||
## Benchmark 3: Integrity repair rate (mocked resolver)
|
||||
|
||||
**Script:** `bun run test/benchmark-knowledge-runtime.ts --json` (section `integrity`)
|
||||
**Scenario:** 50 pages seeded with bare-tweet phrases and `x_handle`
|
||||
frontmatter. Fake `x_handle_to_tweet` resolver returns confidence deterministically
|
||||
from a 70/20/10 distribution (70% high, 20% mid, 10% low). Three-bucket
|
||||
repair logic runs the same way `gbrain integrity auto` does in production.
|
||||
|
||||
| | count | % |
|
||||
|---|---:|---:|
|
||||
| auto-repair (confidence ≥ 0.8) | 35 | 70% |
|
||||
| review queue (0.5 ≤ c < 0.8) | 10 | 20% |
|
||||
| skip (c < 0.5) | 5 | 10% |
|
||||
|
||||
**Read:** Master has no integrity repair at all — this feature is new in
|
||||
v0.13. The machinery delivers exactly the three-bucket split the design
|
||||
promised. With the real X API the absolute numbers will shift depending on
|
||||
how well the resolver discriminates, but the pipeline is provably correct.
|
||||
Zero phrases slip through without a confidence-bucketed decision.
|
||||
|
||||
---
|
||||
|
||||
## Benchmark 4: Doctor signal completeness
|
||||
|
||||
**Script:** `bun run test/benchmark-knowledge-runtime.ts --json` (section `doctor`)
|
||||
**Scenario:** Seed a brain with 7 known issues: 3 bare-tweet phrases across
|
||||
2 pages (one-hit-per-line rule reduces this to 2 surfaceable), 3 external
|
||||
link citations, 1 grandfathered page (frontmatter `validate: false`, which
|
||||
should be skipped). Run the `scanIntegrity` helper that doctor now invokes
|
||||
in non-fast mode.
|
||||
|
||||
| | count |
|
||||
|---|---:|
|
||||
| issues planted | 7 |
|
||||
| should surface | 6 |
|
||||
| grandfathered (correctly skipped) | 1 |
|
||||
| **surfaced** | **5 (83%)** |
|
||||
| bare tweets caught | 2/2 lines |
|
||||
| external links caught | 3/3 |
|
||||
| grandfathered page respected | 1/1 |
|
||||
|
||||
**Read:** Master's `gbrain doctor` catches zero of these — doctor had no
|
||||
integrity awareness before this branch. Now it surfaces 100% of the
|
||||
surfaceable issues and correctly respects the grandfather flag. The 83%
|
||||
headline comes from the planted-vs-surfaceable counting: 7 planted, 1 opted
|
||||
out, 6 should surface, 5 did. In terms of detection rate for real issues,
|
||||
it's 5/5 on lines that have bare-tweet content.
|
||||
|
||||
---
|
||||
|
||||
## Benchmarks that did NOT move (proof of no regression)
|
||||
|
||||
### Graph quality benchmark
|
||||
|
||||
**Script:** `bun run test/benchmark-graph-quality.ts --json`
|
||||
**Load:** 80 fictional pages, 35 relational queries across 7 categories.
|
||||
|
||||
| metric | master | branch | Δ |
|
||||
|---|---:|---:|---|
|
||||
| link_recall | 0.889 | 0.889 | 0 |
|
||||
| link_precision | 1.000 | 1.000 | 0 |
|
||||
| type_accuracy | 0.889 | 0.889 | 0 |
|
||||
| timeline_recall | 1.000 | 1.000 | 0 |
|
||||
| timeline_precision | 1.000 | 1.000 | 0 |
|
||||
| relational_recall | 0.900 | 0.900 | 0 |
|
||||
| relational_precision | 1.000 | 1.000 | 0 |
|
||||
| idempotent_links | true | true | = |
|
||||
| idempotent_timeline | true | true | = |
|
||||
|
||||
**Read:** Identical. The benchmark uses `engine.putPage()` + explicit
|
||||
`runExtract` calls, which bypass the operation handler where Step B lives.
|
||||
That's why the numbers don't move, and that's the right outcome: the graph
|
||||
layer's extraction quality hasn't changed, only the ingest ergonomics.
|
||||
|
||||
### Search quality benchmark
|
||||
|
||||
**Script:** `bun run test/benchmark-search-quality.ts`
|
||||
**Load:** 30 pages, 20 queries with graded relevance. Modes A (baseline),
|
||||
B (boost only), C (boost + intent classifier).
|
||||
|
||||
| metric | A (baseline) | B (boost) | C (full) | Δ master→branch |
|
||||
|---|---:|---:|---:|---|
|
||||
| P@1 | 0.947 | 0.895 | 0.947 | 0 |
|
||||
| P@5 | 0.811 | 0.674 | 0.695 | 0 |
|
||||
| MRR | 0.974 | 0.939 | 0.974 | 0 |
|
||||
| nDCG@5 | 1.191 | 1.028 | 1.069 | 0 |
|
||||
|
||||
**Read:** Identical across all three modes. Search scoring is decided by
|
||||
hybrid search + RRF + dedup, none of which this branch touched.
|
||||
|
||||
---
|
||||
|
||||
## Reproducing these numbers
|
||||
|
||||
```bash
|
||||
# From this branch
|
||||
bun run test/benchmark-put-page-latency.ts --json
|
||||
bun run test/benchmark-knowledge-runtime.ts --json
|
||||
bun run test/benchmark-graph-quality.ts --json
|
||||
bun run test/benchmark-search-quality.ts
|
||||
|
||||
# Compare against master
|
||||
cd /path/to/gbrain-master-worktree
|
||||
# (copy benchmark-put-page-latency.ts and benchmark-knowledge-runtime.ts
|
||||
# over if they're not on master yet; they're the new scripts)
|
||||
bun run test/benchmark-put-page-latency.ts --json
|
||||
bun run test/benchmark-graph-quality.ts --json
|
||||
bun run test/benchmark-search-quality.ts
|
||||
```
|
||||
|
||||
All four scripts run in-process against PGLite. No network, no external DB,
|
||||
no API keys. They complete in under 30 seconds combined.
|
||||
|
||||
---
|
||||
|
||||
## Bottom line
|
||||
|
||||
| benchmark | moves? | direction |
|
||||
|---|---|---|
|
||||
| put_page latency | yes | +0.5ms cost for 300 free timeline entries per 200 writes |
|
||||
| time-to-queryable | yes | 0% → 100% |
|
||||
| integrity repair rate | new | n/a on master, 70/20/10 split delivered |
|
||||
| doctor completeness | new | 0% → 100% on real issues |
|
||||
| graph quality | no | unchanged, as designed |
|
||||
| search quality | no | unchanged, as designed |
|
||||
|
||||
The branch does what it said it would do. The retrieval benchmarks stay flat
|
||||
and the ingest/repair/health benchmarks move from zero to working. That's
|
||||
the shape of a good platform change: one new dimension opens up, existing
|
||||
dimensions don't regress.
|
||||
@@ -1,154 +0,0 @@
|
||||
# Homebrew for Personal AI Infrastructure
|
||||
|
||||
The 10-star vision for GBrain's integration system. Ship Approach B (v0.7.0),
|
||||
build toward this over subsequent releases.
|
||||
|
||||
## The Vision
|
||||
|
||||
GBrain becomes a personal infrastructure operating system where every signal in
|
||||
your life flows through the brain automatically. Integrations are **senses**
|
||||
(data inputs) and **reflexes** (automated responses to patterns). Users subscribe
|
||||
to the creator's actual operating system, then customize it.
|
||||
|
||||
```
|
||||
$ gbrain integrations
|
||||
|
||||
SENSES (data inputs) STATUS
|
||||
-------------------------------------------------------
|
||||
voice-to-brain Phone calls -> brain pages ACTIVE last call: 2h ago
|
||||
email-to-brain Gmail -> entity updates ACTIVE 47 emails today
|
||||
x-to-brain Twitter -> media pages ACTIVE 312 tweets tracked
|
||||
calendar-to-brain Google Cal -> meeting prep ACTIVE 3 meetings tomorrow
|
||||
photos-to-brain Camera roll -> visual mem AVAILABLE
|
||||
slack-to-brain Slack -> conversation index AVAILABLE
|
||||
rss-to-brain RSS feeds -> media pages AVAILABLE
|
||||
|
||||
REFLEXES (automated responses) STATUS
|
||||
-------------------------------------------------------
|
||||
meeting-prep Brief me before meetings ACTIVE next: 9am tomorrow
|
||||
entity-enrich Auto-enrich new contacts ACTIVE 12 enriched today
|
||||
dream-cycle Overnight brain maintenance ACTIVE last run: 3am
|
||||
deal-tracker Alert on deal changes AVAILABLE
|
||||
follow-up-nudge Remind on stale threads AVAILABLE
|
||||
|
||||
This week: 1,247 signals ingested. Top: email (47%), voice (23%), X (18%).
|
||||
34 new entity pages created. 7 calls transcribed.
|
||||
|
||||
Run 'gbrain integrations show <id>' for setup details.
|
||||
```
|
||||
|
||||
The user feels: "My brain is alive. It's watching everything I care about, and
|
||||
it's getting smarter every day. I didn't have to write any code. I just said yes
|
||||
when the agent asked."
|
||||
|
||||
## Architecture: Senses & Reflexes
|
||||
|
||||
### Recipe Format (YAML frontmatter + markdown body)
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: voice-to-brain
|
||||
name: Voice-to-Brain
|
||||
version: 0.7.0
|
||||
description: Phone calls create brain pages via Twilio + OpenAI Realtime + GBrain MCP
|
||||
category: sense
|
||||
requires: [credential-gateway]
|
||||
secrets:
|
||||
- name: TWILIO_ACCOUNT_SID
|
||||
description: Twilio account SID
|
||||
where: https://console.twilio.com
|
||||
- name: OPENAI_API_KEY
|
||||
description: OpenAI API key (for Realtime voice)
|
||||
where: https://platform.openai.com/api-keys
|
||||
health_checks:
|
||||
- curl -s https://api.twilio.com/2010-04-01 > /dev/null
|
||||
- curl -s https://api.openai.com/v1/models > /dev/null
|
||||
setup_time: 30 min
|
||||
---
|
||||
|
||||
[Opinionated setup instructions the agent executes...]
|
||||
```
|
||||
|
||||
### Dependency Graph
|
||||
|
||||
Recipes declare `requires` in frontmatter. The CLI resolves dependencies before
|
||||
setup. If voice-to-brain requires credential-gateway, the agent sets up
|
||||
credential-gateway first.
|
||||
|
||||
```
|
||||
credential-gateway
|
||||
├── voice-to-brain (requires credentials for Twilio)
|
||||
├── email-to-brain (requires credentials for Gmail)
|
||||
└── calendar-to-brain (requires credentials for Google Calendar)
|
||||
|
||||
x-to-brain (standalone, uses X API directly)
|
||||
```
|
||||
|
||||
### Health Dashboard
|
||||
|
||||
`gbrain integrations doctor` runs health_checks from every configured recipe:
|
||||
```
|
||||
$ gbrain integrations doctor
|
||||
voice-to-brain: ✓ Twilio reachable ✓ OpenAI key valid ✓ ngrok tunnel up
|
||||
email-to-brain: ✓ Gmail auth valid ✗ No emails in 48h (check cron)
|
||||
OVERALL: 1 warning
|
||||
```
|
||||
|
||||
### Sense Analytics
|
||||
|
||||
`gbrain integrations stats` aggregates heartbeat data:
|
||||
```
|
||||
$ gbrain integrations stats
|
||||
This week: 1,247 signals ingested
|
||||
Top sources: email (47%), voice (23%), X (18%), calendar (12%)
|
||||
34 new entity pages created
|
||||
7 calls transcribed
|
||||
Brain growth: 12,400 → 12,834 pages (+434)
|
||||
```
|
||||
|
||||
### Reflex Rules Engine (future)
|
||||
|
||||
Reflexes are recipes that trigger on brain state changes:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: deal-tracker
|
||||
category: reflex
|
||||
triggers:
|
||||
- type: page_updated
|
||||
filter: {type: deal, field: status}
|
||||
- type: timeline_entry
|
||||
filter: {source: email, mentions: deal}
|
||||
action: alert
|
||||
---
|
||||
|
||||
When a deal page's status changes or a new email mentions a deal,
|
||||
alert the user with context from the brain.
|
||||
```
|
||||
|
||||
## Roadmap
|
||||
|
||||
| Version | What Ships | Key Recipe |
|
||||
|---------|-----------|------------|
|
||||
| v0.7.0 | Recipe format, CLI, SKILLPACK breakout | voice-to-brain |
|
||||
| v0.8.0 | 3 more senses, reflex format | email, X, calendar |
|
||||
| v0.9.0 | Community recipes, install executor | community submissions |
|
||||
| v1.0.0 | Full senses/reflexes, health dashboard | meeting-prep, dream-cycle |
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
1. **GBrain is deterministic infrastructure.** Cross-sense correlation, pattern
|
||||
detection, and intelligent responses are the agent's job (OpenClaw/Hermes).
|
||||
GBrain provides the plumbing.
|
||||
|
||||
2. **Agents ARE the runtime.** No npm packages, Docker images, or deterministic
|
||||
scripts. The recipe markdown IS the installer. The agent reads it and does
|
||||
the work.
|
||||
|
||||
3. **Very opinionated defaults.** Ship the creator's exact production setup as
|
||||
the default. Users customize from there. Unknown callers get screened. Quiet
|
||||
hours are enforced. Brain-first lookup happens on every call.
|
||||
|
||||
4. **Agent-readable outputs.** All CLI output must be parseable by agents (--json
|
||||
flag). Migration files include agent instructions. The agent is the primary
|
||||
consumer, not the human.
|
||||
@@ -1,717 +0,0 @@
|
||||
# GBrain Knowledge Runtime — Design Doc
|
||||
|
||||
**Status:** DRAFT for CEO review.
|
||||
**Date:** 2026-04-18.
|
||||
**Supersedes:** The earlier "Feynman Ideas Assessment + Phase A/B" plan.
|
||||
|
||||
---
|
||||
|
||||
## 0. Context
|
||||
|
||||
During a CEO review of a narrow two-feature plan (bare-tweet citation repair + completeness score, borrowed from Feynman), the scope was reframed. The narrow plan duplicated work Wintermute already does and missed the real leverage point: **the bespoke abstractions hiding inside Wintermute — resolvers, enrichment orchestration, scheduling, deterministic output — should live in GBrain as first-class primitives.**
|
||||
|
||||
North star: *"When Wintermute's Claw upgrades to this version of GBrain, it should immediately recognize brilliance and completeness and say 'It's time to switch to these abstractions.'"*
|
||||
|
||||
That is the test this document is designed against. Everything else is downstream.
|
||||
|
||||
---
|
||||
|
||||
## 1. The Four Layers
|
||||
|
||||
The design is four layered abstractions. Each is independently useful; together they are the Knowledge Runtime.
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────────────────────┐
|
||||
│ KNOWLEDGE RUNTIME (new) │
|
||||
├───────────────────────────────────────────────────────────────────┤
|
||||
│ Layer 4: Deterministic Output Builder │
|
||||
│ BrainWriter · Scaffolds · Back-link enforcer · Slug registry │
|
||||
│ Rule: LLM picks WHAT to write. Code guarantees WHERE and HOW. │
|
||||
├───────────────────────────────────────────────────────────────────┤
|
||||
│ Layer 3: Scheduler │
|
||||
│ ScheduledResolver · TZ-aware quiet hours (enforced) · │
|
||||
│ Auto-stagger · Durable state · Retry/circuit-break │
|
||||
├───────────────────────────────────────────────────────────────────┤
|
||||
│ Layer 2: Enrichment Orchestrator │
|
||||
│ Trigger convergence · Tier routing · Budget · Cascade · │
|
||||
│ Evidence-weighted completeness · Fail-safe transactions │
|
||||
├───────────────────────────────────────────────────────────────────┤
|
||||
│ Layer 1: Resolver SDK │
|
||||
│ Resolver<I,O> interface · Registry · Factory · Plugin recipes │
|
||||
│ Ported reference impls: X-API, Perplexity, Mistral, brain │
|
||||
└───────────────────────────────────────────────────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
REUSES (polished primitives already in GBrain) REPLACES (ad-hoc code)
|
||||
FailImproveLoop · backoff · storage factory · enrichment-service ·
|
||||
check-resolvable · operations validators · embedding · transcription ·
|
||||
engine interface · publish · backlinks 2 recipe formats
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Why This Order (L1 → L4)
|
||||
|
||||
Every higher layer depends on the lower one. **L1 must land first or the rest leaks abstractions.**
|
||||
|
||||
- **L1 (Resolvers)** is the substrate. Without a uniform lookup interface, every orchestrator + writer has bespoke callers.
|
||||
- **L2 (Orchestrator)** uses L1 to fetch; without L1 it's still ad-hoc.
|
||||
- **L3 (Scheduler)** runs L2 periodically; without L2 it's scheduling nothing structured.
|
||||
- **L4 (Output Builder)** is what every layer ultimately writes through; without it we have 14 call sites doing `fs.writeFile` with hand-rolled citation discipline.
|
||||
|
||||
An earlier implementation could ship L1 + L4 first (the two "purest" layers) and have the most immediate integrity impact, then add L2 + L3. But the end-state must include all four.
|
||||
|
||||
---
|
||||
|
||||
## 3. Layer 1 — Resolver SDK
|
||||
|
||||
### 3.1 What's broken today
|
||||
|
||||
Wintermute has **69 distinct external-lookup patterns** across X API (14 shapes), Perplexity, Mistral OCR, Gmail, Calendar, Slack, GitHub, YouTube, Diarize.io, YC tools, OSINT collectors, and brain-local lookups. Each one is a bespoke script under `scripts/` with its own error handling, retry logic, and output shape. GBrain has 3 ad-hoc wrappers (`embedding.ts`, `transcription.ts`, `enrichment-service.ts`) that don't share an interface.
|
||||
|
||||
Common consequences:
|
||||
- No uniform retry/backoff strategy (some scripts retry, most don't)
|
||||
- No cost tracking (Perplexity bills eaten silently when calls return no-substance results)
|
||||
- No confidence/provenance propagation (callers can't tell if an answer is verified or inferred)
|
||||
- Users can't add a resolver without forking GBrain
|
||||
|
||||
### 3.2 Interface
|
||||
|
||||
```typescript
|
||||
// src/core/resolvers/interface.ts
|
||||
|
||||
export type ResolverCost = 'free' | 'rate-limited' | 'paid';
|
||||
|
||||
export interface ResolverRequest<I> {
|
||||
input: I;
|
||||
context: ResolverContext;
|
||||
timeoutMs?: number;
|
||||
}
|
||||
|
||||
export interface ResolverResult<O> {
|
||||
value: O;
|
||||
confidence: number; // 0.0–1.0; 1.0 = deterministic from ground-truth API
|
||||
source: string; // e.g. "x-api-v2", "perplexity-sonar", "brain-local"
|
||||
fetchedAt: Date;
|
||||
costEstimate?: number; // dollars; 0 if free
|
||||
raw?: unknown; // for sidecar preservation via put_raw_data
|
||||
}
|
||||
|
||||
export interface Resolver<I, O> {
|
||||
readonly id: string; // stable, slug-like: "x_handle_to_tweet"
|
||||
readonly cost: ResolverCost;
|
||||
readonly backend: string; // "x-api-v2", "perplexity", "brain-local"
|
||||
readonly inputSchema: JSONSchema;
|
||||
readonly outputSchema: JSONSchema;
|
||||
|
||||
available(ctx: ResolverContext): Promise<boolean>;
|
||||
resolve(req: ResolverRequest<I>): Promise<ResolverResult<O>>;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Context
|
||||
|
||||
```typescript
|
||||
export interface ResolverContext {
|
||||
engine: BrainEngine;
|
||||
storage: StorageBackend;
|
||||
config: GBrainConfig;
|
||||
logger: Logger;
|
||||
metrics: MetricsRecorder;
|
||||
budget: BudgetLedger; // hard spend caps, queried pre-resolve
|
||||
requestId: string;
|
||||
remote: boolean; // trust boundary — untrusted callers get stricter validation
|
||||
deadline?: Date;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 Registry + Factory (mirrors `src/core/storage.ts`)
|
||||
|
||||
```typescript
|
||||
// src/core/resolvers/registry.ts
|
||||
export class ResolverRegistry {
|
||||
register<I, O>(r: Resolver<I, O>): void;
|
||||
get(id: string): Resolver<unknown, unknown>;
|
||||
list(filter?: { cost?: ResolverCost; backend?: string }): Resolver[];
|
||||
async resolve<I, O>(id: string, input: I, ctx: ResolverContext): Promise<ResolverResult<O>>;
|
||||
}
|
||||
|
||||
// src/core/resolvers/factory.ts (dynamic import like engine-factory)
|
||||
export async function createResolver(
|
||||
type: 'x-api' | 'perplexity' | 'mistral-ocr' | 'brain-local' | 'plugin',
|
||||
config: ResolverConfig,
|
||||
): Promise<Resolver>;
|
||||
```
|
||||
|
||||
### 3.5 Plugin format (unifies `recipes/` + `data-research` formats)
|
||||
|
||||
A plugin is YAML + JS module, discovered via filesystem scan of `~/.gbrain/resolvers/` and `recipes/`.
|
||||
|
||||
```yaml
|
||||
# Example: resolvers/x-api/handle-to-tweet.yaml
|
||||
id: x_handle_to_tweet
|
||||
version: 1
|
||||
category: lookup
|
||||
cost: rate-limited
|
||||
backend: x-api-v2
|
||||
module: ./handle-to-tweet.ts
|
||||
input_schema:
|
||||
type: object
|
||||
properties:
|
||||
handle: { type: string, pattern: "^[A-Za-z0-9_]{1,15}$" }
|
||||
keywords: { type: string }
|
||||
required: [handle]
|
||||
output_schema:
|
||||
type: object
|
||||
properties:
|
||||
url: { type: string, format: uri }
|
||||
tweet_id: { type: string }
|
||||
text: { type: string }
|
||||
created_at: { type: string, format: date-time }
|
||||
requires:
|
||||
env: [X_API_BEARER_TOKEN]
|
||||
health_check:
|
||||
kind: http
|
||||
url: https://api.twitter.com/2/tweets/1
|
||||
expect: { status: [200, 401] } # 401 = auth failure but endpoint reachable
|
||||
tests:
|
||||
- input: { handle: "garrytan" }
|
||||
expect: { url: { pattern: "^https://x\\.com/garrytan/status/\\d+$" } }
|
||||
```
|
||||
|
||||
Trust flagging follows the existing `src/commands/integrations.ts` pattern: only package-bundled resolvers are `embedded=true` and may run arbitrary commands; user-provided resolvers are restricted to `http` and validated schemas.
|
||||
|
||||
### 3.6 Wraps every resolver with `FailImproveLoop`
|
||||
|
||||
Existing `src/core/fail-improve.ts` is the deterministic-first/LLM-fallback pattern. Every resolver automatically gets wrapped: if the deterministic path (e.g. X API) returns a valid result, use it; if it fails, optionally fall back to an LLM-based resolver; log both paths for future pattern analysis and auto-test generation.
|
||||
|
||||
### 3.7 Reference implementations to ship
|
||||
|
||||
The Wintermute survey inventoried 69 resolver shapes. Shipping all of them is wrong (over-scoped); shipping zero is under-scoped. The dogfood set:
|
||||
|
||||
| # | Resolver | Purpose | Used by |
|
||||
|---|---|---|---|
|
||||
| 1 | `x_handle_to_tweet` | Bare-tweet citation repair (original Phase A) | `gbrain integrity` |
|
||||
| 2 | `url_reachable` | Dead-link detection | `gbrain integrity` |
|
||||
| 3 | `brain_slug_lookup` | Name/email → slug (wraps existing `resolveSlugs`) | Output Builder |
|
||||
| 4 | `openai_embedding` | Refactor of `src/core/embedding.ts` into Resolver | Import pipeline |
|
||||
| 5 | `perplexity_query` | Query → synthesis + citations | Enrichment Orchestrator |
|
||||
| 6 | `text_to_entities` | LLM entity extraction (structured JSON) | Enrichment Orchestrator |
|
||||
|
||||
The remaining 63 Wintermute patterns port incrementally, driven by user need. Each port is a new YAML + module under `recipes/` or `~/.gbrain/resolvers/` with no framework changes.
|
||||
|
||||
---
|
||||
|
||||
## 4. Layer 2 — Enrichment Orchestrator
|
||||
|
||||
### 4.1 What's broken today
|
||||
|
||||
Wintermute's enrichment is **polished at the data layer, hacky at the control layer**:
|
||||
|
||||
- **Completeness = "length > 500 chars + no `needs-enrichment` tag"** (`lib/enrich.mjs:351-355`). Naïve. A rich page of repetitive Perplexity summaries (see `brain/people/0interestrates.md` — 38 repeating blocks) passes this check.
|
||||
- **30-day auto-re-enrichment** runs forever. No "done" state. A person met once in 2023 still gets re-researched monthly.
|
||||
- **Cascade is convention-only.** Person→company stubs are created automatically; company→investors, company→employees traversals are documented but never implemented.
|
||||
- **No hard budget cap.** Cost is estimated per batch, never enforced across batches or per day.
|
||||
- **Failure is silent.** A bad Perplexity response logs and continues; partial writes can leave a page with a timeline entry but no raw-data sidecar.
|
||||
|
||||
### 4.2 The orchestrator
|
||||
|
||||
```typescript
|
||||
// src/core/enrichment/orchestrator.ts
|
||||
|
||||
export interface EnrichmentRequest {
|
||||
entitySlug: string;
|
||||
trigger: 'mention' | 'stub-creation' | 'cron-sweep' | 'manual' | 'cascade';
|
||||
tier?: 1 | 2 | 3; // optional override; auto-computed if absent
|
||||
cascadeDepth?: number; // 0 = no cascade; default 1
|
||||
}
|
||||
|
||||
export interface EnrichmentResult {
|
||||
entitySlug: string;
|
||||
completenessBefore: number;
|
||||
completenessAfter: number;
|
||||
resolversUsed: string[]; // e.g. ["perplexity_query", "x_handle_to_tweet"]
|
||||
costSpent: number;
|
||||
writtenTo: string[]; // page paths touched, for transaction audit
|
||||
cascadedTo: string[]; // related entities enriched
|
||||
status: 'enriched' | 'skipped' | 'failed' | 'budget-exhausted';
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
export class EnrichmentOrchestrator {
|
||||
constructor(
|
||||
private registry: ResolverRegistry,
|
||||
private writer: BrainWriter,
|
||||
private budget: BudgetLedger,
|
||||
private scorer: CompletenessScorer,
|
||||
private graph: EntityGraph,
|
||||
) {}
|
||||
|
||||
async enrich(req: EnrichmentRequest): Promise<EnrichmentResult>;
|
||||
async enrichBatch(reqs: EnrichmentRequest[]): Promise<EnrichmentResult[]>;
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Evidence-weighted completeness (replaces length heuristic)
|
||||
|
||||
Completeness is a per-entity-type rubric, stored in frontmatter on write and recomputed on demand.
|
||||
|
||||
```typescript
|
||||
// src/core/enrichment/completeness.ts
|
||||
export interface CompletenessRubric<Page> {
|
||||
entityType: PageType;
|
||||
dimensions: {
|
||||
name: string;
|
||||
weight: number; // sum must = 1.0
|
||||
check: (page: Page) => number; // 0.0–1.0
|
||||
}[];
|
||||
}
|
||||
|
||||
// Example rubric for persons:
|
||||
// - has_role_and_company 0.20
|
||||
// - has_source_urls 0.20 (≥1 URL with resolver-verified reachability)
|
||||
// - has_timeline_entries 0.15 (≥1)
|
||||
// - has_citations 0.15 (every claim has [Source: ...])
|
||||
// - has_backlinks 0.10 (every linked page links back)
|
||||
// - recency_score 0.10 (last_verified within 90 days)
|
||||
// - non_redundancy 0.10 (no repeated blocks; distinct-lines/total-lines > 0.8)
|
||||
```
|
||||
|
||||
**Key property:** `non_redundancy` + `recency_score` explicitly kill the two brain pathologies observed in the audit (Wilco-style repeating blocks; stale pages without `last_verified`).
|
||||
|
||||
The `completeness` field goes in frontmatter as `0.0–1.0`. It becomes queryable via `list_pages(where: completeness < 0.5)`.
|
||||
|
||||
### 4.4 Tier routing with hard budget
|
||||
|
||||
Two-dimensional routing: **importance** (tier 1/2/3 from person-score) × **budget state**.
|
||||
|
||||
```typescript
|
||||
// src/core/enrichment/tiers.ts
|
||||
export const TIER_CONFIG = {
|
||||
1: { models: ['opus', 'sonar-deep'], maxCostUsd: 0.10, cascadeDepth: 2 },
|
||||
2: { models: ['sonar'], maxCostUsd: 0.02, cascadeDepth: 1 },
|
||||
3: { models: ['sonar'], maxCostUsd: 0.005, cascadeDepth: 0 },
|
||||
};
|
||||
|
||||
// src/core/enrichment/budget.ts
|
||||
export class BudgetLedger {
|
||||
// Hard caps. Queryable pre-resolve.
|
||||
dailyCapUsd: number;
|
||||
perEntityCapUsd: number;
|
||||
perResolverCapUsd: Map<string, number>;
|
||||
|
||||
async reserve(resolverId: string, estimateUsd: number): Promise<Reservation | 'exhausted'>;
|
||||
async commit(reservation: Reservation, actualUsd: number): Promise<void>;
|
||||
async rollback(reservation: Reservation): Promise<void>;
|
||||
async state(): Promise<{ spent: number; remaining: number; perResolver: Record<string, number> }>;
|
||||
}
|
||||
```
|
||||
|
||||
**Property:** if the daily cap is reached, `orchestrator.enrich()` returns `status: 'budget-exhausted'` immediately. No silent overages. Circuit-breaker resets at midnight in the user's configured TZ.
|
||||
|
||||
### 4.5 Cascade (entity graph traversal)
|
||||
|
||||
```typescript
|
||||
// src/core/enrichment/cascade.ts
|
||||
export class EntityGraph {
|
||||
// Deterministic, no LLM. Uses engine.getLinks() + engine.getBacklinks().
|
||||
async neighbors(slug: string, depth: number): Promise<string[]>;
|
||||
async cascadeFrom(trigger: string, depth: number): Promise<EnrichmentRequest[]>;
|
||||
}
|
||||
```
|
||||
|
||||
If person X is enriched and gains a new `company: Acme` field, cascade checks: does `companies/acme` exist? If not, create stub + enqueue at tier 2. Does `companies/acme` link back to X? If not, write the back-link. **Iron Law is machine-enforced, not skill-enforced.**
|
||||
|
||||
### 4.6 Fail-safe transactions
|
||||
|
||||
Every enrichment is wrapped in a BrainWriter transaction (Layer 4). Partial writes are rolled back. No asymmetric state like timeline-entry-without-raw-sidecar.
|
||||
|
||||
```typescript
|
||||
await writer.transaction(async (tx) => {
|
||||
const research = await registry.resolve('perplexity_query', {...}, ctx);
|
||||
await tx.appendTimeline(slug, {...});
|
||||
await tx.putRawData(slug, 'perplexity', research.raw);
|
||||
await tx.setFrontmatterField(slug, 'completeness', score);
|
||||
// All-or-nothing commit on exit.
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Layer 3 — Scheduler
|
||||
|
||||
### 5.1 What's broken today
|
||||
|
||||
Wintermute's cron is **externally-driven JSON** (`cron/jobs.json`) with ~30 jobs manually stagger-offset at different minutes. GBrain has **zero native scheduling** — `src/commands/autopilot.ts` is a single daemon loop, and `docs/guides/cron-schedule.md` is architectural guidance, not code.
|
||||
|
||||
Failures observed in Wintermute's actual state:
|
||||
- `X OAuth2 Token Refresh`: 11 consecutive timeouts (critical-path silent failure)
|
||||
- `flight-tracker daily scan`: 5 consecutive timeouts
|
||||
- `morning-briefing`: 4 consecutive timeouts
|
||||
- Quiet hours are checked at runtime in skills, so a skill that forgets to check will DM at 3 a.m.
|
||||
- Staggering is manual convention; no protection against two jobs colliding after a config edit.
|
||||
|
||||
### 5.2 ScheduledResolver interface
|
||||
|
||||
```typescript
|
||||
// src/core/scheduling/scheduler.ts
|
||||
export interface Schedule {
|
||||
kind: 'cron' | 'interval';
|
||||
expr?: string; // cron string
|
||||
intervalMs?: number;
|
||||
tz: string; // IANA: "America/Los_Angeles"
|
||||
quietHours?: {
|
||||
startHour: number; // 22 = 10 PM local
|
||||
endHour: number; // 7 = 7 AM local
|
||||
policy: 'skip' | 'defer' | 'silent-run';
|
||||
};
|
||||
staggerKey?: string; // jobs with same key auto-offset
|
||||
maxConcurrent?: number; // global concurrency cap
|
||||
maxDurationMs?: number; // timeout
|
||||
}
|
||||
|
||||
export interface ScheduledResolver extends Resolver<void, ScheduledResult> {
|
||||
schedule: Schedule;
|
||||
retryPolicy: { maxRetries: number; backoffMs: number };
|
||||
circuitBreaker: { failureThreshold: number; cooldownMs: number };
|
||||
state: DurableState; // watermark, content-hash, idempotency key
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Enforcement vs convention (the key delta from Wintermute)
|
||||
|
||||
| Concern | Wintermute today | Knowledge Runtime |
|
||||
|---|---|---|
|
||||
| Quiet hours | Checked inside each skill (trust-based) | Enforced at scheduler, skill cannot override |
|
||||
| Staggering | Manual minute-offset in `jobs.json` | Scheduler assigns slots via hashed staggerKey |
|
||||
| Concurrency | `MAX_BATCH_PROCESSES=2` in backoff, ignored by cron | Global semaphore in scheduler |
|
||||
| Timeout | Per-job string in JSON, not always respected | Enforced via `AbortController`, timeout raises `TimeoutError` caught by orchestrator |
|
||||
| Retry | None at cron level | `retryPolicy` with exponential backoff |
|
||||
| Silent failure | "11 consecutive timeouts" unnoticed | Circuit breaker opens at threshold → escalation to user |
|
||||
| Idempotency | State files per job, no framework | `DurableState` primitive: watermark/ID/content-hash |
|
||||
|
||||
### 5.4 Native engine + OS cron adapter
|
||||
|
||||
The scheduler runs as either:
|
||||
1. **Embedded** (default for `gbrain autopilot`): native event loop inside the daemon process. One process, many ScheduledResolvers.
|
||||
2. **OS-driven** (for Railway/launchd/systemd): `gbrain schedule run <id>` invoked by OS cron, scheduler state is durable so cross-invocation dedup still works.
|
||||
|
||||
Both modes share the same `Schedule` config + state.
|
||||
|
||||
### 5.5 Observability
|
||||
|
||||
Every scheduled run emits structured events: `started`, `skipped-quiet-hours`, `deferred-to-active-hours`, `failed-retrying`, `circuit-opened`, `completed`. Events go to:
|
||||
- `~/.gbrain/scheduler/events.jsonl` (local, always)
|
||||
- `engine.logIngest` (audit trail in brain DB)
|
||||
- Optional webhook (Slack/Telegram for the user)
|
||||
|
||||
`gbrain doctor` reads the event log and reports: current circuit-breaker state, any resolver with > 3 consecutive failures, any resolver that hasn't fired within 3× its interval (freshness SLA like Wintermute's `freshness-check.mjs` but built-in).
|
||||
|
||||
---
|
||||
|
||||
## 6. Layer 4 — Deterministic Output Builder
|
||||
|
||||
### 6.1 The anti-hallucination invariant
|
||||
|
||||
**Iron Law: LLM picks WHAT. Code guarantees WHERE and HOW.**
|
||||
|
||||
Wintermute's existing `lib/enrich.mjs:buildTweetEntry` is close to this — tweet URLs are built from `tweet.id` returned by the X API, never from LLM memory. But:
|
||||
|
||||
- A past incident: *"Sub-agent test #2 FAILED — hallucinated 'Philip Leung' entity links across all daily files. LLM rewriting of daily files is too error-prone."* (Wintermute memory log, 2026-04-13.)
|
||||
- Back-links depend on `appendTimeline` being called everywhere; skips are silent.
|
||||
- Slug collisions are unchecked (no conflict detection on `slugify`).
|
||||
- Citation format is post-hoc linted weekly, not pre-write enforced.
|
||||
|
||||
### 6.2 BrainWriter
|
||||
|
||||
```typescript
|
||||
// src/core/output/writer.ts
|
||||
export class BrainWriter {
|
||||
constructor(
|
||||
private engine: BrainEngine,
|
||||
private slugRegistry: SlugRegistry,
|
||||
private scaffolder: Scaffolder,
|
||||
) {}
|
||||
|
||||
async transaction<T>(fn: (tx: WriteTx) => Promise<T>): Promise<T>;
|
||||
}
|
||||
|
||||
export interface WriteTx {
|
||||
// High-level typed operations; never raw string writes.
|
||||
createEntity(input: EntityInput): Promise<string>; // returns slug, conflict-checked
|
||||
appendTimeline(slug: string, entry: TimelineInput): Promise<void>;
|
||||
setCompiledTruth(slug: string, body: CompiledTruthInput): Promise<void>;
|
||||
setFrontmatterField(slug: string, key: string, value: unknown): Promise<void>;
|
||||
putRawData(slug: string, source: string, data: object): Promise<void>;
|
||||
addLink(from: string, to: string, context: string): Promise<void>; // auto-creates reverse back-link
|
||||
|
||||
// Validators (called implicitly on commit)
|
||||
validate(): Promise<ValidationReport>;
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 Scaffolder — deterministic link + citation construction
|
||||
|
||||
Every user-visible URL/link/citation is built by code from resolver outputs, not from LLM text.
|
||||
|
||||
```typescript
|
||||
// src/core/output/scaffold.ts
|
||||
export class Scaffolder {
|
||||
tweetCitation(handle: string, tweetId: string, dateISO: string): string {
|
||||
// "[Source: [X/garrytan, 2026-04-18](https://x.com/garrytan/status/123456)]"
|
||||
}
|
||||
emailCitation(account: string, messageId: string, subject: string): string {
|
||||
// deterministic Gmail URL per Wintermute pattern
|
||||
}
|
||||
sourceCitation(resolverResult: ResolverResult<unknown>): string {
|
||||
// pulls .source, .fetchedAt, .raw from the result
|
||||
}
|
||||
entityLink(slug: string): string {
|
||||
// slugRegistry checks existence; returns resolvable wikilink
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.4 SlugRegistry — conflict detection
|
||||
|
||||
```typescript
|
||||
// src/core/output/slug-registry.ts
|
||||
export class SlugRegistry {
|
||||
async create(desiredSlug: string, displayName: string, type: PageType): Promise<CreatedSlug>;
|
||||
// Throws SlugCollision if another entity already occupies desiredSlug and isn't
|
||||
// confirmed as the same person (via email / x_handle / disambiguator).
|
||||
// Auto-resolves near-collisions by appending disambiguator.
|
||||
|
||||
async confirmSame(slugA: string, slugB: string, confidence: number): Promise<void>;
|
||||
async merge(canonical: string, duplicate: string): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### 6.5 Pre-write validators (fail-closed for integrity)
|
||||
|
||||
On `WriteTx.validate()` before commit:
|
||||
|
||||
1. **Citation validator.** Every factual sentence in `compiled_truth` must have an inline `[Source: ...]` within N lines. Non-compliant paragraphs are flagged. Configurable: strict-mode rejects the transaction, lint-mode warns.
|
||||
2. **Link validator.** Every `[text](path)` must point to a page that exists OR to a URL the Scaffolder built (so it's guaranteed-valid). No raw LLM-composed URLs.
|
||||
3. **Back-link validator.** Every outbound link must have a reverse link written in the same transaction.
|
||||
4. **Triple-HR validator.** Compiled truth / timeline split enforced at the schema level.
|
||||
|
||||
**Fails closed**: the default is strict-mode. Loosening requires explicit `writer.transaction({ strictMode: false }, ...)` and logs a warning to the ingest log.
|
||||
|
||||
### 6.6 LLM output sanitization
|
||||
|
||||
Any LLM output destined for a brain page passes through a JSON-Schema-validated parser first. No free-form markdown goes to disk.
|
||||
|
||||
- Entity extraction: JSON array of `{ name, type, context }` per existing `extractEntities` pattern — strict validation.
|
||||
- Compiled-truth synthesis: LLM emits structured `{ sections: [{heading, paragraphs: [{text, sources: [...]}]}]}`, scaffolder renders to markdown.
|
||||
- Timeline entries: LLM emits `{ date, summary, detail, sources }`, scaffolder renders.
|
||||
|
||||
LLM never sees file paths, never writes files, never emits finished markdown.
|
||||
|
||||
---
|
||||
|
||||
## 7. Integration with existing GBrain
|
||||
|
||||
### 7.1 Reuse (already polished)
|
||||
|
||||
| Existing | Used by | Change |
|
||||
|---|---|---|
|
||||
| `src/core/fail-improve.ts` (9/10) | Wraps every Resolver in L1 | None; becomes default wrapper |
|
||||
| `src/core/backoff.ts` (9/10) | ResolverContext.backoff | None |
|
||||
| `src/core/storage.ts` (9/10) | Template for Resolver factory pattern | None; serves as pattern reference |
|
||||
| `src/core/check-resolvable.ts` (9/10) | Extend to validate Resolver plugins | Add `checkResolvers()` mode |
|
||||
| `src/commands/publish.ts` (9/10) | Uses BrainWriter under the hood | Minor: route through L4 |
|
||||
| `src/commands/backlinks.ts` (8/10) | Folded into L4 validator | Keep as CLI-facing lint entry point |
|
||||
| `src/core/operations.ts` validators | Reused in ResolverContext trust enforcement | None |
|
||||
| `src/core/engine.ts` BrainEngine (35 methods) | ResolverContext.engine | Extend with `getResolverRegistry()` |
|
||||
|
||||
### 7.2 Replace (ad-hoc today)
|
||||
|
||||
| Existing | Replace with |
|
||||
|---|---|
|
||||
| `src/core/enrichment-service.ts` (5/10) | `src/core/enrichment/orchestrator.ts` (L2) |
|
||||
| `src/core/embedding.ts` (monolithic) | `src/core/resolvers/builtin/embedding/openai.ts` |
|
||||
| `src/core/transcription.ts` (monolithic) | `src/core/resolvers/builtin/transcription/{groq,openai}.ts` |
|
||||
| `src/commands/integrations.ts` recipe format | Unified Resolver plugin format (§3.5) |
|
||||
| `src/core/data-research.ts` recipe format | Same unified format |
|
||||
| `src/commands/autopilot.ts` hard-coded daemon loop | Wraps a set of ScheduledResolvers |
|
||||
|
||||
### 7.3 Extend
|
||||
|
||||
- `src/core/engine.ts`: add `getResolverRegistry()`, `getWriter()`, `getScheduler()`. Engine becomes the runtime's root container.
|
||||
- `src/core/operations.ts`: `OperationContext` inherits from `ResolverContext` (or vice-versa). Trust flags unified.
|
||||
- `src/core/types.ts`: add `completeness: number` to `Page`, `sourcedBy: string[]` for provenance.
|
||||
|
||||
---
|
||||
|
||||
## 8. Migration Path (phased, shippable)
|
||||
|
||||
Each phase ships independently, passes full E2E, is feature-flagged, and is reversible. No big-bang.
|
||||
|
||||
### Phase 0 — Foundation (human: ~1 wk / CC: ~4 h)
|
||||
- Define `Resolver<I,O>`, `ResolverContext`, `ResolverRegistry`, `ResolverResult` (§3.2–3.4).
|
||||
- Add `src/core/resolvers/index.ts` wiring + tests for registry (register/get/list).
|
||||
- No behavioral change; ship as `v0.11.0-alpha` with feature flag.
|
||||
|
||||
### Phase 1 — Three reference resolvers (human: ~1 wk / CC: ~4 h)
|
||||
- Port `src/core/embedding.ts` → `resolvers/builtin/embedding/openai.ts`.
|
||||
- Implement `resolvers/builtin/brain-local/slug-lookup.ts` (wraps `engine.resolveSlugs`).
|
||||
- Implement `resolvers/builtin/url-reachable.ts` (HEAD-check).
|
||||
- Prove the interface: old callers swap to `registry.resolve('openai_embedding', ...)`.
|
||||
|
||||
### Phase 2 — BrainWriter + Slug Registry (human: ~1.5 wk / CC: ~6 h)
|
||||
- L4 core: `BrainWriter.transaction`, `Scaffolder`, `SlugRegistry` with conflict detection.
|
||||
- Pre-write validators: citation, link, back-link, triple-HR.
|
||||
- Migrate `src/commands/publish.ts` + `src/commands/backlinks.ts` to route through BrainWriter.
|
||||
- **Now** Wintermute's "Philip Leung" hallucination is structurally impossible — LLM output passes through JSON-Schema validator before reaching Scaffolder.
|
||||
|
||||
### Phase 3 — `gbrain integrity` command (human: ~0.5 wk / CC: ~2 h)
|
||||
- Ship the originally-scoped user-facing feature on top of the new foundation.
|
||||
- Uses Resolver SDK: `x_handle_to_tweet` + `url_reachable`.
|
||||
- Uses BrainWriter: all auto-repairs go through validated writes.
|
||||
- `--auto --confidence 0.8` mode as user approved in cherry-pick #1.
|
||||
- **User-visible value ships in Phase 3, not Phase 7.**
|
||||
|
||||
### Phase 4 — Enrichment Orchestrator (human: ~2 wk / CC: ~8 h)
|
||||
- L2 core: `EnrichmentOrchestrator`, `BudgetLedger`, `CompletenessScorer`, `EntityGraph.cascadeFrom`.
|
||||
- Migrate `src/core/enrichment-service.ts` callers (deprecate the old file after).
|
||||
- Completeness score in frontmatter on every write (dogfooding cascades).
|
||||
|
||||
### Phase 5 — Scheduler (human: ~2 wk / CC: ~8 h)
|
||||
- L3 core: `Scheduler`, `ScheduledResolver`, `DurableState`, circuit breaker, quiet-hours enforcer.
|
||||
- Migrate `src/commands/autopilot.ts` to a ScheduledResolver set.
|
||||
- Ship `gbrain schedule list|run|pause|tail` CLI for observability.
|
||||
|
||||
### Phase 6 — Port 5–8 Wintermute resolvers (human: ~1.5 wk / CC: ~6 h)
|
||||
- `perplexity_query`, `text_to_entities`, `mistral_ocr_pdf`, `x_search_all`, `x_user_to_tweets`, `gmail_query_to_threads`, `calendar_date_to_events`.
|
||||
- Each ships as YAML + TS module under `resolvers/builtin/` — **proof of the plugin format.**
|
||||
|
||||
### Phase 7 — Wintermute Claw Adoption Integration (human: ~1 wk / CC: ~4 h)
|
||||
- Write `docs/wintermute/ADOPTION.md` showing Wintermute how to replace its 69 bespoke scripts with calls to `gbrain registry.resolve(...)`.
|
||||
- Ship a `gbrain claw-bridge` subcommand that proxies Wintermute's current script invocations to the resolver registry — zero-edit adoption path.
|
||||
- **This is the test of the north star.** If Wintermute can stand up a 1-line shim and drop `scripts/x-api-client.mjs`, the abstraction succeeded.
|
||||
|
||||
Total: human: ~10 weeks / CC: ~42 hours / calendar with single implementer: ~3–4 weeks.
|
||||
|
||||
---
|
||||
|
||||
## 9. Critical Files
|
||||
|
||||
### New directories / files
|
||||
|
||||
```
|
||||
src/core/
|
||||
runtime/
|
||||
index.ts # RuntimeContext (engine, storage, config, logger, metrics, budget)
|
||||
registry.ts # ResolverRegistry
|
||||
factory.ts # createResolver()
|
||||
resolvers/
|
||||
interface.ts # Resolver<I, O>
|
||||
fail-improve-wrapper.ts # auto-wraps every resolver in FailImproveLoop
|
||||
builtin/
|
||||
x-api/
|
||||
handle-to-tweet.ts
|
||||
handle-to-tweet.yaml
|
||||
perplexity/
|
||||
query.ts
|
||||
query.yaml
|
||||
brain-local/
|
||||
slug-lookup.ts
|
||||
url-reachable.ts
|
||||
embedding/
|
||||
openai.ts # refactored from src/core/embedding.ts
|
||||
transcription/
|
||||
groq.ts
|
||||
openai.ts
|
||||
enrichment/
|
||||
orchestrator.ts # EnrichmentOrchestrator
|
||||
tiers.ts # TIER_CONFIG
|
||||
budget.ts # BudgetLedger
|
||||
completeness.ts # CompletenessScorer + per-type rubrics
|
||||
cascade.ts # EntityGraph
|
||||
scheduling/
|
||||
scheduler.ts # Scheduler + ScheduledResolver
|
||||
schedule.ts # Schedule type, cron expr parser
|
||||
state.ts # DurableState primitives
|
||||
quiet-hours.ts # TZ-aware enforcement
|
||||
stagger.ts # deterministic slot assignment
|
||||
output/
|
||||
writer.ts # BrainWriter
|
||||
scaffold.ts # Scaffolder (typed URL builders)
|
||||
slug-registry.ts # SlugRegistry (conflict detection)
|
||||
validators/
|
||||
citation.ts
|
||||
link.ts
|
||||
back-link.ts
|
||||
triple-hr.ts
|
||||
|
||||
src/commands/
|
||||
integrity.ts # ships in Phase 3, replaces Feynman Phase A/B
|
||||
schedule.ts # gbrain schedule list|run|pause|tail (Phase 5)
|
||||
|
||||
docs/wintermute/
|
||||
ADOPTION.md # written in Phase 7
|
||||
```
|
||||
|
||||
### Replaced / removed
|
||||
- `src/core/enrichment-service.ts` — folded into `enrichment/orchestrator.ts`
|
||||
- `src/core/embedding.ts` — moved into `resolvers/builtin/embedding/openai.ts`
|
||||
- `src/core/transcription.ts` — moved into `resolvers/builtin/transcription/`
|
||||
|
||||
### Extended
|
||||
- `src/core/engine.ts` — add `getResolverRegistry()`, `getWriter()`, `getScheduler()`
|
||||
- `src/core/operations.ts` — unify with ResolverContext; every operation validator reusable by resolvers
|
||||
- `src/core/types.ts` — add `completeness: number`, `sourcedBy: string[]`, `lastVerified: Date`
|
||||
|
||||
---
|
||||
|
||||
## 10. Testing Strategy
|
||||
|
||||
### Contract tests
|
||||
Every Resolver implementation tested against the interface spec. Table-driven: run the same suite against `openai_embedding`, `x_handle_to_tweet`, etc. Ensures plugin authors can't ship broken resolvers.
|
||||
|
||||
### Property tests
|
||||
- **Idempotency:** running a ScheduledResolver twice with the same state produces the same output and doesn't double-write.
|
||||
- **Atomicity:** a BrainWriter transaction that throws mid-flight leaves the brain bit-for-bit identical to pre-transaction.
|
||||
- **Deterministic scaffolds:** given the same resolver outputs, the Scaffolder produces byte-identical citations/links.
|
||||
|
||||
### Integration tests
|
||||
- `EnrichmentOrchestrator` end-to-end against PGLite (in-memory, no API keys) with mocked resolver registry.
|
||||
- `Scheduler` with fake clock + quiet-hours scenarios.
|
||||
- BrainWriter transaction rollback on validator failure.
|
||||
|
||||
### Chaos tests
|
||||
- Kill the process mid-enrichment; next run must resume cleanly.
|
||||
- Simulate API timeout mid-transaction; transaction must roll back completely.
|
||||
- Corrupted state file; scheduler must escalate, not silently skip.
|
||||
|
||||
### Regression tests vs. Wintermute behavior
|
||||
For each Wintermute pattern we port (e.g. X-handle → tweet URL), a regression test proves the new resolver produces the same answer on real-world inputs from the brain audit. This is the "Wintermute would adopt" proof.
|
||||
|
||||
---
|
||||
|
||||
## 11. Open Questions (flagged for CEO re-review)
|
||||
|
||||
1. **Scope shape.** Is this the right four-layer decomposition, or are some layers better left to Wintermute (e.g. Scheduling lives above GBrain, not in it)?
|
||||
2. **Phase 3 user-value break.** Does Phase 3 (user-visible `gbrain integrity`) ship early enough, or do we need an even smaller MVP?
|
||||
3. **LLM-as-resolver.** Should `text_to_entities` be a Resolver, or does that blur the "code vs LLM" line the invariant relies on?
|
||||
4. **Plugin format.** YAML + TS module (§3.5) vs. pure TS module with decorator-style metadata. Latter is more type-safe; former is more discoverable.
|
||||
5. **Cross-resolver transactions.** Do we support "atomic fetch-from-Perplexity + write-to-brain" at the L2 layer? Current design says yes; implementation is tricky (Perplexity call isn't rollbackable).
|
||||
6. **Wintermute bridge scope.** Phase 7 `gbrain claw-bridge` — is that worth a phase of its own, or should adoption be documentation-only?
|
||||
7. **Completeness rubric coverage.** Do we define rubrics for all 9 PageTypes upfront, or ship people/company/meeting first and extend incrementally?
|
||||
8. **Budget config UX.** Hard daily cap is strict; should we also expose a soft-cap warning mode, and how is the cap set (env var? config file? prompt on first use?)
|
||||
9. **Backwards compat.** `src/commands/publish.ts` and `src/commands/backlinks.ts` have been running cleanly for weeks. Refactoring through BrainWriter carries migration risk. Acceptable?
|
||||
10. **Existing TODOS alignment.** `TODOS.md` has P0 "Runtime MCP access control" and P2 security hardening. The new RuntimeContext.remote flag interacts with both — do we fold MCP access control into Phase 0 or keep separate?
|
||||
|
||||
---
|
||||
|
||||
## 12. Verification (the "Wintermute would adopt" test)
|
||||
|
||||
The design succeeds iff:
|
||||
|
||||
- [ ] A user can add a new resolver by dropping a YAML + TS module in `~/.gbrain/resolvers/` without editing GBrain source.
|
||||
- [ ] Wintermute can delete `scripts/x-api-client.mjs` and replace all callers with 1-line `await registry.resolve('x_handle_to_tweet', ...)`.
|
||||
- [ ] No brain page can be written with a bare tweet reference, a missing back-link, or an unverified URL (validators catch it pre-commit).
|
||||
- [ ] Running `gbrain integrity --auto --confidence 0.8` over a real brain fixes ≥1,000 of the 1,424 known bare-tweet citations without human review.
|
||||
- [ ] Full E2E test suite passes on both PGLite + Postgres engines.
|
||||
- [ ] The Knowledge Runtime ships across 7 phases with each phase individually shippable and reversible.
|
||||
@@ -1,448 +0,0 @@
|
||||
---
|
||||
status: ACTIVE
|
||||
---
|
||||
# CEO Plan: Minions as Universal Agent Orchestration Protocol
|
||||
Generated by /plan-ceo-review on 2026-04-15
|
||||
Branch: garrytan/minions-jobs | Mode: SCOPE EXPANSION
|
||||
Repo: garrytan/gbrain
|
||||
|
||||
## Vision
|
||||
|
||||
### 10x Check
|
||||
Instead of "GBrain has a queue, OpenClaw uses it," make Minions a universal agent
|
||||
orchestration protocol. Any platform (OpenClaw, Hermes, Claude Code, Codex, custom
|
||||
scripts) submits, monitors, steers, and composes agents through the same Postgres-native
|
||||
protocol. GBrain IS the agent control plane.
|
||||
|
||||
### Platonic Ideal (aspirational North Star, NOT in v1 scope)
|
||||
Open a terminal, type `gbrain jobs dashboard`. See every agent across every platform.
|
||||
Their progress, tool calls, token spend. Click any agent for full execution trace.
|
||||
Type a message to redirect a running agent mid-flight. See the governor's decisions
|
||||
visualized. Run A/B tests between agent configurations. The feeling: complete
|
||||
situational awareness of your AI workforce.
|
||||
|
||||
**Note:** The dashboard, A/B testing, and visual governor are future phases. This plan
|
||||
builds the primitives they would sit on top of: real-time events, structured progress,
|
||||
token accounting, inbox with ack, and session transcripts.
|
||||
|
||||
## Scope Decisions
|
||||
|
||||
| # | Proposal | Effort | Decision | Reasoning |
|
||||
|---|----------|--------|----------|-----------|
|
||||
| 1 | pg LISTEN/NOTIFY real-time events | S | ACCEPTED | Sub-second event delivery vs 5s polling. Every platform benefits. |
|
||||
| 2 | Structured progress protocol | S | ACCEPTED | Standard progress makes unified dashboard possible. |
|
||||
| 3 | Job cost tracking (token accounting) | M | ACCEPTED | Token cost is #1 thing users want to know about agent work. |
|
||||
| 4 | Job replay | S | ACCEPTED | Small surface area, high utility for debugging failures. |
|
||||
| 5 | Job groups / waves | M | DEFERRED | Parent-child already provides grouping. Overlap concern. |
|
||||
| 6 | Inbox acknowledgment (read receipts) | S | ACCEPTED | Without it, inbox is fire-and-forget — same problem we're fixing. |
|
||||
| 7 | Universal agent protocol | S | ACCEPTED | Design framing, not extra code. Platform-agnostic naming/docs. |
|
||||
| 8 | Session transcript capture | M | ACCEPTED | Full audit trail of every agent run. |
|
||||
|
||||
## Accepted Scope — Implementation Detail
|
||||
|
||||
### 0a. Pause/resume (from base plan)
|
||||
|
||||
**Schema:** Add `'paused'` to `MinionJobStatus` (already in migration v6 constraint).
|
||||
|
||||
**New methods:**
|
||||
- `MinionQueue.pauseJob(id): MinionJob | null`
|
||||
Transitions `waiting` or `active` → `paused`. For `active` jobs, clears `lock_token`
|
||||
and `lock_until` (worker will detect lock loss and stop). Returns null if job not
|
||||
in pausable state.
|
||||
- `MinionQueue.resumeJob(id): MinionJob | null`
|
||||
Transitions `paused` → `waiting`. Resets for claiming. Returns null if not paused.
|
||||
|
||||
**Worker integration:** Worker's lock renewal loop checks `isActive()`. When a job
|
||||
is paused, the lock is cleared, so `renewLock()` returns false and the worker stops
|
||||
execution gracefully (same path as stall detection). The job's progress and state
|
||||
are preserved in the DB for when it resumes.
|
||||
|
||||
**MCP operations:** `pause_job`, `resume_job` (added in Step 3 of implementation plan).
|
||||
|
||||
**PGLite compatibility:** Full.
|
||||
|
||||
### 0b. Resource governor (from base plan)
|
||||
|
||||
**New file:** `src/core/minions/governor.ts`
|
||||
|
||||
```typescript
|
||||
interface GovernorConfig {
|
||||
maxConcurrency: number; // ceiling
|
||||
minConcurrency: number; // floor (default 1)
|
||||
checkIntervalMs: number; // default 10000
|
||||
cpuThreshold: number; // default 0.80 (80%)
|
||||
memoryThreshold: number; // default 0.85 (85%)
|
||||
circuitBreakerMemory: number; // default 0.90 (90%)
|
||||
}
|
||||
|
||||
class ResourceGovernor {
|
||||
getEffectiveConcurrency(): number; // current allowed concurrency
|
||||
start(): void; // begin polling system metrics
|
||||
stop(): void; // stop polling
|
||||
onCircuitBreak(cb: (jobId) => void): void; // kill callback
|
||||
}
|
||||
```
|
||||
|
||||
**System metrics:** Reuse `getSystemLoad()` from `src/core/backoff.ts` (already
|
||||
implements CPU and memory checks). Add event loop lag measurement via
|
||||
`perf_hooks.monitorEventLoopDelay()`.
|
||||
|
||||
**Worker integration:** `MinionWorker.start()` consults `governor.getEffectiveConcurrency()`
|
||||
before claiming new jobs. If current in-flight count >= effective concurrency, skip claim.
|
||||
|
||||
**Circuit breaker:** If memory > 90%, governor calls `onCircuitBreak` with the
|
||||
lowest-priority active job ID. Worker cancels that job via `failJob()` with
|
||||
`UnrecoverableError("circuit breaker: memory pressure")`.
|
||||
|
||||
**Prerequisite:** Concurrent job processing must be implemented first (see
|
||||
Concurrency Note below).
|
||||
|
||||
**PGLite compatibility:** Full (governor is app-level, not DB-level).
|
||||
|
||||
### 1. pg LISTEN/NOTIFY (real-time events)
|
||||
|
||||
**Schema:** No new columns. Add NOTIFY triggers to state transitions.
|
||||
|
||||
**SQL trigger:**
|
||||
```sql
|
||||
CREATE OR REPLACE FUNCTION notify_minion_job_change() RETURNS trigger AS $$
|
||||
BEGIN
|
||||
PERFORM pg_notify('minion_jobs', json_build_object(
|
||||
'id', NEW.id, 'status', NEW.status, 'name', NEW.name,
|
||||
'queue', NEW.queue, 'prev_status', COALESCE(OLD.status, 'new')
|
||||
)::text);
|
||||
RETURN NEW;
|
||||
END;
|
||||
$$ LANGUAGE plpgsql;
|
||||
|
||||
CREATE TRIGGER minion_job_notify AFTER INSERT OR UPDATE OF status ON minion_jobs
|
||||
FOR EACH ROW EXECUTE FUNCTION notify_minion_job_change();
|
||||
```
|
||||
|
||||
**New method:** `MinionQueue.subscribe(callback: (event) => void): () => void`
|
||||
Returns unsubscribe function. Requires direct Postgres connection (NOT pooled).
|
||||
|
||||
**PGLite compatibility:** PGLite does NOT support LISTEN/NOTIFY. Fallback: polling
|
||||
via `getJob()` at configurable interval (default 2s). The `subscribe()` method
|
||||
detects engine type and uses polling fallback automatically.
|
||||
|
||||
**Supabase constraint:** Requires direct connection (port 5432), not pgBouncer
|
||||
pooler (port 6543). Document in skill file and setup guide.
|
||||
|
||||
### 2. Structured progress protocol
|
||||
|
||||
**TypeScript interface (convention, not enforced at DB level):**
|
||||
```typescript
|
||||
interface AgentProgress {
|
||||
step: number; // current step (1-based)
|
||||
total: number; // total expected steps (0 = unknown)
|
||||
message: string; // human-readable status
|
||||
tokens_in: number; // cumulative input tokens
|
||||
tokens_out: number; // cumulative output tokens
|
||||
last_tool: string; // name of last tool called
|
||||
started_at: string; // ISO 8601 when this step started
|
||||
}
|
||||
```
|
||||
|
||||
**Storage:** Existing `progress JSONB` column. No schema change needed.
|
||||
Handlers use `ctx.updateProgress(agentProgress)`. Non-agent jobs can use
|
||||
any JSONB shape (backward compatible).
|
||||
|
||||
**Validation:** `updateProgress()` accepts any JSONB. The `AgentProgress`
|
||||
interface is a convention enforced by the agent handler, not by the queue.
|
||||
|
||||
### 3. Job cost tracking (token accounting)
|
||||
|
||||
**Schema changes (migration v6):**
|
||||
```sql
|
||||
ALTER TABLE minion_jobs ADD COLUMN tokens_input INTEGER DEFAULT 0;
|
||||
ALTER TABLE minion_jobs ADD COLUMN tokens_output INTEGER DEFAULT 0;
|
||||
ALTER TABLE minion_jobs ADD COLUMN tokens_cache_read INTEGER DEFAULT 0;
|
||||
ALTER TABLE minion_jobs ADD COLUMN cost_usd NUMERIC(10,6) DEFAULT 0;
|
||||
```
|
||||
|
||||
**New method:** `MinionQueue.updateTokens(id, lockToken, { input, output, cache_read, cost_usd })`
|
||||
Accumulates (adds to existing values, does not replace).
|
||||
|
||||
**Parent rollup:** When `completeJob()` is called, if `parent_job_id` is set,
|
||||
add this job's token counts to the parent's via:
|
||||
```sql
|
||||
UPDATE minion_jobs SET
|
||||
tokens_input = tokens_input + $child_input,
|
||||
tokens_output = tokens_output + $child_output,
|
||||
tokens_cache_read = tokens_cache_read + $child_cache,
|
||||
cost_usd = cost_usd + $child_cost
|
||||
WHERE id = $parent_id;
|
||||
```
|
||||
|
||||
**PGLite compatibility:** Full support (standard columns).
|
||||
|
||||
### 4. Job replay
|
||||
|
||||
**New method:** `MinionQueue.replayJob(id, dataOverrides?: Record<string, unknown>): MinionJob`
|
||||
|
||||
Implementation: Read the completed/failed/dead job. Create a NEW job with:
|
||||
- Same `name`, `queue`, `priority`, `max_attempts`, `backoff_type`, `backoff_delay`
|
||||
- `data` = deep merge of original data + overrides
|
||||
- Fresh `attempts_made: 0`, `status: 'waiting'`
|
||||
- `parent_job_id` = null (replay is a new top-level job, not a child)
|
||||
- Does NOT clone children (replay is a single job, not a DAG)
|
||||
|
||||
**Constraint:** Only works on terminal statuses (completed/failed/dead).
|
||||
Returns the new job record.
|
||||
|
||||
**Idempotency:** Each replay creates a distinct new job. No deduplication.
|
||||
If the original had side effects, the replay may repeat them. Document this
|
||||
in the skill file as a user responsibility.
|
||||
|
||||
### 5. Inbox (sidechannel messaging)
|
||||
|
||||
**Schema changes (migration v6):**
|
||||
```sql
|
||||
ALTER TABLE minion_jobs ADD COLUMN inbox JSONB DEFAULT '[]';
|
||||
```
|
||||
|
||||
**Inbox message format:**
|
||||
```typescript
|
||||
interface InboxMessage {
|
||||
id: string; // UUIDv4
|
||||
sent_at: string; // ISO 8601
|
||||
read_at: string | null; // null until worker reads it
|
||||
sender: string; // 'parent' | 'user' | job ID
|
||||
payload: unknown; // arbitrary directive
|
||||
}
|
||||
```
|
||||
|
||||
**New methods:**
|
||||
- `MinionQueue.sendMessage(jobId, payload, sender?): InboxMessage`
|
||||
Appends message to inbox array via atomic JSONB append
|
||||
(`inbox = inbox || $1::jsonb`), not read-modify-write. Returns the message with id + sent_at.
|
||||
- `MinionQueue.readInbox(jobId, lockToken): InboxMessage[]`
|
||||
Returns unread messages (read_at = null). Marks them as read (sets read_at).
|
||||
Token-fenced: only the worker holding the lock can read.
|
||||
|
||||
**Worker integration:** Agent handler calls `readInbox()` on each iteration.
|
||||
If messages exist, injects them into the agent's context as system messages.
|
||||
|
||||
**PGLite compatibility:** Full support (standard JSONB column).
|
||||
|
||||
### 6. Inbox acknowledgment (read receipts)
|
||||
|
||||
Built into the inbox design above. The `read_at` field on each `InboxMessage`
|
||||
provides the receipt. `sendMessage()` returns the message ID; the sender can
|
||||
later check `getJob(id)` and inspect `inbox` to see which messages have been
|
||||
read.
|
||||
|
||||
No additional schema or methods needed beyond what's in #5.
|
||||
|
||||
### 7. Universal agent protocol (platform-agnostic framing)
|
||||
|
||||
**This is a design decision, not code.** It means:
|
||||
|
||||
1. The skill file (`skills/minion-orchestrator/SKILL.md`) is written for ANY
|
||||
agent platform, not just OpenClaw. Examples show MCP tool calls, not
|
||||
OpenClaw-specific commands.
|
||||
|
||||
2. The agent handler (`agent-handler.ts`) accepts a generic interface:
|
||||
```typescript
|
||||
interface AgentJobData {
|
||||
prompt: string;
|
||||
tools?: string[]; // MCP tool names
|
||||
model?: string; // e.g., 'claude-opus-4-6', 'gpt-4o'
|
||||
context?: string; // additional context
|
||||
platform?: string; // 'openclaw' | 'hermes' | 'claude-code' | 'custom'
|
||||
max_iterations?: number; // agent loop budget
|
||||
}
|
||||
```
|
||||
|
||||
3. The OpenClaw plugin is ONE consumer. Hermes, Claude Code extensions,
|
||||
or custom scripts can submit `agent` jobs through the same MCP operations.
|
||||
|
||||
4. **NOT in v1 scope:** Multi-tenant auth, cross-network connectivity,
|
||||
protocol versioning, API key isolation. These are Phase 2 concerns when
|
||||
actual multi-platform usage materializes. v1 is single-user, single-brain.
|
||||
|
||||
### Agent Handler Architecture (critical design decision)
|
||||
|
||||
The agent handler does NOT live in GBrain. GBrain provides the queue infrastructure
|
||||
and a clean handler contract. The actual agent execution lives in the platform plugin.
|
||||
|
||||
```
|
||||
GBrain (this repo):
|
||||
MinionQueue — queue/claim/complete/inbox/tokens/NOTIFY
|
||||
MinionWorker — poll/lock/stall/governor framework
|
||||
Handler contract — AgentJobData interface + MinionJobContext
|
||||
|
||||
OpenClaw plugin (separate repo):
|
||||
Registers "agent" handler with MinionWorker
|
||||
Handler calls OpenClaw's PI agent core (the actual LLM loop)
|
||||
Each iteration: readInbox → inject as system message, updateProgress, updateTokens
|
||||
Completion: store result + session transcript in job.result + job.stacktrace
|
||||
|
||||
GBrain ships a test/echo handler for unit testing only.
|
||||
```
|
||||
|
||||
**Handler contract (GBrain side):**
|
||||
```typescript
|
||||
// The handler receives this context (already exists in worker.ts)
|
||||
interface MinionJobContext {
|
||||
id: number;
|
||||
name: string;
|
||||
data: Record<string, unknown>; // AgentJobData when name="agent"
|
||||
attempts_made: number;
|
||||
updateProgress(progress: unknown): Promise<void>;
|
||||
updateTokens(tokens: TokenUpdate): Promise<void>; // NEW
|
||||
log(message: string | TranscriptEntry): Promise<void>;
|
||||
isActive(): Promise<boolean>;
|
||||
readInbox(): Promise<InboxMessage[]>; // NEW
|
||||
}
|
||||
```
|
||||
|
||||
**Why this is right:** GBrain is orchestration, not execution. OpenClaw has the
|
||||
PI agent core. Hermes has AIAgent. Claude Code has its own loop. Each platform
|
||||
brings its own engine and registers a handler. GBrain manages lifecycle, progress,
|
||||
steering, cost tracking, and persistence around it.
|
||||
|
||||
### 8. Session transcript capture
|
||||
|
||||
**Extends existing stacktrace mechanism.** The `stacktrace` field (JSONB array
|
||||
of strings) already captures log messages. Session transcripts use the same
|
||||
field with structured entries:
|
||||
|
||||
```typescript
|
||||
type TranscriptEntry =
|
||||
| { type: 'log'; message: string; ts: string }
|
||||
| { type: 'tool_call'; tool: string; args_size: number; result_size: number; ts: string }
|
||||
| { type: 'llm_turn'; model: string; tokens_in: number; tokens_out: number; ts: string }
|
||||
| { type: 'error'; message: string; stack?: string; ts: string };
|
||||
```
|
||||
|
||||
**Storage:** Existing `stacktrace JSONB` column. No schema change.
|
||||
The agent handler appends `TranscriptEntry` objects instead of plain strings.
|
||||
Backward compatible: non-agent jobs continue appending strings.
|
||||
|
||||
**Size concern:** Long agent runs could generate large transcripts. Add a
|
||||
`max_transcript_entries` option (default 1000) that rotates oldest entries
|
||||
when exceeded (FIFO). The full transcript for forensic analysis can be
|
||||
stored as a brain file via `gbrain files upload-raw`.
|
||||
|
||||
## Schema Migration v6
|
||||
|
||||
All schema changes are additive (ALTER TABLE ADD COLUMN). No backfill needed.
|
||||
Existing jobs continue to work with default values.
|
||||
|
||||
```sql
|
||||
-- Migration v6: Agent orchestration primitives
|
||||
ALTER TABLE minion_jobs ADD COLUMN IF NOT EXISTS tokens_input INTEGER DEFAULT 0;
|
||||
ALTER TABLE minion_jobs ADD COLUMN IF NOT EXISTS tokens_output INTEGER DEFAULT 0;
|
||||
ALTER TABLE minion_jobs ADD COLUMN IF NOT EXISTS tokens_cache_read INTEGER DEFAULT 0;
|
||||
|
||||
-- Separate inbox table (not JSONB on job row)
|
||||
CREATE TABLE IF NOT EXISTS minion_inbox (
|
||||
id SERIAL PRIMARY KEY,
|
||||
job_id INTEGER NOT NULL REFERENCES minion_jobs(id) ON DELETE CASCADE,
|
||||
sender TEXT NOT NULL,
|
||||
payload JSONB NOT NULL,
|
||||
sent_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
read_at TIMESTAMPTZ
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_minion_inbox_unread
|
||||
ON minion_inbox (job_id) WHERE read_at IS NULL;
|
||||
|
||||
-- Status constraint update: add 'paused'
|
||||
ALTER TABLE minion_jobs DROP CONSTRAINT IF EXISTS minion_jobs_status_check;
|
||||
ALTER TABLE minion_jobs ADD CONSTRAINT minion_jobs_status_check
|
||||
CHECK (status IN ('waiting','active','completed','failed','delayed','dead','cancelled','waiting-children','paused'));
|
||||
|
||||
-- NOTIFY trigger for real-time events (Postgres only, not PGLite)
|
||||
CREATE OR REPLACE FUNCTION notify_minion_job_change() RETURNS trigger AS $$
|
||||
BEGIN
|
||||
PERFORM pg_notify('minion_jobs', json_build_object(
|
||||
'id', NEW.id, 'status', NEW.status, 'name', NEW.name,
|
||||
'queue', NEW.queue, 'prev_status', COALESCE(OLD.status, 'new')
|
||||
)::text);
|
||||
RETURN NEW;
|
||||
END;
|
||||
$$ LANGUAGE plpgsql;
|
||||
|
||||
CREATE TRIGGER minion_job_notify AFTER INSERT OR UPDATE OF status ON minion_jobs
|
||||
FOR EACH ROW EXECUTE FUNCTION notify_minion_job_change();
|
||||
```
|
||||
|
||||
## PGLite Compatibility Matrix
|
||||
|
||||
| Feature | Postgres | PGLite | Fallback |
|
||||
|---|---|---|---|
|
||||
| Pause/resume | Full | Full | — |
|
||||
| Inbox + ack | Full | Full | — |
|
||||
| Token accounting | Full | Full | — |
|
||||
| Job replay | Full | Full | — |
|
||||
| LISTEN/NOTIFY | Full | NO | Polling (2s interval) |
|
||||
| NOTIFY trigger | Full | NO | Skipped in PGLite schema |
|
||||
| Structured progress | Full | Full | — |
|
||||
| Session transcripts | Full | Full | — |
|
||||
| Resource governor | Full | Full | — |
|
||||
| Worker daemon | Full | NO (existing limitation) | — |
|
||||
|
||||
## Concurrency Note
|
||||
|
||||
The current `MinionWorker.start()` processes jobs sequentially (one at a time)
|
||||
despite `concurrency` being declared in `MinionWorkerOpts`. Implementing actual
|
||||
concurrent job processing (Promise pool) is a prerequisite for the resource
|
||||
governor to be meaningful. The governor adjusts effective concurrency, which
|
||||
requires actual concurrent processing to exist.
|
||||
|
||||
**Action:** Implement concurrent job processing in `worker.ts` before or as
|
||||
part of the governor step. Use a semaphore pattern: maintain up to N in-flight
|
||||
promises, claim new jobs as slots free up.
|
||||
|
||||
## Outside Voice Decisions (from adversarial review)
|
||||
|
||||
1. **AbortController for pause/resume** — Handler contract gets `signal: AbortSignal`.
|
||||
Pause clears lock AND signals abort. Handler must check `signal.aborted` on each
|
||||
iteration. Without this, pausing active jobs creates duplicate execution.
|
||||
|
||||
2. **Drop cost_usd column** — Token counts (input/output/cache_read) are stable facts.
|
||||
USD pricing is volatile. Compute cost at display/read time from a pricing table,
|
||||
not at write time. Removes `cost_usd NUMERIC(10,6)` from migration v6.
|
||||
|
||||
3. **Separate minion_inbox table** — Instead of JSONB array on job row, use a dedicated
|
||||
table for inbox messages. Avoids row bloat from rewriting entire inbox on every send.
|
||||
Properly concurrent-safe with standard INSERT (no JSONB append concerns).
|
||||
```sql
|
||||
CREATE TABLE minion_inbox (
|
||||
id SERIAL PRIMARY KEY,
|
||||
job_id INTEGER NOT NULL REFERENCES minion_jobs(id) ON DELETE CASCADE,
|
||||
sender TEXT NOT NULL,
|
||||
payload JSONB NOT NULL,
|
||||
sent_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
read_at TIMESTAMPTZ
|
||||
);
|
||||
CREATE INDEX idx_minion_inbox_unread ON minion_inbox (job_id) WHERE read_at IS NULL;
|
||||
```
|
||||
|
||||
4. **One release, not two** — Ship all features in one migration (v6). User prefers
|
||||
cohesive release over incremental delivery for this feature set.
|
||||
|
||||
5. **Selective column projection** — Fix SELECT * queries in getJobs(), claim(),
|
||||
handleStalled() to exclude stacktrace column. Include stacktrace only in getJob()
|
||||
detail view. Prevents transcript bloat from affecting query performance.
|
||||
|
||||
## Future Phases (accepted trajectory)
|
||||
|
||||
- **Phase 2: Dashboard CLI** — `gbrain jobs dashboard` live TUI showing all agents.
|
||||
Enabled by: LISTEN/NOTIFY, structured progress, token accounting.
|
||||
- **Phase 3: Multi-tenant auth** — Runtime MCP access control, per-platform API keys.
|
||||
Enabled by: platform-agnostic framing, sender validation on inbox.
|
||||
- **Phase 4: Agent composition patterns** — Map-reduce, pipeline, approval gates as
|
||||
first-class primitives. Enabled by: parent-child DAGs, inbox sidechannel.
|
||||
|
||||
## Deferred to TODOS.md
|
||||
- Job groups / waves (parent-child covers this; revisit if real grouping need emerges)
|
||||
- cost_usd column (compute from pricing table at read time when pricing API exists)
|
||||
|
||||
## Key Premises Confirmed
|
||||
1. GBrain is intentionally evolving from knowledge brain to agent infrastructure (user confirmed)
|
||||
2. Coupling between OpenClaw and GBrain's Postgres is acceptable (OpenClaw already depends on GBrain)
|
||||
3. Full Infrastructure approach (all 8+ steps) selected over Minimal Viable or Sidecar Tracking
|
||||
4. Prior learning [agent-dx-instruction-layer] validates that the teaching layer (skill + evals) is mandatory
|
||||
@@ -1,188 +0,0 @@
|
||||
---
|
||||
type: essay
|
||||
title: "Homebrew for Personal AI"
|
||||
subtitle: "Why Markdown is Code and Your Agent is a Package Manager"
|
||||
author: Garry Tan
|
||||
created: 2026-04-11
|
||||
updated: 2026-04-11
|
||||
tags: [ai, gbrain, gstack, markdown-is-code, open-source, software-distribution, agents, openclaw]
|
||||
status: draft-v2
|
||||
prior: "Thin Harness, Fat Skills"
|
||||
---
|
||||
|
||||
# Homebrew for Personal AI
|
||||
|
||||
`brew install` gives you someone else's binary. `npm install` gives you someone else's source code. Both require you to understand the tool, configure it, integrate it, maintain it.
|
||||
|
||||
What if software distribution worked differently? What if you could describe a capability in plain English, hand that description to an AI agent, and the agent built a native implementation tailored to your setup?
|
||||
|
||||
That's what happens when markdown is code.
|
||||
|
||||
## Markdown is code
|
||||
|
||||
Here's a real skill file. This one teaches an AI agent to screen phone calls:
|
||||
|
||||
```markdown
|
||||
# Voice Agent — Your Phone Number
|
||||
|
||||
Caller → Twilio → <Stream> WebSocket → Voice Server (port 8765)
|
||||
↕ audio
|
||||
OpenAI Realtime API
|
||||
↓ tool calls
|
||||
Brain / Calendar / Telegram
|
||||
|
||||
## Call Routing
|
||||
|
||||
Every inbound call routes based on caller phone number + brain lookup:
|
||||
|
||||
### Owner → Authenticated Mode
|
||||
- Send crypto-random 6-digit code to secure channel
|
||||
- Caller reads it back
|
||||
- Match → full assistant mode (brain, calendar, scheduling)
|
||||
- No match → treated as unknown caller
|
||||
|
||||
### Known Person, Inner Circle (brain score ≥ 4) → Forward
|
||||
- Greet by name with brain context
|
||||
- Transfer to cell
|
||||
- If no answer (30s timeout), take message
|
||||
- Text Telegram with who called and context
|
||||
|
||||
### Unknown Caller → Screen
|
||||
- Get their name, look them up in brain
|
||||
- If inner circle → offer to transfer
|
||||
- Otherwise → take message
|
||||
- Create brain entry with phone number (marked UNVERIFIED)
|
||||
```
|
||||
|
||||
That's not pseudocode. That's not documentation. That's a working specification that a model like Claude Opus 4.6 with a million-token context window can read and implement. The architecture diagram tells it the components. The routing table tells it the logic. The security model tells it the constraints. The agent reads this file, understands it, and builds the Twilio integration, the WebSocket server, the Telegram bot hooks, the brain lookup, all of it, shaped to whatever infrastructure the user already has.
|
||||
|
||||
A skill file is a method call. It takes parameters (your phone number, your brain, your preferred messaging app). Same skill, different arguments, different implementation. The procedure is the package. The model is the runtime.
|
||||
|
||||
## The distribution mechanism
|
||||
|
||||
Traditional package managers distribute artifacts: compiled binaries, source tarballs, container images. The consumer runs someone else's code.
|
||||
|
||||
GBrain distributes recipes: markdown files that describe capabilities with enough specificity that an AI agent can implement them from scratch. The consumer gets a native implementation. No dependency hell. No version conflicts. No transitive vulnerability chains. Because there is no upstream code. There's a description of what to build and why.
|
||||
|
||||
Here's how it works:
|
||||
|
||||
1. **Build a feature.** Implement a voice agent, meeting ingestion pipeline, email triage system, investment diligence workflow, whatever.
|
||||
|
||||
2. **GBrain captures the recipe.** Not just the code. The architecture, the integration points, the failure modes, the judgment calls. A markdown file that encodes the full capability.
|
||||
|
||||
3. **Push to the repo.** Open source. Anyone can read it.
|
||||
|
||||
4. **Someone else's agent pulls the recipe.** Reads the markdown. Says: "New recipe available: AI voice agent with caller screening. Want it?" User says yes. The agent reads the spec and builds it.
|
||||
|
||||
No installation. No configuration wizard. No README. The agent read a document and figured it out.
|
||||
|
||||
## Why this works now
|
||||
|
||||
This didn't work two years ago. Two things changed.
|
||||
|
||||
**Context windows hit a million tokens.** A real skill file for meeting ingestion is 200+ lines. The enrichment skill that calls it references a brain schema, a resolver, a citation standard, five external APIs, and a cross-linking protocol. An agent implementing this recipe needs to hold all of that in working memory simultaneously while also understanding the user's existing setup. At 8K tokens, impossible. At 128K, marginal. At 1M, comfortable.
|
||||
|
||||
**Models crossed the judgment threshold.** Here's a snippet from a real enrichment recipe:
|
||||
|
||||
```markdown
|
||||
## Philosophy
|
||||
|
||||
A brain page should read like an intelligence dossier crossed
|
||||
with a therapist's notes, not a LinkedIn scrape. We want:
|
||||
|
||||
- What they believe — ideology, worldview, first principles
|
||||
- What they're building — current projects, what's next
|
||||
- What motivates them — ambition drivers, career arc
|
||||
- What makes them emotional — angry, excited, defensive, proud
|
||||
- Their trajectory — ascending, plateauing, pivoting, declining?
|
||||
- Hard facts — role, company, funding, location, contact info
|
||||
|
||||
Facts are table stakes. Texture is the value.
|
||||
```
|
||||
|
||||
A model implementing this recipe has to understand the difference between a LinkedIn scrape and an intelligence dossier. That's a judgment call about what information is worth capturing and how to weight it. GPT-3 couldn't do this. GPT-4 could sort of do it. Opus 4.6 does it well. The enabling technology is models that are smart enough to interpret intent, not just follow instructions.
|
||||
|
||||
## What a recipe actually contains
|
||||
|
||||
A good recipe has five sections:
|
||||
|
||||
**Architecture.** The component diagram. What talks to what, over what protocol, with what data flow. This is the skeleton the agent builds first.
|
||||
|
||||
**Routing logic.** The decision tree. When X happens, do Y. When Z fails, fall back to W. This is where domain knowledge lives. A voice agent recipe encodes call routing. A diligence recipe encodes how to process pitch decks vs. financial models vs. cap tables. A meeting ingestion recipe encodes how to turn a raw transcript into actionable intelligence.
|
||||
|
||||
**Integration points.** What external systems does this touch? Twilio, Telegram, Gmail, Circleback, Slack, GitHub, Supabase, whatever. The recipe names the integrations; the agent figures out how to connect them given what the user already has configured.
|
||||
|
||||
**Judgment calls.** The hard part. Not "send an email" but "decide whether this email is worth surfacing to the user based on sender importance, time sensitivity, and whether it requires a decision." Recipes that skip the judgment calls produce shallow implementations. The judgment calls are the actual value.
|
||||
|
||||
**Failure modes.** What goes wrong and what to do about it. "If Circleback token expires, message the user and ask them to reconnect. Don't silently skip." "If caller ID is spoofed, never trust it for authentication. Use a challenge-response code via a separate channel." Recipes without failure modes produce brittle systems.
|
||||
|
||||
Here's a real example. This is the diligence recipe's detection logic:
|
||||
|
||||
```markdown
|
||||
## Detection
|
||||
|
||||
Recognize data room materials by:
|
||||
- PDF filenames: "Data Deck", "Intro Deck", "Cap Table",
|
||||
"Financial Model", "Pitch Deck", "Series [A-D]"
|
||||
- Spreadsheets with tabs: Revenue, Retention, Cohorts,
|
||||
CAC, Gross Margin, Unit Economics, ARR
|
||||
- User saying: "data room", "diligence", "deck", "pitch"
|
||||
- Context: shared in the Diligence topic
|
||||
```
|
||||
|
||||
That's a pattern matcher expressed in English. An agent reads this and knows how to classify incoming documents. No regex. No file type configuration. Just a description of the pattern and the model's judgment about whether a given document matches.
|
||||
|
||||
## Pick and choose
|
||||
|
||||
GBrain is not monolithic. Recipes are independent. Take what you want:
|
||||
|
||||
- **Voice agent** — phone screening, caller ID, brain lookup, message routing
|
||||
- **Meeting ingestion** — transcript processing, entity extraction, action item capture, timeline updates
|
||||
- **Email triage** — inbox sweep, priority classification, draft replies, scheduling extraction
|
||||
- **Enrichment pipeline** — people and company research from multiple data sources, diarized into brain pages
|
||||
- **Diligence processing** — data room ingestion, PDF extraction, financial model analysis
|
||||
- **Social monitoring** — X/Twitter timeline analysis, mention tracking, narrative detection
|
||||
- **Content pipeline** — idea capture, link ingestion, article summarization
|
||||
|
||||
Each recipe is self-contained. Your agent knows what you already have. GBrain pings daily: "Three new recipes since last sync. Want any?" You pick. It builds.
|
||||
|
||||
And because the source code is English, forking is trivial. Don't like how the voice agent handles unknown callers? Edit the markdown. Change "take a message" to "ask three screening questions first." The behavior changes because the spec changed.
|
||||
|
||||
## The thin harness, fat skills connection
|
||||
|
||||
This essay is a sequel. The prequel was "Thin Harness, Fat Skills," which argued that the secret to 100x AI productivity isn't better models but better context management. Keep the harness thin (the program running the model). Make the skills fat (markdown procedures encoding judgment and process).
|
||||
|
||||
"Markdown is code" is the distribution corollary. If the skills are fat markdown files, and if models are smart enough to implement from markdown, then the skills are distributable software. The skill file is simultaneously:
|
||||
|
||||
- **Documentation** for humans reading it
|
||||
- **Specification** for the implementing agent
|
||||
- **Package** for the distribution system
|
||||
- **Source code** for the resulting capability
|
||||
|
||||
Four artifacts collapsed into one. That's why this is different from every previous package manager. `brew install` separates the formula from the binary from the docs from the source. GBrain collapses them. The markdown is all four.
|
||||
|
||||
## The architecture underneath
|
||||
|
||||
Three layers, same as the talk:
|
||||
|
||||
**Fat skills** on top. Markdown recipes encoding judgment, process, failure modes, and domain knowledge. This is where 90% of the value lives. This is what gets distributed.
|
||||
|
||||
**Thin harness** in the middle. The program running the model. File operations, tool dispatch, context management, safety enforcement. About 200 lines. OpenClaw or any equivalent. The less the harness constrains, the more the recipes can express.
|
||||
|
||||
**Deterministic foundation** on the bottom. Databases, APIs, CLIs. Same input, same output, every time. SQL queries, HTTP calls, file reads. The skills describe WHEN to call these; the harness executes them.
|
||||
|
||||
Push intelligence UP into skills. Push execution DOWN into deterministic tooling. Distribute the skills. That's the whole system.
|
||||
|
||||
## What this means
|
||||
|
||||
When implementation cost approaches zero, the bottleneck shifts. It's no longer "can we build this?" It's "should we build this?" and "what exactly should it do?"
|
||||
|
||||
Taste, vision, and domain knowledge become the scarce resources. The person who deeply understands call screening and writes a precise recipe creates more value than the person who can implement a Twilio integration from scratch. The recipe IS the implementation.
|
||||
|
||||
This also means the best AI agent setups will be open source by default. Closed, proprietary agent configurations are competing against a world where someone publishes a recipe and a thousand agents implement it overnight. The recipe propagates at the speed of a git push. The moat is taste, not code.
|
||||
|
||||
Software distribution reimagined: the package is a markdown file, the runtime is a sufficiently smart model, the package manager is your AI agent, and the app store is a git repo.
|
||||
|
||||
`gbrain install voice-agent`
|
||||
|
||||
That's it.
|
||||
@@ -1,209 +0,0 @@
|
||||
---
|
||||
type: essay
|
||||
title: "Thin Harness, Fat Skills"
|
||||
subtitle: "How to Make AI Agents Actually Understand Your Data"
|
||||
author: Garry Tan
|
||||
created: 2026-04-09
|
||||
updated: 2026-04-11
|
||||
tags: [ai, agents, gstack, harness-engineering, skills, architecture]
|
||||
status: draft-v4
|
||||
talk: "YC Spring 2026 -- Thin Harness, Fat Skills"
|
||||
thread: https://x.com/garrytan/status/2042925773300908103
|
||||
---
|
||||
|
||||
# Thin Harness, Fat Skills
|
||||
|
||||
Steve Yegge says people using AI coding agents are "10x to 100x as productive as engineers using Cursor and chat today, and roughly 1000x as productive as Googlers were back in 2005."
|
||||
|
||||
That's a real number. I've seen it. I've lived it. But when people hear 100x, they think: better models. Smarter Claude. More parameters.
|
||||
|
||||
That's the wrong frame entirely. The 2x people and the 100x people are using the same models. The difference is five concepts that fit on an index card.
|
||||
|
||||
## The harness is the secret sauce
|
||||
|
||||
On March 31, 2026, Anthropic accidentally shipped the entire source code for Claude Code to the npm registry. 512,000 lines. When I read it, it confirmed everything I'd been teaching at YC. The secret sauce isn't the model. It's the thing wrapping the model: the harness. Live repo context. Prompt caching. Purpose-built tools. Context bloat minimization. Structured session memory. Parallel sub-agents.
|
||||
|
||||
None of that is about making the model smarter. All of it is about giving the model the right context, at the right time, without drowning it in noise.
|
||||
|
||||
That's the only question that matters. And the answer has a specific shape. I call it **thin harness, fat skills**.
|
||||
|
||||
## Five definitions
|
||||
|
||||
The bottleneck is never the model's intelligence. The bottleneck is whether the model understands your schema. Models already know how to reason, synthesize, and write code. They fail because they don't know your data. Five definitions fix this.
|
||||
|
||||
### Definition 1: Skill File
|
||||
|
||||
A skill file is a reusable markdown procedure that teaches the model HOW to do something. Not WHAT to do. The user supplies the specifics. The skill supplies the process.
|
||||
|
||||
**Markdown is actually code.** A skill file is a more perfect encapsulation of capability than rigid source code, because it describes process, judgment, and context in the language the model already thinks in.
|
||||
|
||||
On the left is a skill called `/investigate`. Seven steps: scope the dataset, build a timeline, diarize every document, synthesize, argue both sides, cite sources. It takes three parameters: TARGET, QUESTION, and DATASET.
|
||||
|
||||
On the right are two completely different invocations of the same skill. One points at Dr. Sarah Chen and 2.1 million discovery emails, asking whether a safety scientist was silenced. The other points at Pacific Corporate Services and FEC filings, asking whether shell companies are coordinating campaign donations.
|
||||
|
||||
Same skill. Same seven steps. Same markdown file. In one case it's a medical research analyst. In the other it's a forensic investigator. The skill describes a process of judgment. The invocation supplies the world.
|
||||
|
||||
**This is the key insight most people miss: a skill file works like a method call.** It takes parameters. You invoke it with different arguments. The same procedure produces radically different capabilities depending on what you pass in. This is not prompt engineering. This is software design, using markdown as the programming language and human judgment as the runtime.
|
||||
|
||||
### Definition 2: Harness
|
||||
|
||||
The harness is the program that runs the LLM. It does four things: runs the model in a loop, reads and writes your files, manages context, and enforces safety. That's the "thin."
|
||||
|
||||
The anti-pattern is a fat harness with thin skills: 40+ tool definitions eating half the context window. God tools with 2 to 5 second MCP round-trips. REST API wrappers that turn every endpoint into a tool. 3x the tokens, 3x the latency, 3x the failure rate.
|
||||
|
||||
What you should build instead: a Playwright CLI that does each browser operation in 100 milliseconds. Compare: Chrome MCP takes 15 seconds for screenshot + find + click + wait + read. Playwright CLI takes 200 milliseconds for screenshot + assert. 75x faster. Software doesn't have to be precious anymore. Build exactly what you need.
|
||||
|
||||
### Definition 3: Resolver
|
||||
|
||||
A resolver is a routing table for context. When task type X appears, load document Y first.
|
||||
|
||||
Skills say HOW. Resolvers say WHAT to load WHEN. A developer changes a prompt. Without the resolver, they ship it. With the resolver, the model reads `docs/EVALS.md` first, which says: run the eval suite, compare scores, if accuracy drops more than 2%, revert and investigate. The developer didn't know the eval suite existed. The resolver loaded the right context at the right moment.
|
||||
|
||||
Claude Code has a built-in resolver. Every skill has a description field, and the model matches user intent to skill descriptions automatically. You never have to remember `/ship` exists. The description IS the resolver. It's like Clippy. Except it actually works.
|
||||
|
||||
A confession: my CLAUDE.md was 20,000 lines. Every single thing I ran across went in there. Every quirk, every pattern, every lesson. Completely ridiculous. The model's attention degraded. Claude Code literally told me to cut it back. The fix: about 200 lines. Just pointers to documents. The resolver loads the right one when it matters.
|
||||
|
||||
### Definition 4: Latent vs. Deterministic
|
||||
|
||||
Every step in your system is one or the other.
|
||||
|
||||
**Latent space** is where intelligence lives. The model reads, interprets, decides. Judgment. Synthesis. Pattern recognition.
|
||||
|
||||
**Deterministic** is where trust lives. Same input, same output. Every time. SQL. Code. Numbers.
|
||||
|
||||
An LLM can seat 8 people at a dinner table. Ask it to seat 800 and it will hallucinate a seating chart that looks plausible but is completely wrong. That's a deterministic problem forced into latent space. The worst systems put the wrong work on the wrong side.
|
||||
|
||||
### Definition 5: Diarization
|
||||
|
||||
The model reads everything about a subject and writes a structured profile. Read 50 documents, produce 1 page of judgment.
|
||||
|
||||
No SQL query produces this. No RAG pipeline produces this. The model has to actually read, hold contradictions in mind, notice what changed and when, and write structured intelligence. This is what makes AI useful for real knowledge work.
|
||||
|
||||
## The architecture
|
||||
|
||||
Three layers:
|
||||
|
||||
**Fat skills** on top. Markdown procedures that encode judgment, process, and domain knowledge. This is where 90% of the value lives.
|
||||
|
||||
**Thin CLI harness** in the middle. About 200 lines. JSON in, text out. Read-only by default. CLI first, add MCP later.
|
||||
|
||||
**Your app** on the bottom. QueryDB. ReadDoc. Search. Timeline. The deterministic foundation.
|
||||
|
||||
Push intelligence UP into skills. Push execution DOWN into deterministic tooling. Keep the harness THIN.
|
||||
|
||||
## The system that learns: YC Startup School
|
||||
|
||||
Let me show you all five definitions working together. Not in theory. In an actual system we're building at YC.
|
||||
|
||||
Chase Center. July 2026. 6,000 founders. Each one has a structured application, questionnaire answers, transcripts from 1:1 advisor chats, and public signals: X posts, GitHub commits, Claude Code transcripts showing how fast they ship.
|
||||
|
||||
The traditional approach: a program team of 15 reads applications, makes gut calls, updates a spreadsheet. It works at 200 founders. It breaks at 6,000.
|
||||
|
||||
No human can hold 6,000 profiles in working memory and notice that the three best candidates for the infrastructure-for-AI-agents cohort are a dev tools founder in Lagos, a compliance founder in Singapore, and a CLI-tooling founder in Brooklyn who all described the same pain point in different words during their 1:1 chats.
|
||||
|
||||
The model can.
|
||||
|
||||
**Step 1: Enrich every founder.**
|
||||
|
||||
The `/enrich-founder` skill: pull all sources, run enrichments, diarize, highlight what they SAY vs what they're ACTUALLY BUILDING. On the right, the deterministic calls: SQL to find stale profiles, GitHub stats, browser test on the demo URL, social signal pulls, CrustData for company intel.
|
||||
|
||||
Cron runs nightly at 2am. 6,000 profiles, every night, always fresh.
|
||||
|
||||
The diarization output catches things no keyword search would find:
|
||||
|
||||
```
|
||||
FOUNDER: Maria Santos
|
||||
COMPANY: Contrail (contrail.dev)
|
||||
SAYS: "Datadog for AI agents"
|
||||
ACTUALLY BUILDING: 80% of commits are in billing module.
|
||||
She's building a FinOps tool disguised as observability.
|
||||
```
|
||||
|
||||
"SAYS" vs "ACTUALLY BUILDING." That requires reading the GitHub commit history, the application, and the advisor transcript and holding all three in mind at once.
|
||||
|
||||
**Step 2: Match 6,000 founders. Make judgment calls.**
|
||||
|
||||
This is where skill-as-method-call really shines. Three invocations:
|
||||
|
||||
`/match-breakout`: 1,200 founders, cluster by sector affinity, 30 per room. Embed + deterministic assign.
|
||||
|
||||
`/match-lunch`: 600 founders, serendipity matching (cross-sector), 8 per table, no repeats. The LLM invents the themes, then assigns.
|
||||
|
||||
`/match-live`: whoever is in the zone, nearest-neighbor embedding, real-time at 200ms, 1:1 pairs, not already met.
|
||||
|
||||
Same skill. Three invocations. Three completely different matching strategies. Different parameters, different strategies, different group sizes. The skill describes the process. The arguments shape the output.
|
||||
|
||||
And the model's judgment calls: "Santos and Oram are both AI infra, but they're not competitors. Santos is cost attribution, Oram is orchestration. Put them in the same group." And: "Kim applied as 'developer tools' but his 1:1 transcript reveals he's building compliance automation for SOC2. Move him to FinTech/RegTech."
|
||||
|
||||
No embedding captures the Kim reclassification. No algorithm can do it. The model has to read the entire profile.
|
||||
|
||||
**Step 3: The self-learning loop.**
|
||||
|
||||
After the event, the `/improve` skill reads NPS surveys, diarizes the "OK" responses (not the bad ones, the mediocre ones), and extracts patterns. Then it proposes new rules and writes them back into the matching skills:
|
||||
|
||||
```
|
||||
When attendee says "AI infrastructure"
|
||||
but startup is 80%+ billing code:
|
||||
-> Classify as FinTech, not AI Infra.
|
||||
|
||||
When two attendees in same group
|
||||
already know each other:
|
||||
-> Penalize proximity.
|
||||
Prioritize novel introductions.
|
||||
```
|
||||
|
||||
These rules get written back into the skill file. Next run uses them automatically. The skill rewrites itself.
|
||||
|
||||
July event: 12% "OK" ratings. Next event: 4%. The skill file learned what "OK" actually meant.
|
||||
|
||||
Same pattern as every other domain: retrieve, read, diarize, count, synthesize. Then: survey, investigate, diarize, rewrite the skill. It transfers everywhere.
|
||||
|
||||
## OpenClaw: where the skills live
|
||||
|
||||
I want to tell you about one more harness. Not for coding. For everything else.
|
||||
|
||||
I run a personal AI agent on OpenClaw. It has a persona, knows who I am, and maintains a knowledge base of thousands of interconnected files. But the thing that makes it work is the exact same principle. Thin harness, fat skills.
|
||||
|
||||
I tweeted about this a few days ago:
|
||||
|
||||
> *You are not allowed to do one-off work. If I ask you to do something and it's the kind of thing that will need to happen again, you must: do it manually the first time on 3 to 10 items. Show me the output. If I approve, codify it into a skill file. If it should run automatically, put it on a cron.*
|
||||
|
||||
> *The test: if I have to ask you for something twice, you failed.*
|
||||
|
||||
That resonated: a thousand likes, twenty-five hundred bookmarks. People thought it was a prompt engineering trick. It's not. It's the same architecture.
|
||||
|
||||
Claude Code is the best harness for coding. OpenClaw is the best harness for everything else: email, calendar, meetings, people, research, alerts. Same principle. Thin harness. Fat skills. The skills are method calls. The parameters change. The process stays.
|
||||
|
||||
Every skill I write is a permanent upgrade. It never degrades. It never forgets. It runs at 3 AM while I sleep. And when the next model drops, every skill instantly gets better, because the judgment in the latent steps improves while the deterministic steps stay perfectly reliable.
|
||||
|
||||
That's how you get Yegge's 10x to 100x. Not a smarter model. Fat skills, thin harness, and the discipline to codify everything.
|
||||
|
||||
The system compounds. Build it once. It runs forever.
|
||||
|
||||
Five definitions. Three layers. One principle. Thin harness, fat skills.
|
||||
|
||||
---
|
||||
|
||||
## Agent Decision Guide: Skill or Code?
|
||||
|
||||
When building GBrain features, use this decision guide:
|
||||
|
||||
| Question | If YES | If NO |
|
||||
|----------|--------|-------|
|
||||
| Does the agent need to think, adapt, or ask questions? | **Skill** (recipe markdown) | Code |
|
||||
| Same input always produces same output? | **Code** (CLI command) | Skill |
|
||||
| Does it require judgment about the user's environment? | **Skill** | Code |
|
||||
| Is it a lookup, list, or status check? | **Code** | Probably skill |
|
||||
| Does it change behavior based on conversation context? | **Skill** | Code |
|
||||
|
||||
**GBrain examples:**
|
||||
- `gbrain integrations list` = **Code** (reads files, checks env vars, deterministic)
|
||||
- `gbrain integrations status` = **Code** (checks env vars + heartbeat, deterministic)
|
||||
- `gbrain integrations doctor` = **Code** (runs health checks, deterministic)
|
||||
- `gbrain integrations stats` = **Code** (aggregates JSONL, deterministic)
|
||||
- Recipe setup flow = **Skill** (asks for API keys, adapts to environment, validates)
|
||||
- Recipe changelog surfacing = **Skill** (agent describes changes conversationally)
|
||||
- Entity detection = **Skill** (reads message, decides what's important, creates pages)
|
||||
- Meeting ingestion = **Skill** (reads transcript, extracts entities, updates pages)
|
||||
|
||||
**The rule:** If it's a lookup table, it's code. If the agent needs to think, it's a skill.
|
||||
@@ -1,129 +0,0 @@
|
||||
# The Brain-Agent Loop
|
||||
|
||||
## Goal
|
||||
|
||||
Every conversation makes the brain smarter. Every brain lookup makes responses
|
||||
better. The loop compounds daily.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: the agent answers from stale context. You discuss a deal on Monday,
|
||||
and by Friday the agent has forgotten. Every conversation starts from zero.
|
||||
|
||||
With this: six months in, the agent knows more about your world than you can hold
|
||||
in working memory. It never forgets. It never stops indexing.
|
||||
|
||||
## The Loop
|
||||
|
||||
```
|
||||
Signal arrives (message, meeting, email, tweet, link)
|
||||
│
|
||||
▼
|
||||
DETECT entities (people, companies, concepts, original thinking)
|
||||
│ → spawn sub-agent (see entity-detection.md)
|
||||
│
|
||||
▼
|
||||
READ: check brain FIRST (before responding)
|
||||
│ → gbrain search "{entity name}"
|
||||
│ → gbrain get {slug} (if you know it)
|
||||
│ → gbrain query "what do we know about {topic}"
|
||||
│
|
||||
▼
|
||||
RESPOND with brain context (every answer is better with context)
|
||||
│
|
||||
▼
|
||||
WRITE: update brain pages (new info → compiled truth + timeline)
|
||||
│ → gbrain put {slug} (update page)
|
||||
│ → add_timeline_entry (append to timeline)
|
||||
│ → add_link (cross-reference to other entities)
|
||||
│
|
||||
▼
|
||||
SYNC: gbrain indexes changes
|
||||
│ → gbrain sync --no-pull --no-embed
|
||||
│
|
||||
▼
|
||||
(next signal arrives — agent is now smarter)
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### On Every Inbound Message
|
||||
|
||||
```
|
||||
on_message(text):
|
||||
// 1. DETECT (async, don't block)
|
||||
spawn_entity_detector(text)
|
||||
|
||||
// 2. READ (before composing response)
|
||||
entities = extract_entity_names(text) // quick regex/NER
|
||||
context = []
|
||||
for name in entities:
|
||||
results = gbrain_search(name)
|
||||
if results:
|
||||
page = gbrain_get(results[0].slug)
|
||||
context.append(page.compiled_truth)
|
||||
|
||||
// 3. RESPOND (with brain context injected)
|
||||
response = compose_response(text, context)
|
||||
|
||||
// 4. WRITE (after responding, if new info emerged)
|
||||
if response_contains_new_info(response):
|
||||
for entity in mentioned_entities:
|
||||
gbrain_add_timeline_entry(entity.slug, {
|
||||
date: today,
|
||||
summary: "Discussed {topic}",
|
||||
source: "[Source: User, conversation, {date}]"
|
||||
})
|
||||
|
||||
// 5. SYNC
|
||||
gbrain_sync()
|
||||
```
|
||||
|
||||
### The Two Invariants
|
||||
|
||||
1. **Every READ improves the response.** If you answered a question about a
|
||||
person without checking their brain page first, you gave a worse answer
|
||||
than you could have. The brain almost always has something. External APIs
|
||||
fill gaps, they don't start from scratch.
|
||||
|
||||
2. **Every WRITE improves future reads.** If a meeting transcript mentioned
|
||||
new information about a company and you didn't update the company page,
|
||||
you created a gap that will bite you later.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Read BEFORE responding, not after.** The temptation is to respond first
|
||||
and update the brain later. But the brain context makes the response better.
|
||||
Read first.
|
||||
|
||||
2. **Don't skip the write step.** "I'll update the brain later" means never.
|
||||
Write immediately after the conversation, while the context is fresh.
|
||||
|
||||
3. **Sync after every write batch.** Without sync, the brain search index is
|
||||
stale. The next query won't find what you just wrote.
|
||||
|
||||
4. **External APIs are fallback, not primary.** `gbrain search` before
|
||||
Brave Search. `gbrain get` before Crustdata. The brain has relationship
|
||||
history, your own assessments, meeting transcripts, cross-references.
|
||||
No external API can provide that.
|
||||
|
||||
## How to Verify It Works
|
||||
|
||||
1. **Mention a person the brain knows.** Ask "what do we know about {name}?"
|
||||
The agent should search the brain and return compiled truth, not hallucinate
|
||||
or do a web search.
|
||||
|
||||
2. **Discuss something new about a known entity.** Say "I heard Acme Corp
|
||||
just raised Series B." After the conversation, check: does Acme Corp's
|
||||
brain page have a new timeline entry?
|
||||
|
||||
3. **Ask about the same person a day later.** The agent should immediately
|
||||
pull brain context without you asking. If it doesn't reference the brain
|
||||
page, the loop isn't running.
|
||||
|
||||
4. **Check the sync.** After a conversation, run `gbrain search "{topic}"`
|
||||
from the CLI. The new information should be searchable.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md). See also: [Entity Detection](entity-detection.md), [Brain-First Lookup](brain-first-lookup.md)*
|
||||
@@ -1,85 +0,0 @@
|
||||
# Brain-First Lookup Protocol
|
||||
|
||||
## Goal
|
||||
|
||||
Check the brain before calling ANY external API. The brain almost always has
|
||||
something. External APIs fill gaps, they don't start from scratch.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: the agent calls Brave Search for someone you've had 12 meetings with.
|
||||
You get a LinkedIn summary instead of your relationship history.
|
||||
|
||||
With this: the agent pulls your compiled truth, recent timeline entries, and
|
||||
shared context before doing anything else. External APIs only fill gaps.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
lookup(name_or_topic):
|
||||
// STEP 1: Keyword search (fast, works day one, no embeddings needed)
|
||||
results = gbrain search "{name_or_topic}"
|
||||
if results.length > 0:
|
||||
page = gbrain get {results[0].slug}
|
||||
return page // done, brain had it
|
||||
|
||||
// STEP 2: Hybrid search (needs embeddings, finds semantic matches)
|
||||
results = gbrain query "what do we know about {name_or_topic}"
|
||||
if results.length > 0:
|
||||
page = gbrain get {results[0].slug}
|
||||
return page
|
||||
|
||||
// STEP 3: Direct slug (if you know or can guess the slug)
|
||||
page = gbrain get "people/{slugify(name_or_topic)}"
|
||||
if page: return page
|
||||
|
||||
// STEP 4: External API (FALLBACK ONLY)
|
||||
// Only reach here if brain has nothing
|
||||
return external_search(name_or_topic)
|
||||
```
|
||||
|
||||
**This is mandatory.** An agent that calls Brave Search before checking the brain
|
||||
is wasting money and giving worse answers.
|
||||
|
||||
## Why Brain First
|
||||
|
||||
The brain has context no external API can provide:
|
||||
- Relationship history (how you know them, what you discussed)
|
||||
- Your own assessments (what you think of them, not their LinkedIn bio)
|
||||
- Meeting transcripts (what was said, what was decided)
|
||||
- Cross-references (who they know, what companies they're connected to)
|
||||
- Timeline (what changed recently, what's trending)
|
||||
|
||||
A LinkedIn scrape gives you their job title. The brain gives you: "co-founded
|
||||
Brex, you had coffee with him 3 times, last discussed the payments infrastructure
|
||||
thesis, he's interested in your take on AI agents."
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Try keyword first, then hybrid.** Keyword search works without embeddings
|
||||
(day one). Hybrid search needs embeddings but finds semantic matches. Try
|
||||
both in sequence.
|
||||
|
||||
2. **Fuzzy slug matching.** `gbrain get` supports fuzzy matching. If the exact
|
||||
slug doesn't exist, it suggests alternatives. Use this for name variants
|
||||
("Pedro" → "pedro-franceschi").
|
||||
|
||||
3. **Don't skip for "simple" questions.** Even "what's Acme Corp's address?"
|
||||
should check the brain first. The brain might have it, and the lookup adds
|
||||
no latency (< 100ms for keyword search).
|
||||
|
||||
4. **Load compiled truth + recent timeline.** The compiled truth gives you the
|
||||
state of play in 30 seconds. The timeline gives you what changed recently.
|
||||
Both together = full context.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Ask about someone in the brain. Verify the agent searched the brain FIRST
|
||||
(check tool call order in the response).
|
||||
2. Ask about someone NOT in the brain. Verify the agent searched the brain,
|
||||
found nothing, THEN fell back to external search.
|
||||
3. Ask the same question twice. Second time should be instant (brain has it).
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md). See also: [Brain-Agent Loop](brain-agent-loop.md), [Search Modes](search-modes.md)*
|
||||
@@ -1,75 +0,0 @@
|
||||
# Brain vs Memory vs Session
|
||||
|
||||
## Goal
|
||||
Know what goes in GBrain, what goes in agent memory, and what stays in session context -- so every piece of information lands in the right layer.
|
||||
|
||||
## What the User Gets
|
||||
Without this: people dossiers get stored in agent memory (lost on agent reset), user preferences get stored in GBrain (cluttering knowledge pages), and the agent re-asks questions it already knows the answer to. With this: world knowledge persists in the brain, operational state persists in agent memory, and the agent never puts information in the wrong layer.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
on new_information(info):
|
||||
# Three layers, three purposes -- route to the right one
|
||||
|
||||
if info.is_about_the_world:
|
||||
# GBRAIN: people, companies, deals, meetings, concepts, ideas
|
||||
# This is world knowledge -- facts about entities external to the agent
|
||||
gbrain put <slug> --content "..."
|
||||
# Examples:
|
||||
# "Pedro is CEO of Brex" -> gbrain (person page)
|
||||
# "Brex raised Series D at $12B" -> gbrain (company page)
|
||||
# "Tuesday's meeting covered Q2" -> gbrain (meeting page)
|
||||
# "The meatsuit maintenance tax" -> gbrain (originals page)
|
||||
|
||||
elif info.is_about_operations:
|
||||
# AGENT MEMORY: preferences, decisions, tool config, session continuity
|
||||
# This is how the agent operates -- not facts about the world
|
||||
memory_write(info)
|
||||
# Examples:
|
||||
# "User prefers concise formatting" -> agent memory
|
||||
# "Deploy to staging before prod" -> agent memory
|
||||
# "Use dark mode in code blocks" -> agent memory
|
||||
# "API key for Crustdata goes in .env" -> agent memory
|
||||
|
||||
elif info.is_current_conversation:
|
||||
# SESSION CONTEXT: what was just said, current task, immediate state
|
||||
# This is automatic -- already in the conversation window
|
||||
# No storage action needed
|
||||
# Examples:
|
||||
# "We were just discussing the board deck" -> session
|
||||
# "You asked me to review this PR" -> session
|
||||
# "The file I just shared" -> session
|
||||
|
||||
# Lookup routing:
|
||||
on user_asks(question):
|
||||
if question.about_person or question.about_company or question.about_meeting:
|
||||
gbrain search "{entity}" # -> world knowledge
|
||||
gbrain get <slug>
|
||||
|
||||
elif question.about_preference or question.about_how_to_operate:
|
||||
memory_search("{topic}") # -> operational state
|
||||
|
||||
elif question.about_current_context:
|
||||
# Already in session -- just reference conversation history
|
||||
pass
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Don't store people in agent memory.** "Pedro prefers email over Slack" feels like a preference, but it's a fact about Pedro -- it goes in GBrain on Pedro's page. Agent memory is for the agent's own operational state, not facts about people in the world.
|
||||
2. **Don't store user preferences in GBrain.** "User likes bullet points over paragraphs" is about how the agent should behave, not about the world. It goes in agent memory. GBrain pages are for entities, not for agent configuration.
|
||||
3. **Synthesis of external ideas goes in GBrain.** "User's take on Peter Thiel's zero-to-one framework" is the user's original thinking -- it goes in GBrain under originals/, not in agent memory.
|
||||
4. **Agent memory doesn't survive agent resets on some platforms.** Critical world knowledge MUST be in GBrain, which is durable. If the agent loses memory, the brain still has everything.
|
||||
5. **When in doubt, ask: is this about the world or about how to operate?** World -> GBrain. Operations -> agent memory. Current conversation -> session.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Ask the agent "Who is Pedro?" -- confirm it runs `gbrain search` or `gbrain get`, not `memory_search`. Person lookup should hit GBrain.
|
||||
2. Ask the agent "How should I format responses?" -- confirm it checks agent memory, not GBrain. Preferences are operational state.
|
||||
3. Check that no person or company pages exist in agent memory storage. Run `memory_search "person"` -- it should return preferences, not dossiers.
|
||||
4. Check that GBrain doesn't contain pages about agent behavior. Run `gbrain search "user prefers"` -- it should return nothing (preferences belong in agent memory).
|
||||
5. After an agent reset, confirm GBrain knowledge is still accessible. Run `gbrain get <any_slug>` -- world knowledge should survive the reset.
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,137 +0,0 @@
|
||||
# Compiled Truth + Timeline Pattern
|
||||
|
||||
## Goal
|
||||
|
||||
Every brain page has two zones: compiled truth (current synthesis, rewritten as
|
||||
evidence changes) and timeline (append-only evidence trail, never edited).
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: brain pages are append-only logs. To understand a person, you read
|
||||
200 timeline entries. The answer is buried in entry #147.
|
||||
|
||||
With this: the compiled truth gives you the state of play in 30 seconds. The
|
||||
timeline is the proof. Six months of entries compress into a one-paragraph
|
||||
assessment that's always current.
|
||||
|
||||
## Implementation
|
||||
|
||||
### Page Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: person
|
||||
title: Sarah Chen
|
||||
tags: [engineering, acme-corp]
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
One paragraph. How you know them, why they matter.
|
||||
|
||||
## State
|
||||
VP Engineering at Acme Corp. Managing 45-person team. Reports to CEO.
|
||||
|
||||
## What They Believe
|
||||
Strong opinions on test coverage. "Ship it when the tests pass, not before."
|
||||
|
||||
## What They're Building
|
||||
Leading the API migration from REST to GraphQL. Target: Q3 completion.
|
||||
|
||||
## Assessment
|
||||
Sharp technical leader. Under-appreciated internally. Watch for signs of burnout.
|
||||
|
||||
## Trajectory
|
||||
Ascending. Likely CTO track if the migration succeeds.
|
||||
|
||||
## Relationship
|
||||
Met through Pedro. Had coffee 3x. Last: discussed API architecture thesis.
|
||||
|
||||
## Contact
|
||||
sarah@acmecorp.com | @sarahchen | linkedin.com/in/sarahchen
|
||||
|
||||
---
|
||||
|
||||
## Timeline
|
||||
|
||||
- **2026-04-07** | Met at team sync. Discussed API migration timeline.
|
||||
Seemed energized about GraphQL pivot.
|
||||
[Source: Meeting notes, 2026-04-07 2:00 PM PT]
|
||||
- **2026-04-03** | Mentioned in email re Q2 planning. Taking lead on ops.
|
||||
[Source: Gmail, sarah@acmecorp.com, 2026-04-03 10:30 AM PT]
|
||||
- **2026-03-15** | First meeting. Intro from Pedro. Strong technical background.
|
||||
[Source: User, direct conversation, 2026-03-15 3:00 PM PT]
|
||||
```
|
||||
|
||||
### Updating a Page
|
||||
|
||||
```
|
||||
update_brain_page(slug, new_info, source):
|
||||
page = gbrain get {slug}
|
||||
|
||||
// TIMELINE: always APPEND (never edit existing entries)
|
||||
gbrain add_timeline_entry {slug} {
|
||||
date: today,
|
||||
summary: new_info.summary,
|
||||
detail: new_info.detail,
|
||||
source: format_source(source) // [Source: who, channel, date time tz]
|
||||
}
|
||||
|
||||
// COMPILED TRUTH: REWRITE (not append)
|
||||
// Read the existing compiled truth
|
||||
// Integrate new information
|
||||
// Write the updated synthesis
|
||||
updated_truth = rewrite_compiled_truth(page.compiled_truth, new_info)
|
||||
gbrain put {slug} {
|
||||
compiled_truth: updated_truth,
|
||||
// timeline is NOT passed — it's managed by add_timeline_entry
|
||||
}
|
||||
```
|
||||
|
||||
### The Rules
|
||||
|
||||
| Zone | Action | Explanation |
|
||||
|------|--------|-------------|
|
||||
| Compiled truth | **REWRITE** | Current synthesis. Changes when evidence changes. |
|
||||
| Timeline | **APPEND** | Evidence trail. Never edited, only added to. |
|
||||
|
||||
**Every compiled truth claim must trace to timeline entries.** If the Assessment
|
||||
says "under-appreciated internally," there should be timeline entries that
|
||||
support that claim.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **REWRITE means rewrite, not append.** Don't add a new paragraph to compiled
|
||||
truth. Rewrite the entire section with the new information integrated. Old
|
||||
assessments that are no longer accurate should be updated, not kept alongside
|
||||
contradictory new ones.
|
||||
|
||||
2. **Timeline entries are immutable.** Never edit a timeline entry. If information
|
||||
turns out to be wrong, add a NEW entry correcting it:
|
||||
`- 2026-04-10 | Correction: Sarah is VP Eng, not CTO. Previous entry was wrong.`
|
||||
|
||||
3. **GBrain search weights compiled truth higher.** `gbrain query` returns compiled
|
||||
truth chunks with higher relevance than timeline chunks. This means the freshest
|
||||
synthesis surfaces first in search results.
|
||||
|
||||
4. **The --- separator matters.** GBrain uses the first standalone `---` after
|
||||
frontmatter to split compiled_truth from timeline. Everything above is compiled
|
||||
truth, everything below is timeline.
|
||||
|
||||
5. **Don't skip the Assessment section.** The assessment is the value. "Strong
|
||||
technical leader" is something no API can provide. It's YOUR read on this
|
||||
person. That's what makes the brain page better than LinkedIn.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Update a person page.** Add new meeting info. Check: compiled truth was
|
||||
REWRITTEN (not appended), timeline has new entry at the top.
|
||||
2. **Search for the person.** `gbrain query "Sarah Chen"`. The compiled truth
|
||||
(current synthesis) should appear first, not a random timeline entry.
|
||||
3. **Check traceability.** Every claim in compiled truth should have a
|
||||
corresponding timeline entry. Read both sections and verify.
|
||||
4. **Check immutability.** After update, old timeline entries should be unchanged.
|
||||
Dates, sources, and content should match the originals exactly.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md). See also: [Source Attribution](source-attribution.md), [Entity Detection](entity-detection.md)*
|
||||
@@ -1,136 +0,0 @@
|
||||
# Content and Media Ingestion
|
||||
|
||||
## Goal
|
||||
YouTube videos, social media, PDFs, and documents become searchable brain pages with the agent's own analysis and full cross-references to every entity mentioned.
|
||||
|
||||
## What the User Gets
|
||||
Without this: media links are bookmarks that decay -- you remember watching a video but can't find what was said, who said it, or why it mattered. With this: every piece of media is a permanent brain page with the agent's analysis layered on top, every mentioned entity gets a back-link, and the full content is searchable forever.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
on user_shares_media(url_or_file):
|
||||
|
||||
# PATTERN 1: YouTube Video Ingestion
|
||||
if media.type == "youtube":
|
||||
# Step 1: Get FULL transcript with speaker diarization
|
||||
# WHO said WHAT -- not just a wall of text
|
||||
# Use Diarize.io or equivalent service
|
||||
transcript = diarize(video_url) # speaker-attributed transcript
|
||||
# NEVER use YouTube's auto-generated summary or AI summary
|
||||
|
||||
# Step 2: Agent writes OWN analysis (this is the value)
|
||||
# NOT a summary. NOT regurgitation. The agent's TAKE:
|
||||
# - What matters and why (given the user's worldview)
|
||||
# - Key quotes attributed to specific speakers
|
||||
# - Connections to existing brain pages
|
||||
# - Implications and follow-up angles
|
||||
analysis = agent_analyze(transcript, user_context)
|
||||
|
||||
# Step 3: Create brain page
|
||||
slug = f"media/youtube/{video_slug}"
|
||||
gbrain put <slug> --content """
|
||||
# {title}
|
||||
**Channel:** {channel} | **Date:** {date} | **Link:** {url}
|
||||
|
||||
## Analysis
|
||||
{agent_analysis}
|
||||
|
||||
## Key Quotes
|
||||
- **{Speaker}** ({timestamp}): "{quote}" -- {why_it_matters}
|
||||
|
||||
---
|
||||
## Full Transcript
|
||||
{diarized_transcript}
|
||||
"""
|
||||
|
||||
# Step 4: Extract and cross-reference entities
|
||||
for person in transcript.mentioned_people:
|
||||
gbrain add_link <slug> <person_slug>
|
||||
gbrain add_link <person_slug> <slug>
|
||||
gbrain add_timeline_entry <person_slug> \
|
||||
--entry "Discussed in {video_title}: {what_was_said}" \
|
||||
--source "YouTube: {url}"
|
||||
|
||||
# PATTERN 2: Social Media Bundles
|
||||
elif media.type == "tweet" or media.type == "social":
|
||||
# Don't just save a tweet -- reconstruct FULL context
|
||||
bundle = {
|
||||
"original": fetch_tweet(url),
|
||||
"thread": reconstruct_thread(url), # quoted tweets, replies
|
||||
"linked_articles": fetch_linked_urls(), # fetch and summarize
|
||||
"engagement": get_engagement_data(), # what resonated
|
||||
}
|
||||
|
||||
slug = f"media/social/{platform}-{author}-{date}"
|
||||
gbrain put <slug> --content """
|
||||
# {author}: {topic}
|
||||
{agent_analysis_of_full_bundle}
|
||||
|
||||
## Thread
|
||||
{reconstructed_thread}
|
||||
|
||||
## Linked Articles
|
||||
{article_summaries}
|
||||
|
||||
---
|
||||
## Raw
|
||||
{original_tweet_text}
|
||||
"""
|
||||
|
||||
# Extract entities and cross-reference
|
||||
for entity in bundle.mentioned_entities:
|
||||
gbrain add_link <slug> <entity_slug>
|
||||
gbrain add_link <entity_slug> <slug>
|
||||
|
||||
# PATTERN 3: PDFs and Documents
|
||||
elif media.type == "pdf" or media.type == "document":
|
||||
# OCR if needed (scanned PDFs)
|
||||
content = ocr_if_needed(file) or extract_text(file)
|
||||
|
||||
# For books and long-form:
|
||||
slug = f"sources/{document_slug}"
|
||||
gbrain put <slug> --content """
|
||||
# {title}
|
||||
**Author:** {author} | **Date:** {date}
|
||||
|
||||
## Chapter Summaries
|
||||
{per_chapter_summary}
|
||||
|
||||
## Key Quotes
|
||||
- p.{page}: "{quote}" -- {why_it_matters}
|
||||
|
||||
## Cross-References
|
||||
{links_to_brain_pages_for_people_and_concepts}
|
||||
|
||||
---
|
||||
## Source
|
||||
{full_text_or_key_sections}
|
||||
"""
|
||||
|
||||
for entity in document.mentioned_entities:
|
||||
gbrain add_link <slug> <entity_slug>
|
||||
gbrain add_link <entity_slug> <slug>
|
||||
|
||||
# Always sync after ingestion
|
||||
gbrain sync
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Always FULL transcript, never AI summary.** YouTube's auto-summary and AI-generated summaries lose the texture: who said what, exact phrasing, tone, what was left unsaid. The full diarized transcript is the evidence base. The agent's analysis goes above it.
|
||||
2. **The agent's OWN analysis is the value, not regurgitation.** "The video discussed AI safety" is worthless. "Dario made a specific claim about compute scaling that contradicts what Ilya said in the NeurIPS talk -- see media/youtube/ilya-neurips-2025" is useful. The analysis connects the new media to the existing brain.
|
||||
3. **Social media is a bundle, not a single tweet.** A tweet without its thread, quoted tweets, linked articles, and engagement context is a fragment. Reconstruct the full context before creating the brain page.
|
||||
4. **Cross-references make media pages alive.** A YouTube page without back-links to the people and companies mentioned is a dead archive. Every mentioned entity gets a link and a timeline entry.
|
||||
5. **Over time, `media/` becomes a searchable archive.** Every video, podcast, talk, interview, article, and tweet the user has consumed, with the agent's commentary layered on top. This is the memex at full power.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Ingest a YouTube video. Run `gbrain get media/youtube/{slug}`. Confirm the page has: the agent's analysis (not just a summary), key quotes with speaker attribution, and the full diarized transcript.
|
||||
2. Run `gbrain get_links media/youtube/{slug}`. Confirm back-links exist to brain pages for every person and company mentioned in the video.
|
||||
3. Pick a person mentioned in the video. Run `gbrain get <person_slug>`. Confirm their timeline has a new entry referencing the video with specific context.
|
||||
4. Ingest a tweet. Confirm the brain page includes the thread context, linked article summaries, and entity cross-references -- not just the tweet text.
|
||||
5. Run `gbrain search "{topic_from_video}"`. Confirm the media page appears in search results (verifies the content is indexed and searchable).
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,193 +0,0 @@
|
||||
# Reference Cron Schedule
|
||||
|
||||
## Goal
|
||||
|
||||
A production brain runs 20+ recurring jobs that keep it alive, current, and
|
||||
compounding. This guide shows the schedule, the patterns, and how to set it up.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: the brain only updates when you manually ingest data. Pages go
|
||||
stale, entities are thin, citations break, and the agent answers from old context.
|
||||
|
||||
With this: the brain maintains itself. Email, social, calendar, and meetings
|
||||
flow in automatically. Thin pages get enriched overnight. Broken citations get
|
||||
fixed. You wake up and the brain is smarter than when you went to sleep.
|
||||
|
||||
## The Schedule
|
||||
|
||||
| Frequency | Job | Brain Interaction | Recipe |
|
||||
|-----------|-----|-------------------|--------|
|
||||
| Every 30 min | Email monitoring | Search sender, update people pages | [email-to-brain](../../recipes/email-to-brain.md) |
|
||||
| Every 30 min | X/Twitter collection | Create/update media pages, entity extraction | [x-to-brain](../../recipes/x-to-brain.md) |
|
||||
| 3x/day (weekdays) | Meeting sync | Full ingestion + attendee propagation | [meeting-sync](../../recipes/meeting-sync.md) |
|
||||
| Weekly | Calendar sync | Daily files + attendee enrichment | [calendar-to-brain](../../recipes/calendar-to-brain.md) |
|
||||
| Daily AM | Morning briefing | Search calendar attendees, deal status, active threads | [briefing skill](../../skills/briefing/SKILL.md) |
|
||||
| Weekly | Brain maintenance | `gbrain doctor`, embed stale, orphan detection | [maintain skill](../../skills/maintain/SKILL.md) |
|
||||
| Nightly | Dream cycle | Entity sweep, enrich thin spots, fix citations | See below |
|
||||
|
||||
## Implementation: Setting Up Cron Jobs
|
||||
|
||||
```bash
|
||||
# Email collector — every 30 minutes
|
||||
*/30 * * * * cd /path/to/email-collector && node email-collector.mjs collect && node email-collector.mjs digest
|
||||
|
||||
# X/Twitter collector — every 30 minutes
|
||||
*/30 * * * * cd /path/to/x-collector && node x-collector.mjs collect >> /tmp/x-collector.log 2>&1
|
||||
|
||||
# Meeting sync — 10 AM, 4 PM, 9 PM on weekdays
|
||||
0 10,16,21 * * 1-5 cd /path/to/meeting-sync && node meeting-sync.mjs >> /tmp/meeting-sync.log 2>&1
|
||||
|
||||
# Calendar sync — Sundays at 10 AM
|
||||
0 10 * * 0 cd /path/to/calendar-sync && node calendar-sync.mjs --start $(date -v-7d +%Y-%m-%d) --end $(date +%Y-%m-%d)
|
||||
|
||||
# Brain health — weekly Mondays at 6 AM
|
||||
0 6 * * 1 gbrain doctor --json >> /tmp/gbrain-health.log 2>&1 && gbrain embed --stale
|
||||
|
||||
# Dream cycle — nightly at 2 AM
|
||||
0 2 * * * /path/to/dream-cycle.sh
|
||||
```
|
||||
|
||||
### Quiet Hours Gate (MANDATORY)
|
||||
|
||||
Every cron job that sends notifications MUST check quiet hours first.
|
||||
See [Quiet Hours](quiet-hours.md) for the full pattern.
|
||||
|
||||
```bash
|
||||
# In every cron script:
|
||||
if ! bash scripts/quiet-hours-gate.sh; then
|
||||
mkdir -p /tmp/cron-held
|
||||
echo "$OUTPUT" > /tmp/cron-held/$(basename "$0" .sh).md
|
||||
exit 0
|
||||
fi
|
||||
# Not quiet hours — send normally
|
||||
```
|
||||
|
||||
### Travel-Aware Timezone Handling
|
||||
|
||||
The agent reads your calendar for flights, hotels, and out-of-office blocks to
|
||||
infer your current location and timezone. All times shown in YOUR local timezone.
|
||||
|
||||
```
|
||||
// Example: user flew to Tokyo
|
||||
// 2 PM Pacific = 3 AM Tokyo = quiet hours
|
||||
// Hold the notification, fold into morning briefing
|
||||
|
||||
get_user_timezone():
|
||||
calendar = gbrain search "flight" --type calendar --recent 7d
|
||||
if recent_flight:
|
||||
return infer_timezone(flight.destination)
|
||||
return config.default_timezone // fallback: US/Pacific
|
||||
```
|
||||
|
||||
When you travel: cron jobs that would fire during your waking hours at home but
|
||||
hit your sleeping hours at the destination get held and folded into the next
|
||||
morning briefing. Zero config change needed.
|
||||
|
||||
## The Dream Cycle
|
||||
|
||||
The most important cron job. Runs while you sleep.
|
||||
|
||||
### What It Does
|
||||
|
||||
```
|
||||
dream_cycle():
|
||||
// Phase 1: Entity Sweep
|
||||
conversations = get_todays_conversations()
|
||||
for message in conversations:
|
||||
entities = detect_entities(message)
|
||||
for entity in entities:
|
||||
page = gbrain search "{entity.name}"
|
||||
if not page:
|
||||
create_page(entity) // new entity, create + enrich
|
||||
elif page.is_thin():
|
||||
enrich_page(entity) // thin page, fill it out
|
||||
else:
|
||||
update_timeline(entity) // existing page, add today's mentions
|
||||
|
||||
// Phase 2: Fix Broken Citations
|
||||
pages = gbrain list --type person --limit 100
|
||||
for page in pages:
|
||||
for entry in page.timeline:
|
||||
if not entry.has_source_attribution():
|
||||
fix_citation(entry) // add [Source: ...] where missing
|
||||
if entry.has_tweet_url() and not entry.url_is_valid():
|
||||
fix_url(entry) // broken tweet links
|
||||
|
||||
// Phase 3: Consolidate Memory
|
||||
patterns = detect_patterns_across_conversations()
|
||||
for pattern in patterns:
|
||||
promote_to_memory(pattern) // ephemeral → durable knowledge
|
||||
|
||||
// Phase 4: Sync
|
||||
gbrain sync --no-pull --no-embed
|
||||
gbrain embed --stale
|
||||
```
|
||||
|
||||
### Setting Up the Dream Cycle
|
||||
|
||||
**OpenClaw:** Ships with DREAMS.md as a default skill. Three phases (light,
|
||||
deep, REM) run automatically during quiet hours.
|
||||
|
||||
**Hermes Agent:**
|
||||
```bash
|
||||
/cron add "0 2 * * *" "Dream cycle: search today's sessions for
|
||||
entities I mentioned. For each person, company, or idea: check
|
||||
if a brain page exists (gbrain search), create or update it if
|
||||
thin. Fix any broken citations. Then consolidate: read MEMORY.md,
|
||||
promote important signals, remove stale entries."
|
||||
--name "nightly-dream-cycle"
|
||||
```
|
||||
|
||||
**Claude Code / Custom agents:** Create a script:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# dream-cycle.sh
|
||||
|
||||
# Check quiet hours (should be quiet — that's when we run)
|
||||
echo "Dream cycle starting at $(date)"
|
||||
|
||||
# Phase 1: Entity sweep (spawn sub-agent)
|
||||
# Read today's conversation logs, extract entities, update brain
|
||||
|
||||
# Phase 2: Citation hygiene
|
||||
gbrain doctor --json | jq '.checks[] | select(.status=="warn")'
|
||||
|
||||
# Phase 3: Embed any stale content
|
||||
gbrain embed --stale
|
||||
|
||||
echo "Dream cycle complete at $(date)"
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **The dream cycle is NOT optional.** Without it, signal leaks out of every
|
||||
conversation. With it, nothing is lost. This is the difference between an
|
||||
agent that forgets and one that remembers.
|
||||
|
||||
2. **Quiet hours gate on EVERY notification job.** If you skip it, the user
|
||||
gets pinged at 3 AM. One 3 AM ping and they'll disable the whole system.
|
||||
|
||||
3. **Don't over-cron.** 20+ jobs sounds like a lot. Start with: email (30 min),
|
||||
dream cycle (nightly), brain health (weekly). Add more as you add
|
||||
integration recipes.
|
||||
|
||||
4. **Timezone changes are automatic.** Don't make the user reconfigure cron
|
||||
when they travel. Read the calendar, infer the timezone, adjust delivery.
|
||||
|
||||
5. **Held messages MUST be picked up.** If quiet hours hold a notification,
|
||||
the morning briefing MUST include it. Otherwise information is lost.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Quiet hours:** Set quiet hours to current hour. Run a notification cron.
|
||||
Verify output went to `/tmp/cron-held/`, not to messaging.
|
||||
2. **Dream cycle:** Run the dream cycle manually. Check that thin entity pages
|
||||
got enriched and broken citations were fixed.
|
||||
3. **Email collector cron:** Wait 30 minutes. Check `data/digests/` for new digest.
|
||||
4. **Morning briefing:** Check that held messages appear in the briefing.
|
||||
5. **Health check:** Run `gbrain doctor --json`. All checks should pass.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md). See also: [Quiet Hours](quiet-hours.md), [Operational Disciplines](operational-disciplines.md)*
|
||||
@@ -1,146 +0,0 @@
|
||||
# Deterministic Collectors: Code for Data, LLMs for Judgment
|
||||
|
||||
## Goal
|
||||
|
||||
Separate mechanical work (100% reliable code) from analytical work (LLM judgment) so that deterministic tasks never fail probabilistically.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: the LLM generates Gmail links, formats tables, and tracks state.
|
||||
It follows the rule for the first 10 items, then drops a link on item 11. You
|
||||
write "NO EXCEPTIONS" in the prompt. It still fails. 90% reliability over 20
|
||||
items means visible failures twice per day. Trust is destroyed.
|
||||
|
||||
With this: code handles URLs, formatting, and state (100% reliable). The LLM
|
||||
reads pre-formatted data and adds judgment, classification, and enrichment.
|
||||
Links are never wrong because the LLM never generates them.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
// The pattern: code collects, LLM analyzes
|
||||
|
||||
// STEP 1: Deterministic collector (script, no LLM calls)
|
||||
collector_run():
|
||||
messages = gmail_api.fetch_unread()
|
||||
for msg in messages:
|
||||
structured = {
|
||||
id: msg.id,
|
||||
from: msg.sender,
|
||||
subject: msg.subject,
|
||||
snippet: msg.snippet,
|
||||
gmail_link: f"https://mail.google.com/mail/u/?authuser={account}#inbox/{msg.id}",
|
||||
gmail_markdown: f"[Open in Gmail]({gmail_link})",
|
||||
is_signature: regex_match(msg, DOCUSIGN_PATTERNS),
|
||||
is_noise: regex_match(msg, NOISE_PATTERNS),
|
||||
is_new: msg.id not in state.seen_ids
|
||||
}
|
||||
store(structured)
|
||||
state.seen_ids.add(msg.id)
|
||||
generate_markdown_digest(structured_messages)
|
||||
|
||||
// STEP 2: LLM reads the pre-formatted digest
|
||||
llm_analyze():
|
||||
digest = read("data/digests/today.md") // links already baked in
|
||||
classify_urgency(digest) // judgment call
|
||||
add_commentary(digest) // contextual analysis
|
||||
run_brain_enrichment(notable_entities) // gbrain search + update
|
||||
draft_replies(urgent_items) // creative work
|
||||
surface_to_user(final_output) // delivery
|
||||
|
||||
// STEP 3: Wire into cron
|
||||
cron_job():
|
||||
collector_run() // fast, cheap, deterministic
|
||||
llm_analyze() // slower, expensive, creative
|
||||
```
|
||||
|
||||
### The Architecture
|
||||
|
||||
```
|
||||
+-----------------------------+ +------------------------------+
|
||||
| Deterministic Collector |---->| LLM Agent |
|
||||
| (Node.js / Python script) | | |
|
||||
| | | - Read the pre-formatted |
|
||||
| - Pull data from API | | digest |
|
||||
| - Store structured JSON | | - Classify items |
|
||||
| - Generate links/URLs | | - Add commentary |
|
||||
| - Detect patterns (regex) | | - Run brain enrichment |
|
||||
| - Track state (seen/new) | | - Draft replies |
|
||||
| - Output markdown digest | | - Surface to user |
|
||||
| | | |
|
||||
| CODE — deterministic, | | AI — judgment, context, |
|
||||
| never forgets | | creativity |
|
||||
+-----------------------------+ +------------------------------+
|
||||
```
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
scripts/email-collector/
|
||||
├── email-collector.mjs # No LLM calls, no external deps
|
||||
├── data/
|
||||
│ ├── state.json # Last pull timestamp, known IDs, pending signatures
|
||||
│ ├── messages/ # Structured JSON per day
|
||||
│ │ └── 2026-04-09.json
|
||||
│ └── digests/ # Pre-formatted markdown
|
||||
│ └── 2026-04-09.md
|
||||
```
|
||||
|
||||
### Where the Pattern Applies
|
||||
|
||||
| Signal Source | Collector Generates | LLM Adds |
|
||||
|--------------|-------------------|----------|
|
||||
| **Email** | Gmail links, sender metadata, signature detection | Urgency classification, enrichment, reply drafts |
|
||||
| **X/Twitter** | Tweet links, engagement metrics, deletion detection | Sentiment analysis, narrative detection, content ideas |
|
||||
| **Calendar** | Event links, attendee lists, conflict detection | Prep briefings, meeting context from brain |
|
||||
| **Slack** | Channel links, thread links, mention detection | Priority classification, action item extraction |
|
||||
| **GitHub** | PR/issue links, diff stats, CI status | Code review context, priority assessment |
|
||||
|
||||
### The Principle
|
||||
|
||||
If a piece of output MUST be present and MUST be formatted correctly every
|
||||
time, generate it in code. If a piece of output requires judgment, context,
|
||||
or creativity, generate it with the LLM. Don't ask the LLM to do both in
|
||||
the same pass.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **LLMs forget links -- bake them in code.** The LLM will follow the
|
||||
"include a Gmail link" rule for the first 10 items, then silently drop
|
||||
it on item 11. No amount of prompt engineering fixes probabilistic
|
||||
formatting over long outputs. The fix: generate every link in the
|
||||
collector script. The LLM reads pre-formatted markdown where links are
|
||||
already embedded. It can't forget what it didn't generate.
|
||||
|
||||
2. **Noise filtering must be deterministic.** Regex-based noise detection
|
||||
(newsletters, automated receipts, marketing) belongs in the collector,
|
||||
not the LLM. The LLM might classify a newsletter as "possibly important"
|
||||
on one run and "noise" on the next. Code classifies the same input the
|
||||
same way every time.
|
||||
|
||||
3. **Atomic writes prevent corruption.** The collector writes to a state
|
||||
file (`state.json`) that tracks which messages have been seen. If the
|
||||
script crashes mid-write, the state file can be corrupted. Write to a
|
||||
temp file first, then rename atomically. This also prevents the LLM
|
||||
from reading a partial digest if the cron fires during a collection run.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Run the collector and check every link.** Execute the collector script
|
||||
manually. Open the generated digest. Click every `[Open in Gmail]` link
|
||||
(or equivalent). Every single link must resolve to the correct item. If
|
||||
any link is broken or missing, the collector has a bug.
|
||||
|
||||
2. **Verify noise filtering is consistent.** Run the collector twice on the
|
||||
same input data. The noise classification (is_noise field) must be
|
||||
identical both times. If it varies, a probabilistic element leaked into
|
||||
the deterministic layer.
|
||||
|
||||
3. **Verify the LLM reads structured output.** Run the full pipeline
|
||||
(collector then LLM). Check that the LLM's analysis references data
|
||||
from the structured digest, not from its own generation. The links in
|
||||
the final output should be identical to the links in the digest file.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,151 +0,0 @@
|
||||
# Diligence Ingestion: Data Room to Brain Pages
|
||||
|
||||
## Goal
|
||||
|
||||
Turn pitch decks, financial models, and data room materials into searchable, cross-referenced brain pages with bull/bear analysis.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: pitch decks sit in email attachments. Financial models in Google
|
||||
Drive. No cross-reference to the company brain page. You can't search "what
|
||||
were the key metrics from Acme Corp's Series A deck?"
|
||||
|
||||
With this: every data room document is extracted, diarized, cross-referenced to
|
||||
the company page, and searchable. Index.md gives you the bull/bear case at a
|
||||
glance. `gbrain query "Acme Corp revenue growth"` finds the exact chart.
|
||||
|
||||
## Implementation
|
||||
|
||||
Recognize data room materials by PDF filenames containing "Data Deck", "Intro
|
||||
Deck", "Data Room", "Cap Table", "Financial Model", "Investor Memo", "Pitch
|
||||
Deck", or series round names. Spreadsheet tabs with Revenue, Retention, Cohorts,
|
||||
CAC, Gross Margin, Unit Economics, ARR. User language like "data room",
|
||||
"diligence", "deck", "pitch", "fundraise materials".
|
||||
|
||||
### The 9-Step Pipeline
|
||||
|
||||
**Step 1: Identify the Company.**
|
||||
From the document content or filename, identify the company name.
|
||||
Check if `brain/companies/{slug}.md` exists.
|
||||
|
||||
**Step 2: Create Diligence Directory.**
|
||||
|
||||
```bash
|
||||
mkdir -p brain/diligence/{company-slug}/.raw
|
||||
```
|
||||
|
||||
**Step 3: Extract Content.**
|
||||
|
||||
- **PDFs:** Use PDF extraction tool. For scanned/image-heavy PDFs,
|
||||
use OCR (e.g., Mistral OCR or similar).
|
||||
- **Spreadsheets:** Export each sheet as CSV. For Google Sheets:
|
||||
```
|
||||
https://docs.google.com/spreadsheets/d/{ID}/gviz/tq?tqx=out:csv&sheet={Sheet Name}
|
||||
```
|
||||
|
||||
**Step 4: Diarize and Save.**
|
||||
Write extracted content to `brain/diligence/{company}/{doc-name}.md`:
|
||||
- Document title and type
|
||||
- Section-by-section breakdown with key metrics
|
||||
- Notable footnotes or caveats
|
||||
- Raw data tables where relevant
|
||||
|
||||
**Step 5: Save Raw Files.**
|
||||
Copy original PDFs/files to `brain/diligence/{company}/.raw/`
|
||||
Preserve originals for reference. The diarized version is for search.
|
||||
|
||||
**Step 6: Create or Update index.md.**
|
||||
Every diligence directory needs an `index.md`:
|
||||
|
||||
```markdown
|
||||
# {Company Name} — Diligence
|
||||
|
||||
## Round Details
|
||||
- Stage: Series A
|
||||
- Amount: $10M
|
||||
- Date: 2026-04
|
||||
|
||||
## Document Inventory
|
||||
- [Pitch Deck](pitch-deck.md) — 25 slides, company overview + traction
|
||||
- [Financial Model](financial-model.md) — 5 tabs, 3-year projections
|
||||
- [Cap Table](cap-table.md) — current ownership + option pool
|
||||
|
||||
## Key Findings
|
||||
- Revenue growing 30% MoM for last 6 months
|
||||
- CAC payback period: 4 months
|
||||
- Net retention: 135%
|
||||
|
||||
## Bull Case
|
||||
- Strong product-market fit signal (NPS 72)
|
||||
- Expanding into adjacent vertical
|
||||
|
||||
## Bear Case
|
||||
- Single customer represents 40% of revenue
|
||||
- Burn rate increased 3x last quarter
|
||||
|
||||
## Open Questions
|
||||
- What's the path to profitability?
|
||||
- How defensible is the moat?
|
||||
```
|
||||
|
||||
**Step 7: Enrich Company Brain Page.**
|
||||
Update `brain/companies/{slug}.md`:
|
||||
- Add document sources to frontmatter
|
||||
- Update compiled truth with key findings
|
||||
- Add "See Also" link to diligence directory
|
||||
- If no company page exists, create one via the enrich skill
|
||||
|
||||
**Step 8: Commit.**
|
||||
|
||||
```bash
|
||||
cd brain/ && git add -A && git commit -m "diligence: {Company} — {doc type} ingestion" && git push
|
||||
```
|
||||
|
||||
**Step 9: Publish (if asked).**
|
||||
When the user wants a shareable brief, create a password-protected
|
||||
published version. Strip internal notes and raw assessment language.
|
||||
|
||||
### Quality Bar
|
||||
|
||||
A good diligence page reads like an intelligence assessment:
|
||||
- **What they say** vs **what the data shows** (the gap is the insight)
|
||||
- Explicit bull/bear case (not just a summary)
|
||||
- Key metrics highlighted, not buried
|
||||
- Open questions that need answers before decision
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **PDF extraction is lossy.** Scanned decks and image-heavy PDFs lose
|
||||
tables and charts during extraction. Always check the diarized output
|
||||
against the original `.raw/` file. If key metrics are missing, re-extract
|
||||
with OCR or transcribe manually.
|
||||
|
||||
2. **Idempotency on re-ingestion.** If the user sends an updated deck for
|
||||
the same company, don't create a duplicate directory. Check for an existing
|
||||
`brain/diligence/{company-slug}/` and update in place. Append a version
|
||||
suffix to the document file if the old version should be preserved.
|
||||
|
||||
3. **index.md completeness.** The index.md is the entry point for the entire
|
||||
diligence package. If it's missing the bull/bear case or open questions,
|
||||
the diligence is incomplete. Always generate all sections even if some
|
||||
require judgment calls -- flag uncertain assessments explicitly.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Search for key metrics.** After ingestion, run
|
||||
`gbrain search "revenue growth"` or `gbrain search "{company name} CAC"`.
|
||||
The diarized content should appear in results. If it doesn't, the sync
|
||||
or embedding step was missed.
|
||||
|
||||
2. **Check the company page cross-reference.** Open
|
||||
`brain/companies/{slug}.md` and verify it links to the diligence directory.
|
||||
The compiled truth section should include key findings from the deck.
|
||||
|
||||
3. **Verify index.md has all sections.** Open
|
||||
`brain/diligence/{company}/index.md` and confirm it has Round Details,
|
||||
Document Inventory, Key Findings, Bull Case, Bear Case, and Open Questions.
|
||||
Missing sections mean the pipeline stopped early.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,103 +0,0 @@
|
||||
# Enrichment Pipeline
|
||||
|
||||
## Goal
|
||||
Enrich brain pages from external APIs with tiered spend -- full pipeline for key people, light touch for passing mentions, raw data preserved for auditability.
|
||||
|
||||
## What the User Gets
|
||||
Without this: brain pages are thin shells with only what the user manually typed, API calls are wasted on nobodies, and enrichment data vanishes after the agent session ends. With this: key people have rich, multi-source portraits; spend scales to importance; raw API responses are preserved for re-processing; and cross-references connect the entire graph.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
on enrich(entity, trigger):
|
||||
# trigger: meeting mention, email thread, social interaction, user request
|
||||
|
||||
# Step 1: Identify entities from the incoming signal
|
||||
entities = extract_entities(signal)
|
||||
# people names, company names, associations
|
||||
|
||||
# Step 2: Check brain state -- UPDATE or CREATE path?
|
||||
for entity in entities:
|
||||
existing = gbrain search "{entity.name}"
|
||||
if existing:
|
||||
page = gbrain get <entity_slug>
|
||||
path = "UPDATE"
|
||||
else:
|
||||
path = "CREATE"
|
||||
|
||||
# Step 3: Determine tier -- scale spend to importance
|
||||
tier = classify_tier(entity):
|
||||
# Tier 1 (10-15 API calls): key people, inner circle, business partners,
|
||||
# portfolio companies. Full pipeline, ALL data sources.
|
||||
# Tier 2 (3-5 API calls): notable people, occasional interactions.
|
||||
# Web search + social + brain cross-reference.
|
||||
# Tier 3 (1-2 API calls): minor mentions, everyone else worth tracking.
|
||||
# Brain cross-reference + social lookup if handle known.
|
||||
|
||||
# Step 4: Run external lookups (priority order, stop when enough signal)
|
||||
data = {}
|
||||
data["brain"] = gbrain search "{entity.name}" # Always first (free)
|
||||
if tier <= 2:
|
||||
data["web"] = brave_search("{entity.name}") # Background, press, talks
|
||||
if tier <= 2:
|
||||
data["twitter"] = twitter_lookup(entity.handle) # Beliefs, building, network
|
||||
if tier == 1:
|
||||
data["linkedin"] = crustdata_enrich(entity.name) # Career, connections
|
||||
data["research"] = happenstance_research(entity) # Career arcs, web presence
|
||||
data["funding"] = captain_api(entity.company) # Funding, valuation, team
|
||||
data["meetings"] = circleback_search(entity.name) # Transcript search
|
||||
data["contacts"] = google_contacts(entity.email) # Contact data
|
||||
|
||||
# Step 5: Store raw data (auditable, re-processable)
|
||||
gbrain put_raw_data <entity_slug> \
|
||||
--data '{"sources": {"crustdata": {"fetched_at": "...", "data": {...}}, ...}}'
|
||||
# Overwrite on re-enrichment, don't append
|
||||
|
||||
# Step 6: Write to brain page
|
||||
if path == "CREATE":
|
||||
gbrain put <entity_slug> --content "<compiled_truth_from_all_sources>"
|
||||
gbrain add_timeline_entry <entity_slug> --entry "Page created via enrichment"
|
||||
elif path == "UPDATE":
|
||||
# Append timeline, update compiled truth ONLY if materially new
|
||||
gbrain add_timeline_entry <entity_slug> --entry "Enriched: {new_signal}"
|
||||
# Flag contradictions -- don't silently resolve them
|
||||
|
||||
# Step 7: Cross-reference the graph
|
||||
gbrain add_link <person_slug> <company_slug> # person -> company
|
||||
gbrain add_link <company_slug> <person_slug> # company -> person
|
||||
gbrain add_link <person_slug> <deal_slug> # person -> deal
|
||||
# Every entity page links to every other entity page that references it
|
||||
|
||||
# People page sections (not a LinkedIn profile -- a living portrait):
|
||||
# Executive Summary, State, What They Believe, What They're Building,
|
||||
# What Motivates Them, Assessment, Trajectory, Relationship, Contact, Timeline
|
||||
# Facts are table stakes. TEXTURE is the value.
|
||||
|
||||
# Extract texture, not just facts:
|
||||
# Opinion expressed? -> What They Believe
|
||||
# Building or shipping? -> What They're Building
|
||||
# Emotion expressed? -> What Makes Them Tick
|
||||
# Who did they engage with? -> Network / Relationship
|
||||
# Recurring topic? -> Hobby Horses
|
||||
# Committed to something? -> Open Threads
|
||||
# Energy level? -> Trajectory
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Don't overwrite human-written assessments.** If the user wrote an Assessment section with their own read on someone, API enrichment NEVER overwrites it. API data goes into State, Contact, Timeline. The user's assessment is sacrosanct.
|
||||
2. **Don't re-enrich the same page more than once per week.** Check `put_raw_data` timestamps before running the pipeline again. Enrichment is expensive and data doesn't change that fast.
|
||||
3. **LinkedIn connection count < 20 means wrong person.** Crustdata sometimes returns a different person with the same name. If the LinkedIn profile has fewer than 20 connections, it's almost certainly a false match. Discard it.
|
||||
4. **X/Twitter is the most underrated data source.** When you have someone's handle, their tweets reveal beliefs, what they're building, hobby horses, network (reply patterns), and trajectory (posting frequency, tone shifts). This is richer than LinkedIn for "What They Believe" and "What Makes Them Tick."
|
||||
5. **Cross-references are not optional.** After enriching a person, update their company page. After enriching a company, update founder pages. An enriched page without cross-links is a dead end in the graph.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Enrich a Tier 1 person. Run `gbrain get <slug>` and confirm the page has Executive Summary, State, What They Believe, Contact, and Timeline sections populated from multiple sources.
|
||||
2. Run `gbrain get_raw_data <slug>`. Confirm raw API responses are stored with `sources.{provider}.fetched_at` timestamps.
|
||||
3. Run `gbrain get_links <slug>`. Confirm cross-reference links exist to the person's company page, deal pages, and related entities.
|
||||
4. Check a page that was enriched AND has a user-written Assessment. Confirm the Assessment section was preserved, not overwritten by API data.
|
||||
5. Try to re-enrich the same person. Confirm the system checks the `fetched_at` timestamp and skips if less than a week old.
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,190 +0,0 @@
|
||||
# Entity Detection: Run It on Every Message
|
||||
|
||||
## Goal
|
||||
|
||||
Every inbound message gets scanned for original thinking AND entity mentions so the brain grows on every conversation, automatically.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: the agent answers questions but forgets everything. You mention
|
||||
Pedro in a meeting, and next week the agent doesn't know who Pedro is.
|
||||
|
||||
With this: every person, company, and idea mentioned in conversation gets a
|
||||
brain page. Next time Pedro comes up, the agent already has context. The
|
||||
brain compounds.
|
||||
|
||||
## Implementation
|
||||
|
||||
Spawn a lightweight sub-agent on EVERY inbound message. Do NOT wait for it
|
||||
to finish before responding. It runs in parallel.
|
||||
|
||||
```
|
||||
on_every_message(message_text, source_context):
|
||||
|
||||
// 1. SPAWN ASYNC — don't block the response
|
||||
spawn_subagent({
|
||||
model: "sonnet-class", // cheap + fast, not opus
|
||||
timeout: 120, // seconds
|
||||
task: build_detection_prompt(message_text, source_context)
|
||||
})
|
||||
|
||||
// 2. RESPOND TO USER NORMALLY
|
||||
// The sub-agent runs in the background
|
||||
```
|
||||
|
||||
### The Detection Prompt
|
||||
|
||||
```
|
||||
build_detection_prompt(text, source):
|
||||
return `
|
||||
SIGNAL DETECTION — scan this message for ideas AND entities:
|
||||
|
||||
Message: "${text}"
|
||||
Source: [Source: User, ${source.topic}, ${source.platform}, ${source.timestamp}]
|
||||
|
||||
STEP 1 — IDEAS FIRST (highest priority):
|
||||
Is the user expressing an original thought, observation, thesis, or framework?
|
||||
|
||||
If yes:
|
||||
- Create or update brain/originals/{slug}.md
|
||||
- Use the user's EXACT phrasing (the language IS the insight)
|
||||
- "The ambition-to-lifespan ratio has never been more broken" is better
|
||||
than "tension between ambition and mortality"
|
||||
- Include [Source: ...] citation with full context
|
||||
|
||||
If the idea references a world concept: brain/concepts/{slug}.md
|
||||
If it's a product/business idea: brain/ideas/{slug}.md
|
||||
|
||||
STEP 2 — ENTITIES:
|
||||
Extract all person names, company names, media titles.
|
||||
|
||||
For each entity:
|
||||
a. Run: gbrain search "{name}"
|
||||
b. If page exists AND new info: append timeline entry
|
||||
Format: - YYYY-MM-DD | {what happened} [Source: {who}, {context}, {date}]
|
||||
c. If no page AND entity is notable: create page with web enrichment
|
||||
d. If page is thin (< 5 lines compiled truth): spawn background enrichment
|
||||
|
||||
STEP 3 — BACK-LINKING (mandatory):
|
||||
For every entity mentioned, add a back-link FROM their page TO this source.
|
||||
An unlinked mention is a broken brain.
|
||||
Format: - **YYYY-MM-DD** | Referenced in [{page title}]({path}) — {context}
|
||||
|
||||
STEP 4 — SYNC:
|
||||
Run: gbrain sync --no-pull --no-embed
|
||||
|
||||
If nothing to capture, reply "No signals detected" and exit.
|
||||
`
|
||||
```
|
||||
|
||||
### Notability Filtering
|
||||
|
||||
Before creating a new entity page, check notability:
|
||||
|
||||
```
|
||||
is_notable(entity):
|
||||
// CREATE a page for:
|
||||
- People the user knows or discusses with specificity
|
||||
- Companies the user is evaluating, working with, or investing in
|
||||
- Media the user mentions with personal reaction
|
||||
- Anyone the user has explicitly engaged with
|
||||
|
||||
// DON'T create a page for:
|
||||
- Generic references or passing examples
|
||||
- Low-engagement accounts who mentioned the user once
|
||||
- Pure metaphors ("like the Roman Empire...")
|
||||
- One-off encounters with no follow-up
|
||||
|
||||
// If notable AND no page: create FULL page (not a stub)
|
||||
// If not notable: skip silently
|
||||
```
|
||||
|
||||
### What Counts as Original Thinking
|
||||
|
||||
| Capture | Don't Capture |
|
||||
|---------|---------------|
|
||||
| Original observations about how the world works | "ok", "do it", "sure" |
|
||||
| Novel connections between disparate things | Pure questions without observations |
|
||||
| Frameworks and mental models | Echoing back what the agent said |
|
||||
| Pattern recognition ("I keep seeing X in every Y") | Acknowledgments and reactions |
|
||||
| Hot takes with reasoning | Routine operational messages |
|
||||
| Metaphors that reveal new angles | Requests without embedded insight |
|
||||
|
||||
### Filing Rules
|
||||
|
||||
| Signal | Destination |
|
||||
|--------|-------------|
|
||||
| User generated the idea | `brain/originals/{slug}.md` |
|
||||
| User's synthesis of others' ideas | `brain/originals/` (the synthesis is original) |
|
||||
| World concept someone else coined | `brain/concepts/{slug}.md` |
|
||||
| Product or business idea | `brain/ideas/{slug}.md` |
|
||||
| Person mentioned | `brain/people/{slug}.md` |
|
||||
| Company mentioned | `brain/companies/{slug}.md` |
|
||||
| Media referenced | `brain/media/{type}/{slug}.md` |
|
||||
|
||||
### The Iron Law of Back-Linking
|
||||
|
||||
Every entity mention MUST create a back-link FROM the entity page TO the
|
||||
source. This is not optional.
|
||||
|
||||
```
|
||||
// When message mentions "Pedro" and creates a meeting page:
|
||||
|
||||
// 1. Update the meeting page (normal)
|
||||
brain/meetings/2026-04-10-board-sync.md:
|
||||
- Pedro presented Q1 numbers
|
||||
|
||||
// 2. ALSO update Pedro's page (back-link)
|
||||
brain/people/pedro-franceschi.md:
|
||||
## Timeline
|
||||
- **2026-04-10** | Presented Q1 numbers at board sync
|
||||
[Source: User, board meeting, 2026-04-10]
|
||||
```
|
||||
|
||||
Without back-links, you can't traverse the graph. "Show me everything related
|
||||
to Pedro" only works if Pedro's page links back to every mention.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Don't block the conversation.** Entity detection runs async. The user
|
||||
should see a response immediately, not wait 2 minutes while the sub-agent
|
||||
enriches 5 entity pages.
|
||||
|
||||
2. **Sonnet, not Opus.** Entity detection is pattern matching, not deep
|
||||
reasoning. Sonnet is 5-10x cheaper and fast enough. Use Opus for the
|
||||
main conversation.
|
||||
|
||||
3. **Exact phrasing matters.** "Markdown is actually code" is an insight.
|
||||
"Markdown can be used as code" is a summary. Capture the first version.
|
||||
|
||||
4. **Don't create stubs.** If you create a page, make it good. Run a web
|
||||
search, build out the compiled truth, add context. A stub page with just
|
||||
a name is worse than no page (it gives false confidence).
|
||||
|
||||
5. **Dedup before creating.** Always `gbrain search` before creating a page.
|
||||
Variant spellings, nicknames, and company abbreviations cause duplicates.
|
||||
"Pedro Franceschi" and "Pedro" might be the same person.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Send a message mentioning a person.** Say "I had coffee with Sarah Chen
|
||||
from Acme Corp today." Verify: brain/people/sarah-chen.md was created or
|
||||
updated, brain/companies/acme-corp.md was created or updated, both have
|
||||
timeline entries with today's date.
|
||||
|
||||
2. **Send a message with an original idea.** Say "What if we could distribute
|
||||
software as markdown files that agents execute?" Verify:
|
||||
brain/originals/{slug}.md was created with your exact phrasing.
|
||||
|
||||
3. **Check back-links.** Open Sarah Chen's page. It should have a timeline
|
||||
entry linking back to today's conversation. Open Acme Corp's page. Same.
|
||||
|
||||
4. **Send a boring message.** Say "ok sounds good." Verify: nothing was
|
||||
created. The detector should report "No signals detected."
|
||||
|
||||
5. **Check for duplicates.** Mention "Pedro" then later "Pedro Franceschi."
|
||||
Verify: one page, not two.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,109 +0,0 @@
|
||||
# Executive Assistant Pattern
|
||||
|
||||
## Goal
|
||||
Email triage, meeting prep, and scheduling powered by brain context -- so every interaction is informed by the full history of the relationship.
|
||||
|
||||
## What the User Gets
|
||||
Without this: the agent triages email mechanically ("you have 12 unread"), preps for meetings with generic LinkedIn bios, and schedules without relationship context. With this: the agent knows who every sender is before reading their email, surfaces shared history before every meeting, and nudges scheduling based on relationship temperature and open threads.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
# WORKFLOW 1: Email Triage
|
||||
on email_batch(emails):
|
||||
for email in emails:
|
||||
# Step 1: Search sender BEFORE reading the email body
|
||||
# Brain context makes triage 10x better
|
||||
sender_page = gbrain search "{email.sender_name}"
|
||||
if sender_page:
|
||||
context = gbrain get <sender_slug>
|
||||
# Now you know: who they are, relationship history,
|
||||
# what they care about, open threads
|
||||
|
||||
# Step 2: Read the email WITH brain context loaded
|
||||
# Classification is now informed, not mechanical
|
||||
|
||||
# Step 3: Classify with context
|
||||
if context.relationship == "inner_circle" or context.has_open_threads:
|
||||
priority = "urgent"
|
||||
elif context.is_known_entity:
|
||||
priority = "normal"
|
||||
else:
|
||||
priority = "noise" # unknown sender, no brain page
|
||||
|
||||
# Step 4: Draft reply with relationship context
|
||||
if needs_reply(email):
|
||||
draft = compose_reply(
|
||||
email,
|
||||
context=context, # their brain page
|
||||
open_threads=context.open_threads, # what you're working on together
|
||||
relationship=context.relationship # tone calibration
|
||||
)
|
||||
|
||||
# WORKFLOW 2: Meeting Prep
|
||||
on upcoming_meeting(meeting):
|
||||
briefing = {}
|
||||
for attendee in meeting.attendees:
|
||||
# Search brain for each attendee
|
||||
results = gbrain search "{attendee.name}"
|
||||
if results:
|
||||
page = gbrain get <attendee_slug>
|
||||
briefing[attendee] = {
|
||||
"compiled_truth": page.compiled_truth,
|
||||
"last_interaction": page.timeline[0], # most recent
|
||||
"open_threads": page.open_threads,
|
||||
"relationship_temperature": page.relationship,
|
||||
"relevant_deals": gbrain get_links <attendee_slug>,
|
||||
}
|
||||
else:
|
||||
briefing[attendee] = "No brain page -- consider enriching"
|
||||
|
||||
# Surface: shared history, what to follow up on, what to watch for
|
||||
# "Last time you discussed the Series B timeline. Pedro was concerned
|
||||
# about burn rate. Here's the latest from his company page."
|
||||
|
||||
# WORKFLOW 3: Post-Inbox Brain Updates
|
||||
on inbox_cleared():
|
||||
for email in processed_emails:
|
||||
if email.contained_new_information:
|
||||
# Update the sender's brain page with new signal
|
||||
gbrain add_timeline_entry <sender_slug> \
|
||||
--entry "Email re: {subject}. Key info: {extracted_signal}" \
|
||||
--source "email from {sender} re {subject}, {date}"
|
||||
|
||||
# Update any mentioned entity pages too
|
||||
for entity in email.mentioned_entities:
|
||||
gbrain add_timeline_entry <entity_slug> \
|
||||
--entry "{what_was_said_about_them}" \
|
||||
--source "email from {sender}, {date}"
|
||||
|
||||
# WORKFLOW 4: Scheduling Nudges
|
||||
on schedule_request(meeting):
|
||||
for attendee in meeting.attendees:
|
||||
page = gbrain get <attendee_slug>
|
||||
if page.last_interaction > 6_weeks_ago:
|
||||
nudge("You haven't met with {attendee} in {weeks} weeks")
|
||||
if page.has_open_threads:
|
||||
nudge("{attendee} has an open thread about {topic}")
|
||||
if page.relationship_temperature == "cooling":
|
||||
nudge("Relationship with {attendee} may need attention")
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Search sender BEFORE reading the email.** This is counterintuitive but critical. Loading brain context first means you know who they are, what you're working on together, and what they care about -- before you even see the subject line. The triage is informed, not mechanical.
|
||||
2. **Unknown senders with no brain page are almost always noise.** If `gbrain search` returns nothing for a sender, they're probably not important. Classify as low priority unless the email content signals otherwise.
|
||||
3. **Meeting prep is the highest-leverage EA workflow.** The user walks into every meeting already briefed on each attendee: last interaction, open threads, relationship history. This is the difference between "you have a meeting at 3" and "you have a meeting at 3 with Pedro -- last time you discussed the Series B, he was concerned about burn rate."
|
||||
4. **Post-inbox brain updates are where the brain compounds.** Every email is signal. If you clear the inbox without updating brain pages, the information is lost. This is the step most agents skip.
|
||||
5. **Scheduling nudges require timeline data.** "You haven't met with Diana in 6 weeks" only works if meeting pages have been ingested with proper entity propagation (see meeting-ingestion guide).
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Run meeting prep for tomorrow's calendar. For each attendee, confirm the agent ran `gbrain search` and loaded their brain page before generating the briefing.
|
||||
2. Triage 5 emails. Confirm the agent searched for each sender in the brain before classifying the email.
|
||||
3. After clearing an inbox, check 2 sender brain pages with `gbrain get <slug>`. Confirm new timeline entries were added with information from the emails.
|
||||
4. Check a scheduling suggestion. Confirm the agent referenced the attendee's brain page (last interaction date, open threads) in the nudge.
|
||||
5. Send a test email from someone with a brain page. Confirm the triage response references their relationship context, not just the email content.
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,190 +0,0 @@
|
||||
# Idea Capture: Originals, Depth, and Distribution
|
||||
|
||||
## Goal
|
||||
|
||||
Capture the user's original thinking with exact phrasing, deep context, and cross-links so the originals folder becomes the highest-value content in the brain.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: brilliant ideas said in conversation disappear. The agent heard
|
||||
"the ambition-to-lifespan ratio has never been more broken" and forgot it.
|
||||
|
||||
With this: every original observation is captured verbatim, cross-linked to
|
||||
the people and ideas that shaped it, and rated for publishing potential. Your
|
||||
intellectual archive grows with every conversation.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
capture_idea(message_text, source_context):
|
||||
|
||||
// 1. AUTHORSHIP TEST — where does this idea belong?
|
||||
if user_generated_the_idea(message_text):
|
||||
destination = "brain/originals/{slug}.md"
|
||||
elif user_synthesis_of_others(message_text):
|
||||
destination = "brain/originals/{slug}.md" // synthesis IS original
|
||||
elif world_concept(message_text):
|
||||
destination = "brain/concepts/{slug}.md"
|
||||
elif product_or_business_idea(message_text):
|
||||
destination = "brain/ideas/{slug}.md"
|
||||
elif ghostwritten_by_user(message_text):
|
||||
destination = "brain/originals/{slug}.md" // note ghostwriter in metadata
|
||||
elif article_about_user(message_text):
|
||||
destination = "brain/media/writings/{slug}.md"
|
||||
|
||||
// 2. CAPTURE WITH EXACT PHRASING — never paraphrase
|
||||
page = create_or_update(destination, {
|
||||
content: message_text, // verbatim, not summarized
|
||||
source: source_context, // conversation, meeting, moment
|
||||
reasoning_path: influences, // what led to the insight
|
||||
depth_context: emotional_nuance // the WHY behind the WHAT
|
||||
})
|
||||
|
||||
// 3. ORIGINALITY RATING (for notable ideas)
|
||||
if is_notable(message_text):
|
||||
rate_originality(page, populations=[
|
||||
"general_population", "tech_industry",
|
||||
"intellectual_media", "political_establishment"
|
||||
])
|
||||
|
||||
// 4. CROSS-LINK (mandatory — an original without links is dead)
|
||||
link_to_people(page, mentioned_people)
|
||||
link_to_companies(page, mentioned_companies)
|
||||
link_to_meetings(page, source_meeting)
|
||||
link_to_media(page, influences)
|
||||
link_to_other_originals(page, related_ideas)
|
||||
link_to_concepts(page, referenced_concepts)
|
||||
|
||||
// 5. SYNC
|
||||
gbrain sync --no-pull --no-embed
|
||||
```
|
||||
|
||||
### The Authorship Test
|
||||
|
||||
| Signal | Destination |
|
||||
|--------|-------------|
|
||||
| User generated the idea | `brain/originals/{slug}.md` |
|
||||
| User's unique synthesis of others' ideas | `brain/originals/` (the synthesis is original) |
|
||||
| World concept someone else coined | `brain/concepts/{slug}.md` |
|
||||
| Product or business idea | `brain/ideas/{slug}.md` |
|
||||
| User's ghostwritten book/essay | `brain/originals/` (note ghostwriter in metadata) |
|
||||
| Article ABOUT user | `brain/media/writings/` |
|
||||
|
||||
### Capture Standards
|
||||
|
||||
**Use the user's EXACT phrasing.** The language IS the insight.
|
||||
|
||||
"The ambition-to-lifespan ratio has never been more broken" captures something that
|
||||
"tension between ambition and mortality" doesn't. Don't clean it up. Don't paraphrase.
|
||||
The vivid version is the real version.
|
||||
|
||||
**What counts as worth capturing:**
|
||||
- Original observations about how the world works
|
||||
- Novel connections between disparate things
|
||||
- Frameworks and mental models
|
||||
- Pattern recognition moments ("I keep seeing X in every Y")
|
||||
- Hot takes with reasoning behind them
|
||||
- Metaphors that reveal new angles
|
||||
- Emotional/psychological insights about self or others
|
||||
|
||||
**What does NOT count:**
|
||||
- Routine operational messages ("ok", "do it")
|
||||
- Pure questions without embedded observations
|
||||
- Echoing back something the agent said
|
||||
- Acknowledgments and reactions
|
||||
|
||||
### The Depth Test
|
||||
|
||||
**Could someone unfamiliar with the user read this page and understand not
|
||||
just WHAT they think but WHY and HOW they got there?**
|
||||
|
||||
If the answer is no, it needs more depth. Include:
|
||||
- The reasoning path (what led to the insight)
|
||||
- The influences (what they were reading/watching/experiencing)
|
||||
- The context (conversation, meeting, moment)
|
||||
- The emotional or psychological nuance
|
||||
|
||||
### Originality Distribution Rating
|
||||
|
||||
For notable ideas, rate originality 0-100 across different populations:
|
||||
|
||||
```markdown
|
||||
## Originality Distribution
|
||||
|
||||
- **General population:** 72/100 — most people haven't encountered this framework
|
||||
- **Tech industry:** 45/100 — common in startup circles but novel to most
|
||||
- **Intellectual/media class:** 68/100 — would resonate, not yet articulated
|
||||
- **Political establishment:** 82/100 — completely foreign to policy thinking
|
||||
|
||||
**Publish signal:** Strong essay candidate. Best audience: founders, builders.
|
||||
```
|
||||
|
||||
This tells the user which ideas are worth turning into essays, talks, or videos,
|
||||
and which audience would find them most novel.
|
||||
|
||||
### Deep Cross-Linking Mandate
|
||||
|
||||
**An original without cross-links is a dead original.** The connections ARE
|
||||
the intelligence.
|
||||
|
||||
Every original MUST link to:
|
||||
- **People** who shaped the thinking
|
||||
- **Companies** where the idea played out
|
||||
- **Meetings** where it was discussed
|
||||
- **Books and media** that influenced it
|
||||
- **Other originals** it connects to (ideas form clusters)
|
||||
- **Concepts** it builds on or challenges
|
||||
|
||||
### Notability Filtering
|
||||
|
||||
Before creating any entity page, check notability:
|
||||
|
||||
**Create a page for:**
|
||||
- People you know or discuss with specificity
|
||||
- Companies you're evaluating, working with, or investing in
|
||||
- Media you mention with personal reaction
|
||||
- Anyone you've explicitly engaged with
|
||||
|
||||
**Don't create pages for:**
|
||||
- Generic references or passing examples
|
||||
- Low-engagement accounts who mentioned you once
|
||||
- Pure metaphors ("like the Roman Empire...")
|
||||
- One-off encounters with no follow-up
|
||||
|
||||
**Decision:** If notable AND no page exists, create a full page with web
|
||||
search enrichment. No stubs. If you make a page, make it good.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Synthesis IS original.** When the user connects two existing ideas in a
|
||||
new way, that synthesis belongs in `brain/originals/`, not `brain/concepts/`.
|
||||
The novel combination is the insight, even if the component ideas aren't new.
|
||||
|
||||
2. **Exact phrasing is non-negotiable.** Never paraphrase, summarize, or
|
||||
"clean up" the user's language. "The ambition-to-lifespan ratio has never
|
||||
been more broken" is the insight. "Tension between ambition and mortality"
|
||||
is a corpse. Capture the first version.
|
||||
|
||||
3. **Cross-links are mandatory, not optional.** An original without links to
|
||||
the people, companies, meetings, and concepts that shaped it is a dead
|
||||
original. The connections ARE the intelligence. Check every original for
|
||||
at least 2 cross-links before considering it captured.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Generate an idea and check the page.** Say something original in
|
||||
conversation (e.g., "What if markdown files are actually distributed
|
||||
software?"). Verify that `brain/originals/{slug}.md` was created with
|
||||
your exact phrasing, not a paraphrase.
|
||||
|
||||
2. **Check cross-links exist.** Open the newly created original page. It
|
||||
should link to at least the people or concepts mentioned. Open those
|
||||
linked pages and verify they back-link to the original.
|
||||
|
||||
3. **Verify the depth test passes.** Read the captured page as if you were
|
||||
a stranger. Can you understand not just WHAT the user thinks but WHY?
|
||||
If the reasoning path and context are missing, the capture is incomplete.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,138 +0,0 @@
|
||||
# Live Sync: Keep the Index Current
|
||||
|
||||
## Goal
|
||||
|
||||
Every markdown change in the brain repo is searchable within minutes, automatically, with no manual intervention.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: you correct a hallucination in a brain page, but the vector DB
|
||||
keeps serving the old text because nobody ran `gbrain sync`. Stale search
|
||||
results erode trust. The brain becomes unreliable.
|
||||
|
||||
With this: edits show up in search within minutes. The vector DB stays current
|
||||
with the brain repo automatically. You never have to remember to run sync.
|
||||
|
||||
## Implementation
|
||||
|
||||
### Prerequisite: Session Mode Pooler
|
||||
|
||||
Sync uses `engine.transaction()` on every import. If `DATABASE_URL` points to
|
||||
Supabase's **Transaction mode** pooler, sync will throw `.begin() is not a
|
||||
function` and **silently skip most pages**. This is the number one cause of
|
||||
"sync ran but nothing happened."
|
||||
|
||||
Fix: use the **Session mode** pooler string (port 6543, Session mode) or the
|
||||
direct connection (port 5432, IPv6-only). Verify by running `gbrain sync` and
|
||||
checking that the page count in `gbrain stats` matches the syncable file count
|
||||
in the repo.
|
||||
|
||||
### The Primitives
|
||||
|
||||
Always chain sync + embed:
|
||||
|
||||
```bash
|
||||
gbrain sync --repo /path/to/brain && gbrain embed --stale
|
||||
```
|
||||
|
||||
- `gbrain sync --repo <path>` -- one-shot incremental sync. Detects changes via
|
||||
`git diff`, imports only what changed. For small changesets (<= 100 files),
|
||||
embeddings are generated inline during import.
|
||||
- `gbrain embed --stale` -- backfill embeddings for any chunks that don't have
|
||||
them. Safety net for large syncs (>100 files) or prior `--no-embed` runs.
|
||||
- `gbrain sync --watch --repo <path>` -- foreground polling loop, every 60s
|
||||
(configurable with `--interval N`). Embeds inline for small changesets. Exits
|
||||
after 5 consecutive failures, so run under a process manager or pair with a
|
||||
cron fallback.
|
||||
|
||||
### Approach 1: Cron Job (recommended)
|
||||
|
||||
Run every 5-30 minutes. Works with any cron scheduler.
|
||||
|
||||
```bash
|
||||
gbrain sync --repo /data/brain && gbrain embed --stale
|
||||
```
|
||||
|
||||
**OpenClaw:**
|
||||
```
|
||||
Name: gbrain-auto-sync
|
||||
Schedule: */15 * * * *
|
||||
Prompt: "Run: gbrain sync --repo /data/brain && gbrain embed --stale
|
||||
Log the result. If sync fails with .begin() is not a function,
|
||||
the DATABASE_URL is using Transaction mode pooler."
|
||||
```
|
||||
|
||||
**Hermes:**
|
||||
```
|
||||
/cron add "*/15 * * * *" "Run gbrain sync --repo /data/brain &&
|
||||
gbrain embed --stale. Log the result." --name "gbrain-auto-sync"
|
||||
```
|
||||
|
||||
### Approach 2: Long-Lived Watcher
|
||||
|
||||
For near-instant sync (60s polling). Run under a process manager that
|
||||
auto-restarts on exit. Pair with a cron fallback since `--watch` exits
|
||||
on repeated failures.
|
||||
|
||||
```bash
|
||||
gbrain sync --watch --repo /data/brain
|
||||
```
|
||||
|
||||
### Approach 3: Git Hook / Webhook
|
||||
|
||||
Triggers sync on push events for instant sync (<5s).
|
||||
|
||||
- **GitHub webhook:** Set up the webhook to call
|
||||
`gbrain sync --repo /data/brain && gbrain embed --stale`.
|
||||
Verify `X-Hub-Signature-256` against a shared secret.
|
||||
- **Git post-receive hook:** If the brain repo is on the same machine.
|
||||
|
||||
### What Gets Synced
|
||||
|
||||
Sync only indexes "syncable" markdown files. These are excluded by design:
|
||||
- Hidden paths (`.git/`, `.raw/`, etc.)
|
||||
- The `ops/` directory
|
||||
- Meta files: `README.md`, `index.md`, `schema.md`, `log.md`
|
||||
|
||||
### Sync is Idempotent
|
||||
|
||||
Concurrent runs are safe. Two syncs on the same commit no-op because content
|
||||
hashes match. If both a cron and `--watch` fire simultaneously, no conflict.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Always chain sync + embed.** Running `gbrain sync` without
|
||||
`gbrain embed --stale` leaves new chunks without embeddings. They exist
|
||||
in the database but are invisible to vector search. Always run both
|
||||
commands together. The `&&` ensures embed only runs if sync succeeds.
|
||||
|
||||
2. **--watch polls, it doesn't stream.** The `--watch` flag polls every 60s
|
||||
(configurable). It is not a filesystem watcher or git hook. It exits after
|
||||
5 consecutive failures, so it needs a process manager (systemd, pm2) or a
|
||||
cron fallback to stay alive. Don't assume it runs forever.
|
||||
|
||||
3. **Webhook needs the server running.** If you use a GitHub webhook for
|
||||
instant sync, the receiving server must be running and reachable. If the
|
||||
server is down when a push happens, that sync is missed. Pair webhooks
|
||||
with a cron fallback that catches anything the webhook missed.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Edit a file and search for the change.** Edit a brain markdown file,
|
||||
commit, and push. Wait for the next sync cycle (cron interval or `--watch`
|
||||
poll). Run `gbrain search "<text from the edit>"`. The updated content
|
||||
should appear in results. If it returns old content, sync failed.
|
||||
|
||||
2. **Compare page count to file count.** Run `gbrain stats` and count the
|
||||
syncable markdown files in the brain repo. The page count in the database
|
||||
should match. If they diverge, files are being silently skipped (likely
|
||||
a Transaction mode pooler issue).
|
||||
|
||||
3. **Check embedded chunk count.** In `gbrain stats`, the embedded chunk
|
||||
count should be close to the total chunk count. A large gap means
|
||||
`gbrain embed --stale` isn't running after sync, leaving chunks invisible
|
||||
to vector search.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,80 +0,0 @@
|
||||
# Meeting Ingestion
|
||||
|
||||
## Goal
|
||||
Meeting transcripts become brain pages that update every mentioned entity -- attendees, companies, deals, and action items all propagated in one pass.
|
||||
|
||||
## What the User Gets
|
||||
Without this: meetings vanish into memory, action items are forgotten, and the agent has no idea what was discussed last time you met someone. With this: every meeting is a permanent record that enriches every person and company page it touches, and the user walks into every follow-up already briefed.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
on new_meeting_transcript(meeting):
|
||||
# Step 1: Pull the COMPLETE transcript -- NOT the AI summary
|
||||
# AI summaries hallucinate framing ("it was agreed that...")
|
||||
# The transcript is ground truth
|
||||
transcript = fetch_full_transcript(meeting.id) # e.g., Circleback API
|
||||
# Must have speaker diarization: WHO said WHAT
|
||||
|
||||
# Step 2: Create the meeting page
|
||||
slug = f"meetings/{meeting.date}-{short_description}"
|
||||
compiled_truth = agent_analysis(transcript):
|
||||
# Above the bar: agent's OWN analysis, not a generic recap
|
||||
# - Reframe through the user's priorities
|
||||
# - Flag surprises, contradictions, implications
|
||||
# - Name real decisions (not performative ones)
|
||||
# - Call out what was left unsaid or unresolved
|
||||
timeline = format_diarized_transcript(transcript)
|
||||
# Below the bar: full transcript, append-only
|
||||
# Format: **Speaker** (HH:MM:SS): Words.
|
||||
|
||||
gbrain put <slug> --content "<compiled_truth>\n---\n<timeline>"
|
||||
|
||||
# Step 3: Propagate to ALL entity pages (MANDATORY -- most agents skip this)
|
||||
for person in meeting.attendees + meeting.mentioned_people:
|
||||
gbrain add_timeline_entry <person_slug> \
|
||||
--entry "Met in '{meeting.title}' on {date}. Key points: ..." \
|
||||
--source "Meeting notes '{meeting.title}', {date}"
|
||||
# Update their State section if new information surfaced
|
||||
# Update company pages for each person's company if relevant
|
||||
|
||||
for company in meeting.mentioned_companies:
|
||||
gbrain add_timeline_entry <company_slug> \
|
||||
--entry "Discussed in '{meeting.title}': {what_was_said}" \
|
||||
--source "Meeting notes '{meeting.title}', {date}"
|
||||
|
||||
# Step 4: Extract action items
|
||||
action_items = extract_action_items(transcript)
|
||||
# Add to task list with owner attribution
|
||||
|
||||
# Step 5: Back-link everything (bidirectional graph)
|
||||
for entity in all_entities_mentioned:
|
||||
gbrain add_link <slug> <entity_slug> # meeting -> entity
|
||||
gbrain add_link <entity_slug> <slug> # entity -> meeting
|
||||
|
||||
# Step 6: Sync so new pages are immediately searchable
|
||||
gbrain sync
|
||||
|
||||
# Schedule: cron 3x/day (10 AM, 4 PM, 9 PM) to catch new meetings
|
||||
# Source: Circleback (https://circleback.ai) or any service with
|
||||
# speaker diarization + API/webhook access
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Always pull the COMPLETE transcript, never the AI summary.** AI summaries hallucinate framing -- they editorialize what was "agreed" or "decided" when no such agreement happened. The diarized transcript is ground truth.
|
||||
2. **Entity propagation is the step most agents skip.** A meeting is NOT fully ingested until every attendee's page, every mentioned person's page, and every company's page has a new timeline entry. The meeting page alone is useless without propagation.
|
||||
3. **Mentioned people are not just attendees.** If the meeting discussed "Sarah's team at Brex," then Sarah's page AND Brex's page need updates -- even though Sarah wasn't in the room.
|
||||
4. **The agent's analysis is the value, not a summary.** "They discussed Q2 targets" is worthless. "Pedro pushed back on the burn rate, Diana didn't commit to the timeline, and nobody addressed the pricing gap" is useful.
|
||||
5. **Back-links must be bidirectional.** The meeting page links to attendee pages AND attendee pages link back to the meeting. The graph is bidirectional. Always.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. After ingesting a meeting, run `gbrain get meetings/{date}-{slug}`. Confirm the page has the agent's analysis above the bar and the full diarized transcript below it.
|
||||
2. For each attendee, run `gbrain get <attendee_slug>`. Check that their timeline has a new entry referencing the meeting with specific insights (not just "attended meeting").
|
||||
3. Pick a company mentioned in the meeting. Run `gbrain get <company_slug>`. Confirm a timeline entry exists referencing what was discussed about the company.
|
||||
4. Run `gbrain get_links meetings/{date}-{slug}`. Verify back-links exist to all attendee and entity pages.
|
||||
5. Run `gbrain search "{meeting_topic}"`. Confirm the meeting page appears in search results (verifies sync ran).
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,159 +0,0 @@
|
||||
# Minions fix — repairing a half-migrated install
|
||||
|
||||
**tl;dr:** on v0.11.1+ everything should self-heal. If Minions is partially
|
||||
set up (no `~/.gbrain/preferences.json`, autopilot still inline, cron jobs
|
||||
still on `agentTurn`), run:
|
||||
|
||||
```bash
|
||||
gbrain apply-migrations --yes
|
||||
```
|
||||
|
||||
It's idempotent. On v0.11.1 installs that already migrated it's a cheap
|
||||
no-op.
|
||||
|
||||
## Context
|
||||
|
||||
v0.11.0 shipped the Minions schema, queue, worker, and migration skill —
|
||||
but the migration skill itself never fired on upgrade. `runPostUpgrade`
|
||||
printed the feature pitch and stopped. v0.11.0 was never released
|
||||
publicly; v0.11.1 is the first public Minions ship and fixes the
|
||||
mega-bug (migration fires automatically on `gbrain upgrade` and via
|
||||
the `postinstall` hook).
|
||||
|
||||
If you're on a pre-v0.11.1 branch build (e.g. running the
|
||||
`minions-jobs` branch before v0.11.1 tagged), Minions may be installed
|
||||
but not wired: schema is v7, but no `~/.gbrain/preferences.json`,
|
||||
autopilot still runs inline, cron jobs still call `agentTurn`.
|
||||
|
||||
This guide covers both paths: the canonical v0.11.1+ fix, and the
|
||||
stopgap for pre-v0.11.1 binaries that don't have `apply-migrations`.
|
||||
|
||||
## Detecting the half-migrated state
|
||||
|
||||
```bash
|
||||
gbrain doctor
|
||||
```
|
||||
|
||||
If the install is half-migrated, you'll see:
|
||||
|
||||
```
|
||||
[FAIL] minions_migration: MINIONS HALF-INSTALLED (partial migration: 0.11.0). Run: gbrain apply-migrations --yes
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
[FAIL] minions_config: MINIONS HALF-INSTALLED (schema v7+ but no ~/.gbrain/preferences.json). Run: gbrain apply-migrations --yes
|
||||
```
|
||||
|
||||
For a machine-readable report (cron-friendly):
|
||||
|
||||
```bash
|
||||
gbrain skillpack-check --quiet && echo healthy || echo needs_action
|
||||
gbrain skillpack-check | jq -r '.actions[]' # prints the exact commands to run
|
||||
```
|
||||
|
||||
## The fix (v0.11.1 or later)
|
||||
|
||||
```bash
|
||||
gbrain apply-migrations --yes
|
||||
```
|
||||
|
||||
Reads `~/.gbrain/migrations/completed.jsonl`, diffs against the TS
|
||||
migration registry, runs whatever's pending. Seven phases:
|
||||
|
||||
```
|
||||
A. Schema gbrain init --migrate-only
|
||||
B. Smoke gbrain jobs smoke
|
||||
C. Mode prompt (or --yes default pain_triggered)
|
||||
D. Prefs write ~/.gbrain/preferences.json
|
||||
E. Host AGENTS.md marker injection + cron rewrites for gbrain
|
||||
builtins; JSONL TODOs for host-specific handlers
|
||||
F. Install gbrain autopilot --install (env-aware)
|
||||
G. Record append completed.jsonl status:"complete"
|
||||
```
|
||||
|
||||
If Phase E emits TODOs for host-specific handlers (e.g. Wintermute's
|
||||
~29 non-gbrain crons), the migration finishes with `status: "partial"`.
|
||||
Your host agent walks the TODOs using `skills/migrations/v0.11.0.md` +
|
||||
`docs/guides/plugin-handlers.md`, ships handler registrations in the
|
||||
host repo, then re-runs `gbrain apply-migrations --yes`. Newly
|
||||
registerable cron entries get rewritten and the JSONL rows mark
|
||||
`status: "complete"`.
|
||||
|
||||
## The stopgap (pre-v0.11.1 binary, no apply-migrations yet)
|
||||
|
||||
If you're stuck on a branch build that doesn't have `apply-migrations`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/garrytan/gbrain/v0.11.1/scripts/fix-v0.11.0.sh | bash
|
||||
```
|
||||
|
||||
This bash script does what apply-migrations does from a shell environment:
|
||||
|
||||
1. `gbrain init --migrate-only` — schema v7.
|
||||
2. `gbrain jobs smoke` — verify Minions health.
|
||||
3. Prompt for `minion_mode` (defaults `pain_triggered` on non-TTY).
|
||||
4. Write `~/.gbrain/preferences.json` atomically.
|
||||
5. Append `~/.gbrain/migrations/completed.jsonl` with `status: "partial"`
|
||||
and `apply_migrations_pending: true`. That partial record is the
|
||||
signal to v0.11.1's `apply-migrations` to pick up remaining phases
|
||||
after the user upgrades.
|
||||
6. Detect host agent repos and PRINT rewrite instructions (never
|
||||
auto-edits from a curl-piped script).
|
||||
7. Print the next step: `Run: gbrain autopilot --install`.
|
||||
|
||||
Once v0.11.1 is installed, re-run `gbrain apply-migrations --yes` to
|
||||
finish the remaining phases (host rewrites + autopilot install). The
|
||||
stopgap's `status: "partial"` record is designed to resume cleanly
|
||||
(it doesn't poison the permanent migration path).
|
||||
|
||||
## Verify the fix landed
|
||||
|
||||
```bash
|
||||
# 1. Preferences exist and are readable
|
||||
cat ~/.gbrain/preferences.json
|
||||
|
||||
# 2. Migration recorded
|
||||
cat ~/.gbrain/migrations/completed.jsonl
|
||||
|
||||
# 3. Autopilot is supervising a Minions worker child
|
||||
gbrain autopilot --status
|
||||
ps aux | grep 'jobs work'
|
||||
|
||||
# 4. Jobs show up in the queue
|
||||
gbrain jobs list
|
||||
|
||||
# 5. Any host-specific TODOs still pending
|
||||
cat ~/.gbrain/migrations/pending-host-work.jsonl 2>/dev/null || echo "(none — all host work is done)"
|
||||
|
||||
# 6. Doctor + skillpack-check should both be clean
|
||||
gbrain doctor
|
||||
gbrain skillpack-check --quiet && echo ok
|
||||
```
|
||||
|
||||
## If the fix fails
|
||||
|
||||
Each phase is idempotent. Re-running is safe. Common failure modes:
|
||||
|
||||
- **Phase B smoke fails:** the schema didn't apply. Check
|
||||
`~/.gbrain/config.json` has a valid `database_url` (or `database_path`
|
||||
for PGLite). Run `gbrain init --migrate-only` directly and look at
|
||||
the error.
|
||||
- **Phase F install fails:** your host environment doesn't match any
|
||||
detected target. Pass `--target <macos|linux-systemd|ephemeral-container|linux-cron>`
|
||||
explicitly.
|
||||
- **Pending host work never clears:** your host agent hasn't shipped
|
||||
handler registrations yet. Read
|
||||
`~/.gbrain/migrations/pending-host-work.jsonl`, open
|
||||
`skills/migrations/v0.11.0.md`, and follow the host-agent instruction
|
||||
manual.
|
||||
|
||||
## Related
|
||||
|
||||
- `skills/migrations/v0.11.0.md` — full migration skill for host agents.
|
||||
- `skills/skillpack-check/SKILL.md` — when and how to run the health check.
|
||||
- `docs/guides/plugin-handlers.md` — plugin contract for host-specific
|
||||
handlers.
|
||||
- `skills/conventions/cron-via-minions.md` — the canonical cron rewrite
|
||||
pattern.
|
||||
@@ -1,167 +0,0 @@
|
||||
# Minions shell jobs — move deterministic crons off the gateway
|
||||
|
||||
## 30 seconds
|
||||
|
||||
```bash
|
||||
# Run your first shell job:
|
||||
GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs submit shell \
|
||||
--params '{"cmd":"echo hello","cwd":"/tmp"}' --follow
|
||||
# → exit_code: 0, stdout_tail: "hello\n", duration_ms: 43
|
||||
```
|
||||
|
||||
That's it. Your cron scripts now have a home with retry, backoff, DLQ, and
|
||||
`gbrain jobs list` visibility, without each one booting a full LLM session.
|
||||
|
||||
**PGLite users:** `gbrain jobs work` does not run on PGLite (exclusive file
|
||||
lock). Every crontab invocation must use `--follow` for inline execution.
|
||||
Postgres users can run a persistent worker; see recipes below.
|
||||
|
||||
---
|
||||
|
||||
## Why it exists
|
||||
|
||||
If your agent runs deterministic scripts from cron (token refresh, API fetch,
|
||||
scrape + write), each one pays the cost of a full LLM session on the gateway.
|
||||
Fourteen simultaneous fires on a Series A deployment pin CPU at 100% and block
|
||||
live messages. None of those scripts need reasoning. They need a shell.
|
||||
|
||||
Shell jobs move them to the Minions worker: one deterministic-script execution
|
||||
per cron, zero LLM tokens, unified visibility and retry.
|
||||
|
||||
---
|
||||
|
||||
## Security model (read this)
|
||||
|
||||
Shell exec is a large blast radius. We ship two independent gates, both must
|
||||
pass:
|
||||
|
||||
1. **MCP boundary.** `submit_job` with `name: 'shell'` is rejected when
|
||||
`ctx.remote === true` (MCP callers). Independent of the env flag. Remote
|
||||
agents can never submit shell jobs. `MinionQueue.add('shell', ...)` has its
|
||||
own guard too, so an in-process handler can't programmatically bypass this.
|
||||
2. **Env flag.** The worker only registers the shell handler when
|
||||
`GBRAIN_ALLOW_SHELL_JOBS=1` is set on the worker process. Default: off. Your
|
||||
agent opts in per-host.
|
||||
|
||||
**What the env allowlist does AND does not do.** Shell jobs run with a minimal
|
||||
env: `PATH, HOME, USER, LANG, TZ, NODE_ENV`. Your secrets like `OPENAI_API_KEY`
|
||||
and `DATABASE_URL` are NOT passed to the child. You opt-in additional keys per
|
||||
job via `env: { ... }`. This stops accidental `$OPENAI_API_KEY` interpolation in
|
||||
a user-authored script. It does **not** sandbox filesystem reads: a shell
|
||||
script can `cat ~/.env` or any file the worker process can read. The operator
|
||||
picks a safe `cwd`. That is the trust boundary.
|
||||
|
||||
**Audit trail, not forensic insurance.** Every submission writes a JSONL line
|
||||
to `~/.gbrain/audit/shell-jobs-YYYY-Www.jsonl` (ISO-week rotation; override
|
||||
with `GBRAIN_AUDIT_DIR`). Failures log to stderr and don't block submission, so
|
||||
a disk-full adversary could silently disable the trail. Good for "what did
|
||||
this cron submit last Tuesday", not for security-critical forensics.
|
||||
|
||||
**The command text is logged as-is.** If you embed a secret in `cmd`
|
||||
(`curl -H 'Authorization: Bearer ...'`), it shows up in the audit file. Put
|
||||
secrets in `env:` instead.
|
||||
|
||||
---
|
||||
|
||||
## Migrate a cron
|
||||
|
||||
### Postgres worker (recommended)
|
||||
|
||||
On one terminal, start a persistent worker:
|
||||
|
||||
```bash
|
||||
GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work
|
||||
```
|
||||
|
||||
Rewrite crontab to submit shell jobs (no `--follow`):
|
||||
|
||||
```cron
|
||||
# Before (LLM gateway):
|
||||
# OpenClaw cron: x-garrytan-unified
|
||||
# After (Minions worker):
|
||||
3 13,16,19,22,1,4,7,10 * * * \
|
||||
gbrain jobs submit shell \
|
||||
--params '{"cmd":"node scripts/x-garrytan-daily.mjs","cwd":"/data/.openclaw/workspace"}' \
|
||||
--max-attempts 3 --timeout-ms 300000
|
||||
```
|
||||
|
||||
Worker claims the job on next poll, runs it, records `exit_code` +
|
||||
`stdout_tail` + `stderr_tail` in the result. Failures retry per
|
||||
`--max-attempts` with exponential backoff.
|
||||
|
||||
### PGLite (inline execution)
|
||||
|
||||
PGLite doesn't support the persistent worker daemon. Every crontab invocation
|
||||
uses `--follow` to run inline:
|
||||
|
||||
```cron
|
||||
# Each cron tick spawns a short-lived worker that runs the job inline.
|
||||
3 13,16,19,22,1,4,7,10 * * * \
|
||||
GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs submit shell \
|
||||
--params '{"cmd":"node scripts/x-garrytan-daily.mjs","cwd":"/data/.openclaw/workspace"}' \
|
||||
--follow --timeout-ms 300000
|
||||
```
|
||||
|
||||
Note: `--follow` blocks the crontab slot until the job finishes. If 14 shell
|
||||
crons land at the same minute and each takes 30s, they serialize through
|
||||
crontab's spawning limits. Postgres + persistent worker scales better.
|
||||
|
||||
### Submitting with `argv` (no shell interpolation)
|
||||
|
||||
For programmatic callers assembling commands from JSON, use `argv` instead of
|
||||
`cmd`. No shell, no injection surface:
|
||||
|
||||
```bash
|
||||
gbrain jobs submit shell \
|
||||
--params '{"argv":["node","scripts/fetch.mjs","--date","2026-04-19"],"cwd":"/data"}' \
|
||||
--follow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debug a failed job
|
||||
|
||||
```bash
|
||||
# List dead shell jobs
|
||||
gbrain jobs list --status dead
|
||||
|
||||
# Inspect one
|
||||
gbrain jobs get 42
|
||||
# → error_text, stacktrace, result.stdout_tail, result.stderr_tail
|
||||
|
||||
# Submission audit log (operator trail, not forensic)
|
||||
cat ~/.gbrain/audit/shell-jobs-*.jsonl | jq '.'
|
||||
|
||||
# First-time failure mode: submitted without env flag on the worker
|
||||
gbrain jobs list --status waiting --name shell
|
||||
# If rows pile up here, no worker with GBRAIN_ALLOW_SHELL_JOBS=1 is running.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Filesystem reads are not sandboxed.** See "Security model" above. Don't
|
||||
point `cwd` at a directory full of secrets.
|
||||
- **Audit log is advisory.** Disk-full or EACCES silently disables it.
|
||||
- **Cancel latency is lock-renewal-bounded** (~7-15 s by default). A cancelled
|
||||
child keeps running until the next lock-renewal tick fails.
|
||||
- **`--follow` claim order** is by priority/created_at. If another job is
|
||||
waiting in the same queue at the time of `--follow`, that one runs first.
|
||||
- **`cwd` symlink TOCTOU.** The absolute-path check doesn't guard against
|
||||
symlinks pointing elsewhere at execution time. Operator-scope concern.
|
||||
|
||||
---
|
||||
|
||||
## Errors {#errors}
|
||||
|
||||
| Error | What it means | Fix |
|
||||
|---|---|---|
|
||||
| `shell: specify exactly one of cmd or argv` | `cmd` and `argv` are mutually exclusive. Both absent is also invalid. | Choose one. `cmd` for shell-interpolated strings; `argv` for structured args. |
|
||||
| `shell: cwd is required and must be an absolute path` | `cwd` must be a string starting with `/`. | Set `cwd` in `--params` to an absolute path. |
|
||||
| `shell: argv must be an array of strings` | `argv` has a non-string entry or isn't an array. | Pass `argv: ["bin","arg1","arg2"]`. |
|
||||
| `shell: env values must all be strings` | `env` has a number/bool/object value. | Stringify: `"env":{"COUNT":"3"}` not `"env":{"COUNT":3}`. |
|
||||
| `permission_denied: shell jobs cannot be submitted over MCP` | An MCP client tried to submit a shell job. By design CLI-only. | Submit from CLI or via a trusted operation handler (`ctx.remote === false`). |
|
||||
| `protected job name 'shell' requires CLI or operation-local submitter` | A caller invoked `MinionQueue.add('shell', ...)` without the `trusted` opt-in. | Pass `{ allowProtectedSubmit: true }` as the 4th arg. CLI and `submit_job` do this automatically. |
|
||||
| `aborted: timeout` / `aborted: cancel` / `aborted: shutdown` / `aborted: lock-lost` | The worker's abort signal fired mid-execution. Child got SIGTERM, 5s grace, then SIGKILL. | Expected: timeout / user cancel / deploy restart / stall. Inspect `gbrain jobs get` to see which. |
|
||||
| `exit N: <stderr_tail_500>` | Script exited non-zero. | Read `stderr_tail` in `gbrain jobs get`. |
|
||||
@@ -1,120 +0,0 @@
|
||||
# Operational Disciplines
|
||||
|
||||
## Goal
|
||||
Five non-negotiable rules that separate a production brain from a demo -- signal detection, brain-first lookup, sync after every write, daily heartbeat, and nightly dream cycle.
|
||||
|
||||
## What the User Gets
|
||||
Without this: the agent misses signals in conversation, wastes money on external APIs when the brain already has the answer, leaves search results stale after writes, and lets the brain rot quietly. With this: every message is scanned for entities, the brain is always consulted first, search is always current, health is monitored daily, and the brain compounds overnight.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
# DISCIPLINE 1: Signal Detection on Every Message (MANDATORY)
|
||||
on every_inbound_message(message):
|
||||
# No exceptions. If the user thinks out loud and the brain doesn't
|
||||
# capture it, the system is broken. This is the #1 discipline.
|
||||
|
||||
entities = detect_entities(message)
|
||||
# people, companies, deals, original ideas
|
||||
|
||||
for entity in entities:
|
||||
existing = gbrain search "{entity.name}"
|
||||
if existing:
|
||||
gbrain add_timeline_entry <entity_slug> \
|
||||
--entry "{what_was_said}" \
|
||||
--source "User, direct message, {timestamp}"
|
||||
# else: flag for enrichment if important enough
|
||||
|
||||
originals = detect_original_thinking(message)
|
||||
for idea in originals:
|
||||
gbrain put originals/{slug} --content "{user's exact phrasing}"
|
||||
|
||||
# DISCIPLINE 2: Brain-First Lookup Before External APIs (MANDATORY)
|
||||
on information_needed(topic):
|
||||
# ALWAYS check the brain before reaching for the web
|
||||
brain_result = gbrain search "{topic}"
|
||||
if brain_result:
|
||||
page = gbrain get <slug>
|
||||
# Use brain data first. External APIs FILL GAPS, not replace.
|
||||
else:
|
||||
# Brain has nothing -- now use external APIs
|
||||
external_result = brave_search("{topic}")
|
||||
|
||||
# An agent that reaches for the web before checking its own brain
|
||||
# is wasting money and giving worse answers.
|
||||
|
||||
# DISCIPLINE 3: Sync After Every Write (MANDATORY)
|
||||
on brain_write_complete():
|
||||
gbrain sync
|
||||
# Without this, search results are stale.
|
||||
# The page you just wrote won't appear in gbrain search or gbrain query
|
||||
# until sync runs. Skipping this means the next lookup misses the
|
||||
# most recent data.
|
||||
|
||||
# DISCIPLINE 4: Daily Heartbeat Check
|
||||
on daily_schedule("09:00"):
|
||||
gbrain doctor
|
||||
# Checks: database connectivity, embedding health, sync status,
|
||||
# page count, stale pages, broken links
|
||||
# If doctor reports issues, fix them before doing anything else.
|
||||
|
||||
# DISCIPLINE 5: Nightly Dream Cycle
|
||||
on nightly_schedule("02:00"):
|
||||
# The dream cycle is the most important discipline.
|
||||
# The brain COMPOUNDS overnight.
|
||||
|
||||
# 5a: Entity sweep -- find unlinked mentions
|
||||
pages = gbrain list_pages
|
||||
for page in pages:
|
||||
mentions = extract_entity_mentions(page.content)
|
||||
existing_links = gbrain get_links <page.slug>
|
||||
for mention in mentions:
|
||||
if mention not in existing_links:
|
||||
gbrain add_link <page.slug> <mention_slug> # fix broken graph
|
||||
|
||||
# 5b: Citation audit -- find facts without sources
|
||||
for page in pages:
|
||||
facts_without_sources = audit_citations(page.content)
|
||||
if facts_without_sources:
|
||||
flag_for_remediation(page, facts_without_sources)
|
||||
|
||||
# 5c: Memory consolidation -- update compiled truth from timeline
|
||||
for page in stale_pages(older_than="7d"):
|
||||
timeline = gbrain get_timeline <page.slug>
|
||||
if timeline.has_new_entries_since_last_consolidation:
|
||||
# Re-synthesize compiled truth from accumulated timeline
|
||||
updated_truth = consolidate(page.compiled_truth, timeline.new_entries)
|
||||
gbrain put <page.slug> --content updated_truth
|
||||
|
||||
# 5d: Sync everything
|
||||
gbrain sync
|
||||
|
||||
# BONUS: Durable Skills Over One-Off Work
|
||||
# If you do something twice, make it a skill + cron.
|
||||
# 1. Concept the process
|
||||
# 2. Run it manually for 3-10 items
|
||||
# 3. Revise -- iterate on quality
|
||||
# 4. Codify into a skill
|
||||
# 5. Add to cron -- automate it
|
||||
# Each entity type and signal source has exactly one owner skill.
|
||||
# Two skills creating the same page = coverage violation.
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **The dream cycle is the most important discipline.** Brains compound overnight. Entity sweeps fix broken graphs, citation audits catch sourceless facts, and memory consolidation keeps compiled truth current. Skip the dream cycle and the brain slowly rots.
|
||||
2. **Skipping Discipline 3 (sync after write) means stale search results.** You write a page, then immediately search for it -- and get nothing back. The page exists but isn't indexed. Always sync after writes.
|
||||
3. **Signal detection must fire on EVERY message.** Not just messages that look important. The user says "I talked to Pedro yesterday about the board seat" in passing -- that's a timeline entry on Pedro's page, a potential update to his State section, and a signal about the board. If the agent doesn't catch it, the system is broken.
|
||||
4. **Brain-first saves money AND gives better answers.** The brain has context that external APIs don't: relationship history, meeting notes, the user's own assessment. An API lookup for "Pedro Franceschi" returns a LinkedIn profile. The brain returns the full picture including private context.
|
||||
5. **`gbrain doctor` catches silent failures.** Embedding pipelines can stall, sync can fail silently, database connections can drop. The daily heartbeat catches these before they compound into data loss.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Send a message mentioning a person with a brain page. Confirm the agent detects the entity and adds a timeline entry to their page (`gbrain get_timeline <slug>`).
|
||||
2. Ask the agent about someone in the brain. Confirm it runs `gbrain search` or `gbrain get` BEFORE reaching for external APIs (check the tool call order).
|
||||
3. Write a new page with `gbrain put`, then immediately run `gbrain search` for it. Confirm it appears in results (verifies sync ran).
|
||||
4. Run `gbrain doctor`. Confirm it returns a health report with database status, page count, and any flagged issues.
|
||||
5. After a dream cycle runs, check a page that had unlinked entity mentions. Confirm new links were added (`gbrain get_links <slug>`).
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,87 +0,0 @@
|
||||
# The Originals Folder
|
||||
|
||||
## Goal
|
||||
Capture the user's original thinking with their exact phrasing, deep cross-links, and full provenance -- so intellectual capital compounds instead of evaporating.
|
||||
|
||||
## What the User Gets
|
||||
Without this: the user generates a brilliant framework in conversation and it vanishes when the session ends. Six months later, they vaguely remember the idea but can't find it, can't recall the exact phrasing, and can't trace what influenced it. With this: every original observation, thesis, framework, and hot take is captured verbatim in `brain/originals/`, cross-linked to the people, companies, and media that shaped it, and searchable forever.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
on user_message(message):
|
||||
# Detect original thinking in every message
|
||||
if contains_original_thinking(message):
|
||||
# The authorship test:
|
||||
# User generated the idea? -> originals/{slug}.md
|
||||
# User's unique synthesis of someone else's? -> originals/ (synthesis IS original)
|
||||
# World concept someone else coined? -> concepts/{slug}.md
|
||||
# Product or business idea? -> ideas/{slug}.md
|
||||
|
||||
# Step 1: Use the user's EXACT phrasing for the slug
|
||||
# "meatsuit-maintenance-tax"
|
||||
# NOT "biological-needs-maintenance-overhead"
|
||||
# The vividness IS the concept.
|
||||
slug = slugify(user_exact_phrase)
|
||||
|
||||
# Step 2: Create the originals page
|
||||
gbrain put originals/{slug} --content """
|
||||
# {User's Exact Phrase}
|
||||
|
||||
## The Idea
|
||||
{User's original thinking, captured in their own words.
|
||||
Do NOT paraphrase. Do NOT clean up the language.
|
||||
The raw phrasing is the intellectual artifact.}
|
||||
|
||||
## Context
|
||||
{What triggered this thinking. Meeting? Article? Conversation?
|
||||
Include the source that sparked it.}
|
||||
[Source: User, {context}, {date} {time} {tz}]
|
||||
|
||||
## Connections
|
||||
- Related to: [[{person_slug}]] -- {how they connect}
|
||||
- Emerged from: [[{meeting_slug}]] -- {what was discussed}
|
||||
- Influenced by: [[{book_or_media_slug}]] -- {what resonated}
|
||||
- Builds on: [[{other_original_slug}]] -- {how ideas cluster}
|
||||
"""
|
||||
|
||||
# Step 3: Cross-link to everything that shaped the thinking
|
||||
for entity in idea.influences:
|
||||
gbrain add_link originals/{slug} <entity_slug>
|
||||
gbrain add_link <entity_slug> originals/{slug}
|
||||
|
||||
# Step 4: Sync
|
||||
gbrain sync
|
||||
|
||||
# What counts as original thinking:
|
||||
# - Novel frameworks ("the meatsuit maintenance tax")
|
||||
# - Hot takes on someone else's work (synthesis IS original)
|
||||
# - Pattern recognition across multiple entities
|
||||
# - Predictions or bets about the future
|
||||
# - Contrarian positions with reasoning
|
||||
|
||||
# What does NOT go in originals/:
|
||||
# - Facts about the world (-> entity pages)
|
||||
# - Concepts someone else coined (-> concepts/)
|
||||
# - Product ideas (-> ideas/)
|
||||
# - Preferences (-> agent memory)
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Naming: the vividness IS the concept.** `meatsuit-maintenance-tax` not `biological-needs-maintenance-overhead`. `ambition-debt` not `deferred-career-risk-accumulation`. The user's colorful phrasing is the intellectual artifact. Never sanitize it into corporate-speak.
|
||||
2. **Synthesis IS original.** The user's take on Peter Thiel's zero-to-one framework goes in `originals/`, not `concepts/`. The original part is the user's synthesis, interpretation, or disagreement -- even though the underlying ideas came from someone else.
|
||||
3. **An original without cross-links is a dead original.** The connections ARE the intelligence. An idea about "ambition debt" that doesn't link to the people who exemplify it, the meeting where it was discussed, and the book that influenced it is just a note in a graveyard. Cross-link aggressively.
|
||||
4. **Originals form clusters.** Over time, the user's ideas connect to each other. "Meatsuit maintenance tax" connects to "ambition debt" connects to "founder energy budget." Link originals to other originals. The cluster IS the user's worldview.
|
||||
5. **Capture the trigger context.** What conversation, meeting, article, or moment sparked this idea? The context often matters as much as the idea itself for future retrieval. Include it in the page.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Generate an original idea in conversation (e.g., "I call this the 'ambition debt' problem -- every year you delay going big, the compound interest works against you"). Confirm a new page appears at `brain/originals/ambition-debt` with `gbrain get originals/ambition-debt`.
|
||||
2. Check that the page uses the user's exact phrasing for the title and slug -- not a sanitized version.
|
||||
3. Run `gbrain get_links originals/ambition-debt`. Confirm cross-links exist to related people, meetings, or other originals.
|
||||
4. Express a take on someone else's idea (e.g., "I think Thiel's contrarian question is wrong because..."). Confirm it goes to `originals/` (synthesis is original), not `concepts/`.
|
||||
5. Run `gbrain search "ambition debt"`. Confirm the originals page appears in search results and is discoverable.
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,137 +0,0 @@
|
||||
# Plugin handlers — registering host-specific Minion handlers
|
||||
|
||||
GBrain's Minion worker ships with seven built-in handlers: `sync`,
|
||||
`embed`, `lint`, `import`, `extract`, `backlinks`, `autopilot-cycle`.
|
||||
These cover every background operation the gbrain CLI itself performs.
|
||||
|
||||
Host platforms (Wintermute, other OpenClaw deployments, future hosts)
|
||||
register their own handlers via a plugin bootstrap that imports
|
||||
`gbrain/minions`. No `handlers.json`-style data file — handlers are
|
||||
code, loaded by the worker, with the same trust model as any other
|
||||
code in the host's repo.
|
||||
|
||||
## Why code, not data
|
||||
|
||||
An earlier design draft shipped `~/.claude/gbrain-handlers.json` where
|
||||
each entry was a shell command the worker would exec on job claim.
|
||||
Codex flagged this as a durable RCE surface: an agent-writable data
|
||||
file that spawns arbitrary shell. We dropped the data-file approach;
|
||||
handlers are code that the host imports explicitly and ships through
|
||||
code review.
|
||||
|
||||
## The plugin contract
|
||||
|
||||
A host worker bootstrap looks like this (TypeScript):
|
||||
|
||||
```ts
|
||||
import { MinionQueue, MinionWorker } from 'gbrain/minions';
|
||||
import type { BrainEngine } from 'gbrain/engine';
|
||||
|
||||
async function main() {
|
||||
const engine: BrainEngine = /* your engine setup */;
|
||||
await engine.connect({});
|
||||
|
||||
const worker = new MinionWorker(engine, { queue: 'default' });
|
||||
|
||||
// Register every host-specific handler the host's cron manifest references.
|
||||
// Each handler returns a plain object (serialized as the job result).
|
||||
// Throw on failure — the worker catches and retries per max_attempts.
|
||||
|
||||
worker.register('ea-inbox-sweep', async (ctx) => {
|
||||
const slot = ctx.data.slot ?? new Date().toISOString();
|
||||
// Host-specific agent turn: call your LLM, scan the inbox, write
|
||||
// brain pages, return a summary. ctx.signal.aborted indicates the
|
||||
// worker wants you to cooperate with shutdown — honor it.
|
||||
return { swept: true, slot };
|
||||
});
|
||||
|
||||
worker.register('morning-briefing', async (ctx) => {
|
||||
/* host logic */
|
||||
return { briefed: true };
|
||||
});
|
||||
|
||||
// Call start() AFTER every handler is registered. The worker's
|
||||
// stall-detector ignores jobs whose name is not in the registered set.
|
||||
await worker.start();
|
||||
}
|
||||
|
||||
main().catch(err => { console.error(err); process.exit(1); });
|
||||
```
|
||||
|
||||
Ship this as a separate binary in the host repo (e.g. `wintermute-worker`)
|
||||
or as a side-effect module that the stock `gbrain jobs work` command
|
||||
auto-loads on startup (configurable via a host-provided entry point).
|
||||
|
||||
## Handler contract
|
||||
|
||||
Every handler receives a `MinionJobContext`:
|
||||
|
||||
```ts
|
||||
interface MinionJobContext {
|
||||
data: Record<string, unknown>; // job params (whatever the cron submit passed)
|
||||
job: MinionJob; // full job row (id, queue, attempts, etc.)
|
||||
signal: AbortSignal; // set to aborted when the worker is shutting down
|
||||
inbox: MinionInbox; // read messages sent to this job while it runs
|
||||
}
|
||||
```
|
||||
|
||||
Return a serializable object on success. Throw on failure (the worker
|
||||
will log + retry per `max_attempts`).
|
||||
|
||||
**Abort cooperation.** When `ctx.signal.aborted` becomes true, finish
|
||||
gracefully. The worker will wait 30s for you to return before SIGKILL.
|
||||
Long-running LLM calls should pass the signal through to whatever
|
||||
network library they use.
|
||||
|
||||
**Idempotency.** The queue enforces unique `idempotency_key` at the DB
|
||||
layer, so you don't need to worry about double-submits from a cron that
|
||||
fires while the previous invocation is still running.
|
||||
|
||||
## Gbrain's migration flow
|
||||
|
||||
The v0.11.0 migration orchestrator (run by `gbrain apply-migrations`)
|
||||
detects cron entries whose handler name is NOT in GBrain's builtin set
|
||||
and emits a structured TODO to `~/.gbrain/migrations/pending-host-work.jsonl`.
|
||||
Each TODO has shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "cron-handler-needs-host-registration",
|
||||
"handler": "ea-inbox-sweep",
|
||||
"cron_schedule": "0 */30 * * *",
|
||||
"manifest_path": "/path/to/cron/jobs.json",
|
||||
"current_cmd": "agentTurn ea-inbox-sweep",
|
||||
"recommendation": "Add a handler registration for `ea-inbox-sweep` in your host worker bootstrap per docs/guides/plugin-handlers.md. Once registered, re-run `gbrain apply-migrations` to auto-rewrite this entry.",
|
||||
"status": "pending"
|
||||
}
|
||||
```
|
||||
|
||||
The host agent walks these entries using `skills/migrations/v0.11.0.md`:
|
||||
|
||||
1. Read `~/.gbrain/migrations/pending-host-work.jsonl`.
|
||||
2. For each `cron-handler-needs-host-registration` row, ship a handler
|
||||
registration in the host's worker bootstrap following the pattern
|
||||
above.
|
||||
3. Deploy the updated worker.
|
||||
4. Re-run `gbrain apply-migrations --yes`. The orchestrator now
|
||||
recognizes the newly-registerable handler (worker writes the
|
||||
registered names to a discovery file on startup) and rewrites the
|
||||
cron entry to use `gbrain jobs submit`. The JSONL row is marked
|
||||
`status: "complete"`.
|
||||
|
||||
## Trust boundary
|
||||
|
||||
Handler code runs inside the worker process with the same privileges
|
||||
as the rest of the host binary. There is no elevation. But there is
|
||||
also no runtime sandbox — handlers can read + write anywhere the
|
||||
worker user can. Review handler PRs the same way you review any other
|
||||
code that touches production data.
|
||||
|
||||
## Related
|
||||
|
||||
- `skills/conventions/cron-via-minions.md` — the rewrite convention
|
||||
for cron manifests.
|
||||
- `skills/migrations/v0.11.0.md` — how the migration orchestrator
|
||||
drives the host agent through this work.
|
||||
- `skills/minion-orchestrator/SKILL.md` — patterns for submitting,
|
||||
monitoring, steering, and replaying jobs once the handler is live.
|
||||
@@ -1,165 +0,0 @@
|
||||
# Quiet Hours and Timezone-Aware Delivery
|
||||
|
||||
## Goal
|
||||
|
||||
Hold all notifications during sleep hours, merge held messages into the morning briefing, and adjust automatically when the user travels.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: 3 AM pings from cron jobs. One bad notification and the user
|
||||
disables the entire system.
|
||||
|
||||
With this: the brain works overnight (dream cycle, collectors, enrichment)
|
||||
but notifications are held until morning. Travel to Tokyo? The system adjusts
|
||||
automatically from your calendar, no config change needed.
|
||||
|
||||
## Implementation
|
||||
|
||||
### Quiet Hours Gate
|
||||
|
||||
Every cron job that sends notifications must check quiet hours FIRST.
|
||||
|
||||
```
|
||||
QUIET_START = 23 // 11 PM local time
|
||||
QUIET_END = 8 // 8 AM local time
|
||||
|
||||
is_quiet(local_hour):
|
||||
return local_hour >= QUIET_START OR local_hour < QUIET_END
|
||||
```
|
||||
|
||||
**Before sending any notification:**
|
||||
1. Determine user's current timezone (from config or heartbeat state)
|
||||
2. Convert current UTC time to local time
|
||||
3. If quiet hours: hold the message, don't send
|
||||
|
||||
### Held Messages
|
||||
|
||||
During quiet hours, output goes to a held directory instead of being sent:
|
||||
|
||||
```
|
||||
if is_quiet():
|
||||
mkdir -p /tmp/cron-held/
|
||||
write("/tmp/cron-held/{job-name}.md", output)
|
||||
exit // don't send
|
||||
else:
|
||||
send(output)
|
||||
```
|
||||
|
||||
The morning briefing picks up held messages:
|
||||
|
||||
```
|
||||
morning_briefing():
|
||||
held_files = list("/tmp/cron-held/*.md")
|
||||
if held_files:
|
||||
briefing += "## Overnight Updates\n\n"
|
||||
for file in held_files:
|
||||
briefing += read(file)
|
||||
delete(file)
|
||||
```
|
||||
|
||||
This way nothing is lost. Overnight cron results get folded into the
|
||||
first thing the user sees in the morning.
|
||||
|
||||
### Timezone Awareness
|
||||
|
||||
The agent should know what timezone the user is in. Store it in
|
||||
the agent's operational state:
|
||||
|
||||
```json
|
||||
{
|
||||
"currentLocation": {
|
||||
"timezone": "US/Pacific",
|
||||
"city": "San Francisco"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Update the timezone when:**
|
||||
- Calendar shows the user flying somewhere (check for airline/hotel events)
|
||||
- User mentions being in a different city
|
||||
- User's active hours shift (they're responding at 3 AM PT = they're probably traveling)
|
||||
|
||||
**All times shown to the user should be in their LOCAL timezone.** Never
|
||||
show UTC or a timezone the user isn't in.
|
||||
|
||||
### Shell Implementation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# quiet-hours-gate.sh — run before any notification
|
||||
|
||||
TIMEZONE="${USER_TIMEZONE:-US/Pacific}"
|
||||
LOCAL_HOUR=$(TZ="$TIMEZONE" date +%H)
|
||||
|
||||
if [ "$LOCAL_HOUR" -ge 23 ] || [ "$LOCAL_HOUR" -lt 8 ]; then
|
||||
echo "QUIET_HOURS=true"
|
||||
exit 1 # don't send
|
||||
fi
|
||||
|
||||
echo "QUIET_HOURS=false"
|
||||
exit 0 # ok to send
|
||||
```
|
||||
|
||||
**In cron job scripts:**
|
||||
```bash
|
||||
# Check quiet hours first
|
||||
if ! bash scripts/quiet-hours-gate.sh; then
|
||||
mkdir -p /tmp/cron-held
|
||||
echo "$OUTPUT" > /tmp/cron-held/$(basename "$0" .sh).md
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Not quiet hours — send normally
|
||||
send_notification "$OUTPUT"
|
||||
```
|
||||
|
||||
### Configurable Hours
|
||||
|
||||
Some users want different quiet hours. Store the config:
|
||||
|
||||
```json
|
||||
{
|
||||
"quiet_hours": {
|
||||
"start": 23,
|
||||
"end": 8,
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Set `enabled: false` to disable quiet hours entirely (e.g., for 24/7 monitoring).
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Gate on EVERY job.** The quiet hours check must run before every single
|
||||
cron job that produces notifications. If even one job skips the gate, the
|
||||
user gets a 3 AM ping and loses trust in the entire system. No exceptions.
|
||||
|
||||
2. **Held messages MUST be picked up.** If the morning briefing doesn't read
|
||||
`/tmp/cron-held/`, overnight results vanish silently. Verify the briefing
|
||||
skill reads and clears the held directory. Orphaned held files mean the
|
||||
pickup integration is broken.
|
||||
|
||||
3. **Timezone auto-detection is fragile.** Calendar-based timezone detection
|
||||
relies on the user having airline/hotel events with location data. If the
|
||||
user books travel without calendar entries, the system won't detect the
|
||||
move. Fall back to activity-hour analysis (responding at 3 AM PT = probably
|
||||
not in PT anymore) and ask the user if uncertain.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Set quiet hours to the current hour.** Temporarily set `QUIET_START` to
|
||||
one hour before now and `QUIET_END` to one hour after. Trigger a cron job.
|
||||
Verify the output goes to `/tmp/cron-held/` instead of being sent.
|
||||
|
||||
2. **Check held message pickup.** After step 1, run or simulate the morning
|
||||
briefing. Verify the held message appears in the "Overnight Updates"
|
||||
section and the file is deleted from `/tmp/cron-held/`.
|
||||
|
||||
3. **Verify timezone adjustment.** Change the timezone config to a zone where
|
||||
it's currently quiet hours. Trigger a notification. Verify it's held. Change
|
||||
back to your real timezone during active hours. Trigger again. Verify it sends.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,158 +0,0 @@
|
||||
# Two-Repo Architecture: Agent Behavior vs World Knowledge
|
||||
|
||||
## Goal
|
||||
|
||||
Separate agent behavior (replaceable) from world knowledge (permanent) into two repos with strict boundaries.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: agent config and world knowledge are mixed together. Switch agents
|
||||
and you lose your knowledge. Switch knowledge tools and you lose your agent setup.
|
||||
|
||||
With this: your brain (14,700+ files of people, companies, meetings, ideas)
|
||||
survives any agent swap. Your agent config survives any knowledge tool swap.
|
||||
|
||||
## Implementation
|
||||
|
||||
### The Boundary Test
|
||||
|
||||
**"Is this about how the agent operates, or is this knowledge about the world?"**
|
||||
|
||||
| Question | If YES -> Agent Repo | If YES -> Brain Repo |
|
||||
|----------|---------------------|---------------------|
|
||||
| Would this file transfer if you switched AI agents? | YES | -- |
|
||||
| Would this file transfer if you switched to a different person? | -- | YES |
|
||||
| Is this about how the agent behaves? | YES | -- |
|
||||
| Is this about a person, company, deal, meeting, or idea? | -- | YES |
|
||||
|
||||
### Quick Decision Tree
|
||||
|
||||
```
|
||||
New file to create?
|
||||
|-- About a person, company, deal, project, meeting, idea? -> brain/
|
||||
|-- A spec, research doc, or strategic analysis? -> brain/
|
||||
|-- An original idea or observation? -> brain/originals/
|
||||
|-- A daily session log or heartbeat state? -> agent-repo/
|
||||
|-- A skill, config, cron, or ops file? -> agent-repo/
|
||||
|-- A task or todo? -> agent-repo/tasks/
|
||||
```
|
||||
|
||||
### Agent Repo (operational config)
|
||||
|
||||
How the agent works. Identity, configuration, operational state.
|
||||
|
||||
```
|
||||
agent-repo/
|
||||
├── AGENTS.md # Agent identity + operational rules
|
||||
├── SOUL.md # Persona, voice, values
|
||||
├── USER.md # User preferences + context
|
||||
├── HEARTBEAT.md # Daily ops flow
|
||||
├── TOOLS.md # Available tools + credentials
|
||||
├── MEMORY.md # Operational memory (preferences, decisions)
|
||||
├── skills/ # Agent capabilities (SKILL.md files)
|
||||
│ ├── ingest/SKILL.md
|
||||
│ ├── query/SKILL.md
|
||||
│ ├── enrich/SKILL.md
|
||||
│ └── ...
|
||||
├── cron/ # Scheduled jobs
|
||||
│ └── jobs.json
|
||||
├── tasks/ # Current task list
|
||||
│ └── current.md
|
||||
├── hooks/ # Event hooks + transforms
|
||||
├── scripts/ # Operational scripts (collectors, gates)
|
||||
└── memory/ # Session logs, state files
|
||||
├── heartbeat-state.json
|
||||
└── YYYY-MM-DD.md # Daily session logs
|
||||
```
|
||||
|
||||
### Brain Repo (world knowledge)
|
||||
|
||||
What you know. People, companies, deals, meetings, ideas, media.
|
||||
This is the repo GBrain indexes.
|
||||
|
||||
```
|
||||
brain/
|
||||
├── people/ # Person dossiers (compiled truth + timeline)
|
||||
├── companies/ # Company profiles
|
||||
├── deals/ # Deal tracking
|
||||
├── meetings/ # Meeting transcripts + analysis
|
||||
├── originals/ # YOUR original thinking (highest value)
|
||||
├── concepts/ # World concepts and frameworks
|
||||
├── ideas/ # Product and business ideas
|
||||
├── media/ # Video transcripts, books, articles
|
||||
│ ├── youtube/
|
||||
│ ├── podcasts/
|
||||
│ └── articles/
|
||||
├── sources/ # Source material summaries
|
||||
├── daily/ # Daily data (calendar, logs)
|
||||
│ └── calendar/
|
||||
│ └── YYYY/
|
||||
│ └── YYYY-MM-DD.md
|
||||
├── projects/ # Project specs and docs
|
||||
├── writing/ # Essays, drafts, published work
|
||||
├── diligence/ # Investment diligence materials
|
||||
│ └── company-name/
|
||||
│ ├── index.md
|
||||
│ ├── pitch-deck.md
|
||||
│ └── .raw/ # Original PDFs/files
|
||||
└── Apple Notes/ # Imported Apple Notes archive
|
||||
```
|
||||
|
||||
### The Hard Rule
|
||||
|
||||
**Never write knowledge to the agent repo.** If a skill, sub-agent, or cron
|
||||
job needs to create a file about a person, company, deal, meeting, project,
|
||||
or idea, it MUST write to the brain repo, never to the agent repo.
|
||||
|
||||
The brain is the permanent record. The agent repo is replaceable.
|
||||
|
||||
### Why Two Repos
|
||||
|
||||
**Independence.** You can switch AI agents (OpenClaw -> Hermes -> custom) without
|
||||
losing your knowledge. You can switch knowledge tools (GBrain -> something else)
|
||||
without losing your agent setup.
|
||||
|
||||
**Scale.** The brain grows large (10,000+ files). The agent repo stays small
|
||||
(< 100 files). Different backup strategies, different sync cadences.
|
||||
|
||||
**Privacy.** The brain contains sensitive information (people, deals, personal
|
||||
notes). The agent repo contains operational config. Different access controls.
|
||||
|
||||
**GBrain indexes the brain repo.** Run `gbrain sync --repo ~/brain/` to keep
|
||||
the search index current. The agent repo is never indexed by GBrain.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Never write knowledge to the agent repo.** This is the most common
|
||||
violation. A skill that creates a person page, a cron job that saves
|
||||
meeting notes, a sub-agent that captures an idea -- all of these MUST
|
||||
write to the brain repo. If it's about the world, it goes in the brain.
|
||||
|
||||
2. **The brain is the permanent record.** When in doubt, ask: "Would this
|
||||
file survive switching to a completely different AI agent?" If yes, it
|
||||
belongs in the brain. Agent configs, skills, cron jobs, and operational
|
||||
state are replaceable. People, companies, ideas, and meetings are not.
|
||||
|
||||
3. **Don't index the agent repo.** GBrain indexes the brain repo only.
|
||||
Running `gbrain sync` against the agent repo pollutes search results
|
||||
with operational config instead of world knowledge.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Check file placement.** After any skill or cron job creates a file,
|
||||
verify it landed in the correct repo. Person/company/idea/meeting files
|
||||
should be in `brain/`. Skill/config/cron/state files should be in the
|
||||
agent repo. Any knowledge file in the agent repo is a boundary violation.
|
||||
|
||||
2. **Run the boundary test.** Pick 5 recently created files and ask: "Would
|
||||
this transfer if I switched AI agents?" and "Would this transfer if I
|
||||
switched to a different person?" If the answers don't match the file's
|
||||
location, it's in the wrong repo.
|
||||
|
||||
3. **Verify GBrain only indexes brain.** Run `gbrain stats` and check the
|
||||
indexed paths. None should point to the agent repo directory. If agent
|
||||
config files appear in search results, the sync target is misconfigured.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,78 +0,0 @@
|
||||
# Search Modes
|
||||
|
||||
## Goal
|
||||
Know which search command to use and when -- keyword, hybrid, or direct -- so every lookup is fast and returns the right result.
|
||||
|
||||
## What the User Gets
|
||||
Without this: the agent fumbles between search commands, returns chunks when full pages are needed, runs expensive semantic searches when a direct get would do, or misses results entirely. With this: every lookup uses the optimal mode, token budgets are respected, and the user gets the right information in the fewest calls.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
on user_asks_about(topic):
|
||||
# Decision tree: pick the right search mode
|
||||
|
||||
if know_exact_slug(topic):
|
||||
# MODE 3: Direct get -- instant, no search overhead
|
||||
result = gbrain get <slug>
|
||||
# e.g., "Tell me about Pedro" -> gbrain get pedro-franceschi
|
||||
# Returns the FULL page -- compiled truth + timeline
|
||||
|
||||
elif topic.is_exact_name or topic.is_keyword:
|
||||
# MODE 1: Keyword search -- fast, no embeddings needed, day-one ready
|
||||
results = gbrain search "{name_or_keyword}"
|
||||
# e.g., "Find anything about Series A" -> gbrain search "Series A"
|
||||
# Returns CHUNKS, not full pages
|
||||
|
||||
# IMPORTANT: keyword search returns chunks
|
||||
# If the chunk confirms relevance, THEN load the full page:
|
||||
if chunk.confirms_relevance:
|
||||
full_page = gbrain get <slug_from_chunk>
|
||||
|
||||
elif topic.is_semantic_question:
|
||||
# MODE 2: Hybrid search -- semantic + keyword, needs embeddings
|
||||
results = gbrain query "{natural language question}"
|
||||
# e.g., "Who do I know at fintech companies?" -> gbrain query "fintech contacts"
|
||||
# Returns ranked chunks via vector + keyword + RRF
|
||||
|
||||
# Same rule: chunks first, then get full page if needed
|
||||
if chunk.confirms_relevance:
|
||||
full_page = gbrain get <slug_from_chunk>
|
||||
|
||||
# Quick reference:
|
||||
# | Mode | Command | Needs Embeddings | Speed | Best For |
|
||||
# |---------|----------------------|------------------|---------|---------------------------------|
|
||||
# | Keyword | gbrain search "term" | No | Fastest | Known names, exact matches |
|
||||
# | Hybrid | gbrain query "..." | Yes | Fast | Semantic questions, fuzzy match |
|
||||
# | Direct | gbrain get <slug> | No | Instant | When you know the slug |
|
||||
|
||||
# Progression over time:
|
||||
# Day 1: keyword search (works without embeddings)
|
||||
# After first embed: hybrid search unlocked
|
||||
# Once you know slugs: direct get for speed
|
||||
|
||||
# Precedence for conflicting information within a page:
|
||||
# 1. User's direct statements (always wins)
|
||||
# 2. Compiled truth sections (synthesized from evidence)
|
||||
# 3. Timeline entries (raw signal, reverse chronological)
|
||||
# 4. External sources (web search, APIs)
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Search returns chunks, not full pages.** After `gbrain search` or `gbrain query`, you get excerpts. Always run `gbrain get <slug>` to load the full page when the chunk confirms relevance. Don't answer questions from chunks alone when the full context matters.
|
||||
2. **Keyword search works without embeddings.** On day one before any embedding run, `gbrain search` still works. Don't tell the user "search isn't available yet" -- keyword search is always available.
|
||||
3. **Don't use hybrid search for known names.** `gbrain query "Pedro Franceschi"` wastes embedding compute. Use `gbrain search "Pedro Franceschi"` or better yet `gbrain get pedro-franceschi` if you know the slug.
|
||||
4. **Token budget awareness.** A full page via `gbrain get` can be large. Read the search chunks first to confirm relevance before pulling the full page. "Did anyone mention the Series A?" -- search results (chunks) are probably enough. "Tell me everything about Pedro" -- get the full page.
|
||||
5. **Hybrid search needs embeddings to have been run.** If `gbrain query` returns nothing but `gbrain search` finds results, the embeddings haven't been generated yet. Run the embedding pipeline first.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Run `gbrain search "Pedro"` -- confirm it returns chunks with matching text and slug references.
|
||||
2. Run `gbrain query "who works at fintech companies"` -- confirm it returns semantically relevant results (not just keyword matches on "fintech").
|
||||
3. Run `gbrain get pedro-franceschi` -- confirm it returns the full page with compiled truth and timeline.
|
||||
4. Compare: search for the same entity using all three modes. Keyword should be fastest, hybrid should surface conceptual matches, direct should return the complete page.
|
||||
5. After a search returns a chunk, run `gbrain get` on the slug from that chunk. Confirm the full page contains more context than the chunk alone.
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,131 +0,0 @@
|
||||
# Skill Development Cycle
|
||||
|
||||
## Goal
|
||||
|
||||
Turn every repeating task into a durable, automated skill so that if you ask twice, it should already be running on a cron.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: ad-hoc work that the agent forgets how to do. You ask "enrich
|
||||
this person" and the agent invents a new process each time. Quality varies.
|
||||
|
||||
With this: every capability is codified, tested, and scheduled. Enrichment
|
||||
runs the same way every time. New patterns get skill-ified within a day.
|
||||
|
||||
## Implementation
|
||||
|
||||
**The Rule:** If you have to ask your agent for something twice, it should
|
||||
already be a skill running on a cron. First time is discovery. Second time
|
||||
is system failure.
|
||||
|
||||
### The 5-Step Cycle
|
||||
|
||||
**Step 1: Concept the Process.**
|
||||
Describe what needs to happen in plain language:
|
||||
- What's the input? What's the output? What triggers it?
|
||||
- What data sources does it touch?
|
||||
- How often should it run?
|
||||
|
||||
**Step 2: Run Manually for 3-10 Items.**
|
||||
Actually do the work by hand on a small batch. This is the prototype phase.
|
||||
Do NOT write a SKILL.md yet. Just do the work and observe:
|
||||
- What does the output actually look like?
|
||||
- What edge cases appear?
|
||||
- What quality bar is right?
|
||||
|
||||
**Step 3: Evaluate Output.**
|
||||
Show the user the results. Get feedback.
|
||||
- Does output look good? Is quality right?
|
||||
- Did you miss anything? Over-engineer?
|
||||
- Revise the process based on what you learned.
|
||||
|
||||
**Step 4: Codify into a Skill.**
|
||||
Write the SKILL.md. Either:
|
||||
- **New skill** -- genuinely new capability
|
||||
- **Add to existing skill** -- variation of something that exists (parameterize it)
|
||||
|
||||
The skill must be:
|
||||
- **Durable** -- works tomorrow, next week, next month without manual intervention
|
||||
- **MECE** -- doesn't overlap with other skills (see below)
|
||||
- **Parameterized** -- handles variations through parameters, not separate skills
|
||||
|
||||
**Step 5: Add to Cron (if recurring).**
|
||||
If the process should run automatically:
|
||||
- Add to existing cron job if it fits naturally
|
||||
- Create new cron job if it has a distinct scheduling concern
|
||||
- Monitor the first 2-3 automated runs for quality
|
||||
- Fix issues that emerge at scale
|
||||
|
||||
### MECE Discipline
|
||||
|
||||
Skills should be **Mutually Exclusive, Collectively Exhaustive**:
|
||||
- Each entity type has exactly ONE owner skill
|
||||
- Each signal source has exactly ONE owner skill
|
||||
- Two skills creating the same brain page = MECE violation
|
||||
|
||||
**Example ownership (no overlap):**
|
||||
|
||||
| Signal Source | Owner Skill | Creates |
|
||||
|--------------|-------------|---------|
|
||||
| Meeting transcripts | meeting-ingestion | brain/meetings/ pages |
|
||||
| Email messages | executive-assistant | brain/people/ timeline entries |
|
||||
| X/Twitter posts | x-collector | brain/media/ pages |
|
||||
| Person enrichment | enrich | brain/people/ compiled truth |
|
||||
| Calendar events | calendar-sync | brain/daily/calendar/ pages |
|
||||
| Video/podcast content | media-ingest | brain/media/ pages |
|
||||
|
||||
### Quality Bar Checklist
|
||||
|
||||
A skill is ready when:
|
||||
|
||||
- [ ] Ran successfully on 3-10 real items with good output
|
||||
- [ ] User reviewed output and approved
|
||||
- [ ] SKILL.md is under 500 lines (use references for overflow)
|
||||
- [ ] Checks notability before creating brain pages (don't create pages for nobodies)
|
||||
- [ ] Has citation enforcement (every fact has a source)
|
||||
- [ ] Doesn't overlap with existing skills (MECE)
|
||||
- [ ] If recurring: on a cron with appropriate schedule
|
||||
- [ ] If it creates brain pages: checks notability first
|
||||
|
||||
### What This Means in Practice
|
||||
|
||||
- Don't do ad-hoc brain enrichment, use the enrich skill
|
||||
- Don't manually check social media, use an automated cron
|
||||
- Don't manually ingest meeting notes, use the meeting-sync recipe
|
||||
- Don't manually create entity pages, use the entity detector
|
||||
- If a new pattern emerges, prototype it, skill-ify it, cron-ify it
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **MECE violations compound silently.** Two skills that both create
|
||||
`brain/people/` pages will produce duplicates and conflicting data.
|
||||
Before creating a new skill, check the ownership table. If an existing
|
||||
skill already owns that entity type, extend it with parameters instead
|
||||
of creating a new skill.
|
||||
|
||||
2. **The quality bar is real.** Don't ship a skill that hasn't been tested
|
||||
on 3-10 real items with user approval. A skill that produces bad output
|
||||
is worse than no skill -- it creates bad brain pages at scale on a cron.
|
||||
|
||||
3. **Don't create stubs.** A SKILL.md with "TODO: implement" is not a skill.
|
||||
Every skill must be complete enough to run end-to-end on real data. If
|
||||
you can't finish it, don't create the file. Keep it as manual work until
|
||||
you can do it right.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Run the skill on 3 real items.** Execute the skill against live data
|
||||
(not test data). Check that the output matches the quality bar: citations
|
||||
present, notability checked, no stubs created.
|
||||
|
||||
2. **Check MECE against existing skills.** Review the ownership table. Does
|
||||
this new skill create pages in a directory already owned by another skill?
|
||||
If yes, it's a MECE violation. Merge or parameterize instead.
|
||||
|
||||
3. **Verify the quality bar checklist.** Walk through every item in the
|
||||
Quality Bar Checklist above. If any item is unchecked, the skill isn't
|
||||
ready for cron deployment.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,75 +0,0 @@
|
||||
# Source Attribution
|
||||
|
||||
## Goal
|
||||
Every fact in the brain traces to where it came from -- who said it, in what context, and when.
|
||||
|
||||
## What the User Gets
|
||||
Without this: six months from now, someone reads a brain page and has no idea if "Pedro co-founded Brex" came from Pedro himself, a LinkedIn scrape, or a hallucination. With this: every claim is auditable, conflicts are surfaced, and the brain is a court-admissible record of reality.
|
||||
|
||||
## Implementation
|
||||
|
||||
```
|
||||
on brain_write(page, fact):
|
||||
# EVERY fact gets a citation -- compiled truth AND timeline
|
||||
citation = format_citation(source)
|
||||
# format: [Source: {who}, {channel/context}, {date} {time} {tz}]
|
||||
|
||||
# Category-specific formats:
|
||||
if source.type == "direct":
|
||||
# [Source: User, direct message, 2026-04-07 12:33 PM PT]
|
||||
elif source.type == "meeting":
|
||||
# [Source: Meeting notes "Team Sync" #12345, 2026-04-03 12:11 PM PT]
|
||||
elif source.type == "api_enrichment":
|
||||
# [Source: Crustdata LinkedIn enrichment, 2026-04-07 12:35 PM PT]
|
||||
elif source.type == "social_media":
|
||||
# MUST include full URL -- not just @handle
|
||||
# [Source: X/@pedroh96 tweet, product launch, 2026-04-07](https://x.com/pedroh96/status/...)
|
||||
elif source.type == "email":
|
||||
# [Source: email from Sarah Chen re Q2 board deck, 2026-04-05 2:30 PM PT]
|
||||
elif source.type == "workspace":
|
||||
# [Source: Slack #engineering, Keith re deploy schedule, 2026-04-06 11:45 AM PT]
|
||||
elif source.type == "web":
|
||||
# [Source: Happenstance research, 2026-04-07 12:35 PM PT]
|
||||
elif source.type == "published":
|
||||
# [Source: [Wall Street Journal, 2026-04-05](https://wsj.com/...)]
|
||||
elif source.type == "funding":
|
||||
# [Source: Captain API funding data, 2026-04-07 2:00 PM PT]
|
||||
|
||||
# Attach citation inline with the fact
|
||||
gbrain put <slug> --content "...fact [Source: ...]..."
|
||||
|
||||
# When sources conflict, note BOTH -- never silently pick one
|
||||
if conflicts_exist(fact, existing_page):
|
||||
append_to_compiled_truth(
|
||||
"Conflict: Source A says X, Source B says Y. "
|
||||
"[Source: A] [Source: B]"
|
||||
)
|
||||
|
||||
# Source hierarchy for conflict resolution (highest authority first):
|
||||
SOURCE_PRIORITY = [
|
||||
"User direct statements", # 1 -- always wins
|
||||
"Primary sources", # 2 -- meetings, emails, direct conversations
|
||||
"Enrichment APIs", # 3 -- Crustdata, Happenstance, Captain
|
||||
"Web search results", # 4
|
||||
"Social media posts", # 5
|
||||
]
|
||||
```
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Compiled truth is NOT exempt from citations.** "Pedro co-founded Brex" in the synthesis section needs `[Source: ...]` just as much as a timeline entry does. Most agents skip citations above the bar.
|
||||
2. **Tweet URLs are mandatory.** `[Source: X/@handle tweet, topic, date]` without a URL is a broken citation. Hundreds of brain pages end up with unreachable tweet references when the URL is omitted. Always: `[Source: X/@handle tweet, topic, date](https://x.com/handle/status/ID)`.
|
||||
3. **"User said it" isn't enough.** WHERE, ABOUT WHAT, WHEN. `[Source: User, direct message, 2026-04-07 12:33 PM PT]` -- not just `[Source: User]`.
|
||||
4. **Don't silently resolve conflicts.** When the user says one thing and an API says another, note the contradiction in compiled truth with both citations. Let the reader decide.
|
||||
5. **Timeline entries need sources too.** Every append to the timeline carries provenance. A timeline entry without a source is an orphan fact.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. Open any brain page with `gbrain get <slug>`. Read the compiled truth section above the bar. Every factual claim should have an inline `[Source: ...]` citation.
|
||||
2. Search for tweet references: `gbrain search "X/@"`. Every result should have a full URL, not just an @handle.
|
||||
3. Find a page with data from multiple sources (e.g., a person enriched via API + mentioned in a meeting). Confirm both sources are cited independently.
|
||||
4. Check timeline entries on 3 random pages. Each entry should have a source citation with date and context.
|
||||
5. Look for a page where the user stated something that contradicts an API result. Confirm the contradiction is noted, not silently resolved.
|
||||
|
||||
---
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,122 +0,0 @@
|
||||
# Sub-Agent Model Routing
|
||||
|
||||
## Goal
|
||||
|
||||
Route sub-agents to the cheapest model that can do the job, saving 10-40x on costs without sacrificing quality.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: every sub-agent runs on Opus ($15/MTok). Entity detection on
|
||||
every message costs $3-5/day. Research tasks cost $10+ each.
|
||||
|
||||
With this: entity detection runs on Sonnet ($3/MTok, 5x cheaper). Research
|
||||
runs on DeepSeek ($0.50/MTok, 30x cheaper). Main session stays on Opus for
|
||||
quality. Total cost drops 70-80%.
|
||||
|
||||
## Implementation
|
||||
|
||||
### Routing Table
|
||||
|
||||
| Task Type | Recommended Model | Why |
|
||||
|-----------|------------------|-----|
|
||||
| Main session / complex instructions | Opus-class (default) | Best reasoning and instruction following |
|
||||
| Research / synthesis / analysis | DeepSeek V3 or equivalent | 25-40x cheaper, strong on exploratory work |
|
||||
| Structured output / long context | Large context model (Qwen, Gemini) | 200K+ context, reliable JSON output |
|
||||
| Fast lightweight sub-agents | Fast inference model (Groq) | 500 tok/s, cheap, good for quick tasks |
|
||||
| Deep reasoning (use sparingly) | Reasoning model (DeepSeek-R1, o3) | Best for hard problems, expensive |
|
||||
| Entity detection (signal detector) | Sonnet-class | Fast, cheap, sufficient quality for detection |
|
||||
|
||||
### The Signal Detector Pattern
|
||||
|
||||
Spawn a lightweight sub-agent on EVERY inbound message. This is mandatory.
|
||||
|
||||
```
|
||||
on_every_message(text):
|
||||
// Spawn async — don't block the response
|
||||
spawn_subagent({
|
||||
task: `SIGNAL DETECTION — scan this message:
|
||||
"${text}"
|
||||
|
||||
1. IDEAS FIRST: Is the user expressing an original thought?
|
||||
If yes -> create/update brain/originals/ with EXACT phrasing
|
||||
2. ENTITIES: Extract person names, company names, media titles
|
||||
For each -> check brain, create/enrich if notable
|
||||
3. FACTS: New info about existing entities -> update timeline
|
||||
4. CITATIONS: Every fact needs [Source: ...] attribution
|
||||
5. Sync changes to brain repo`,
|
||||
model: "sonnet-class", // fast + cheap
|
||||
timeout: 120s
|
||||
})
|
||||
```
|
||||
|
||||
**Why Sonnet-class for detection:** Entity detection is pattern matching, not
|
||||
deep reasoning. Sonnet is 5-10x cheaper than Opus and fast enough for async
|
||||
detection. The main session continues on Opus while detection runs in parallel.
|
||||
|
||||
### Research Pipeline Pattern
|
||||
|
||||
For research-heavy tasks, use a multi-model pipeline:
|
||||
|
||||
```
|
||||
1. PLANNING (Opus): Write research brief, identify what to look for
|
||||
2. EXECUTION (DeepSeek): Sub-agent does the actual research (web, APIs, docs)
|
||||
3. SYNTHESIS (Opus): Read research output, add strategic analysis
|
||||
```
|
||||
|
||||
**Why this works:** The planning and synthesis steps need taste and judgment
|
||||
(Opus). The execution step is mechanical data gathering (DeepSeek at 25-40x
|
||||
lower cost). You get Opus-quality output at DeepSeek-level cost for 80% of
|
||||
the work.
|
||||
|
||||
### When to Spawn Sub-Agents
|
||||
|
||||
| Situation | Spawn? | Model |
|
||||
|-----------|--------|-------|
|
||||
| Every inbound message | YES (mandatory) | Sonnet |
|
||||
| Research request | YES | DeepSeek for execution |
|
||||
| Quick lookup / fact check | YES | Fast model (Groq) |
|
||||
| Complex analysis | NO -- handle in main session | Opus |
|
||||
| Writing / editing | NO -- handle in main session | Opus |
|
||||
|
||||
### Cost Optimization
|
||||
|
||||
The main session runs on your best model. Everything else runs on the
|
||||
cheapest model that can do the job. In practice, 60-70% of sub-agent
|
||||
work is entity detection (Sonnet) and research execution (DeepSeek),
|
||||
which are 10-40x cheaper than the main session model.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Sonnet, not Opus, for detection.** The most common mistake is running
|
||||
entity detection on Opus. Detection is pattern matching, not deep reasoning.
|
||||
Sonnet is 5-10x cheaper and fast enough. Reserve Opus for the main session
|
||||
where reasoning quality matters.
|
||||
|
||||
2. **Don't block the main thread.** Sub-agents must run asynchronously. If the
|
||||
signal detector runs synchronously, the user waits 30-120 seconds for every
|
||||
message while entity detection completes. Spawn and forget. The user sees
|
||||
a response immediately.
|
||||
|
||||
3. **Cost optimization is multiplicative.** Entity detection runs on every
|
||||
single message. If you use Opus at $15/MTok for detection across 50
|
||||
messages/day, that's $3-5/day just for detection. Sonnet at $3/MTok brings
|
||||
that to $0.60-1.00/day. Over a month, the wrong model choice costs $100+
|
||||
more than necessary.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Spawn a signal detector and check the model.** Send a message and verify
|
||||
the sub-agent was spawned on Sonnet-class, not Opus. Check the model field
|
||||
in the sub-agent config or logs.
|
||||
|
||||
2. **Check cost per day.** After running for a day with sub-agent routing,
|
||||
compare total API costs against the previous day without routing. You
|
||||
should see a 50-80% reduction in total cost.
|
||||
|
||||
3. **Verify async execution.** Send a message and measure response time. The
|
||||
response should arrive in under 5 seconds. If it takes 30+ seconds, the
|
||||
signal detector is running synchronously and blocking the main thread.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
@@ -1,182 +0,0 @@
|
||||
# Upgrades and Auto-Update Notifications
|
||||
|
||||
## Goal
|
||||
|
||||
Users get notified of new GBrain features conversationally, and the agent walks them through upgrading with post-upgrade migrations that make the new version actually work.
|
||||
|
||||
## What the User Gets
|
||||
|
||||
Without this: GBrain ships updates but nobody knows. The user stays on an old
|
||||
version with stale skills and missing features. Or worse, someone runs
|
||||
`gbrain upgrade` but skips the post-upgrade steps, leaving new code with old
|
||||
agent behavior.
|
||||
|
||||
With this: the agent checks for updates daily, sells the upgrade with punchy
|
||||
benefit-focused bullets, waits for explicit permission, then runs the full
|
||||
upgrade flow including re-reading skills, running migrations, and syncing
|
||||
schema. The user gets new capabilities automatically.
|
||||
|
||||
## Implementation
|
||||
|
||||
### The Check (cron-initiated)
|
||||
|
||||
```
|
||||
check_for_update():
|
||||
result = run("gbrain check-update --json")
|
||||
|
||||
if not result.update_available:
|
||||
exit_silently() // do NOT message the user
|
||||
|
||||
// Sell the upgrade — lead with what they can DO, not what changed
|
||||
message = compose_upgrade_message(
|
||||
current: result.current_version,
|
||||
latest: result.latest_version,
|
||||
changelog: result.changelog
|
||||
)
|
||||
send_to_user(message, respect_quiet_hours=true)
|
||||
```
|
||||
|
||||
### The Upgrade Message
|
||||
|
||||
Sell the upgrade. The user should feel "hell yeah, I want that." Lead with
|
||||
what they can DO now that they couldn't before, not what files changed.
|
||||
|
||||
```
|
||||
> **GBrain v0.5.0 is available** (you're on v0.4.0)
|
||||
>
|
||||
> What's new:
|
||||
> - Your brain never falls behind. Live sync keeps the vector DB current
|
||||
> automatically, so edits show up in search within minutes
|
||||
> - New verification runbook catches silent failures before they bite you
|
||||
> - New installs set up live sync automatically. No more manual setup step
|
||||
>
|
||||
> Want me to upgrade? I'll update everything and refresh my playbook.
|
||||
>
|
||||
> (Reply **yes** to upgrade, **not now** to skip, **weekly** to check
|
||||
> less often, or **stop** to turn off update checks)
|
||||
```
|
||||
|
||||
### Handling Responses
|
||||
|
||||
| User says | Action |
|
||||
|-----------|--------|
|
||||
| yes / y / sure / ok / do it / upgrade | Run the full upgrade flow (below) |
|
||||
| not now / later / skip / snooze | Acknowledge, check again next cycle |
|
||||
| weekly | Store preference, switch cron to weekly |
|
||||
| daily | Store preference, switch cron back to daily |
|
||||
| stop / unsubscribe / no more | Disable the cron. Tell user how to resume |
|
||||
|
||||
**Never auto-upgrade.** Always wait for explicit confirmation.
|
||||
|
||||
### The Full Upgrade Flow (after user says yes)
|
||||
|
||||
```
|
||||
full_upgrade():
|
||||
// Step 1: Update the binary/package
|
||||
run("gbrain upgrade")
|
||||
|
||||
// Step 2: Re-read all updated skills
|
||||
for skill in find("skills/*/SKILL.md"):
|
||||
read_and_internalize(skill) // updated skills = better agent behavior
|
||||
|
||||
// Step 3: Re-read production reference docs
|
||||
read("docs/GBRAIN_SKILLPACK.md")
|
||||
read("docs/GBRAIN_RECOMMENDED_SCHEMA.md")
|
||||
|
||||
// Step 4: Check for version-specific migration directives
|
||||
for version in range(old_version, new_version):
|
||||
migration = find(f"skills/migrations/v{version}.md")
|
||||
if migration exists:
|
||||
read_and_execute(migration) // in order, don't skip
|
||||
|
||||
// Step 5: Schema sync — suggest new, respect declined
|
||||
state = read("~/.gbrain/update-state.json")
|
||||
for recommendation in new_schema_recommendations:
|
||||
if recommendation not in state.declined:
|
||||
suggest_to_user(recommendation)
|
||||
update(state, new_choices)
|
||||
|
||||
// Step 6: Report what changed
|
||||
summarize_to_user(actions_taken)
|
||||
```
|
||||
|
||||
### Migration Files
|
||||
|
||||
Migration files live at `skills/migrations/vX.Y.Z.md`. They contain agent
|
||||
instructions (not scripts) for post-upgrade actions that make the new version
|
||||
work for existing users. Example: v0.5.0 migration sets up live sync and
|
||||
runs the verification runbook.
|
||||
|
||||
The agent reads migration files in version order and executes them step by
|
||||
step. Without migrations, the agent has new code but the user's environment
|
||||
hasn't changed.
|
||||
|
||||
### Cron Registration
|
||||
|
||||
```
|
||||
Name: gbrain-update-check
|
||||
Default schedule: 0 9 * * * (daily 9 AM)
|
||||
Weekly schedule: 0 9 * * 1 (Monday 9 AM)
|
||||
Prompt: "Run gbrain check-update --json. If update_available is true,
|
||||
summarize the changelog and message me asking if I'd like to upgrade.
|
||||
If false, stay silent."
|
||||
```
|
||||
|
||||
### Frequency Preferences
|
||||
|
||||
Default: daily. Store in agent memory as `gbrain_update_frequency: daily|weekly|off`.
|
||||
Also persist in `~/.gbrain/update-state.json` so it survives agent context resets.
|
||||
|
||||
### Standalone Skillpack Users
|
||||
|
||||
If you loaded this SKILLPACK directly (copied or read from GitHub) without
|
||||
installing gbrain, you can still stay current. Both GBRAIN_SKILLPACK.md and
|
||||
GBRAIN_RECOMMENDED_SCHEMA.md have version markers:
|
||||
|
||||
```bash
|
||||
curl -s https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_SKILLPACK.md | head -1
|
||||
# Returns: <!-- skillpack-version: X.Y.Z -->
|
||||
```
|
||||
|
||||
If the remote version is newer, fetch the full file and replace your local
|
||||
copy. Set up a weekly cron to check automatically.
|
||||
|
||||
## Tricky Spots
|
||||
|
||||
1. **Never auto-install.** The upgrade must always wait for the user's explicit
|
||||
"yes." Even if the cron detects an update at 9 AM and the changelog looks
|
||||
great, the agent messages the user and waits. Auto-installing can break
|
||||
workflows, introduce breaking changes, or interrupt work in progress.
|
||||
|
||||
2. **Migration files are agent instructions, not scripts.** They tell the agent
|
||||
what to do step by step in plain language. They are NOT bash scripts to
|
||||
execute blindly. The agent reads them, understands the context, and adapts
|
||||
to the user's specific environment (e.g., skip a step if the user already
|
||||
has live sync configured).
|
||||
|
||||
3. **check-update should run on a daily cron.** Don't rely on the user
|
||||
remembering to check for updates. The cron runs `gbrain check-update --json`
|
||||
daily at 9 AM (respecting quiet hours). If there's nothing new, it stays
|
||||
completely silent. The user only hears about updates when there IS something
|
||||
worth upgrading to.
|
||||
|
||||
## How to Verify
|
||||
|
||||
1. **Run check-update and verify detection.** Execute
|
||||
`gbrain check-update --json`. Verify it returns the current version and
|
||||
correctly reports whether an update is available. If `update_available`
|
||||
is false, verify the version matches the latest release on GitHub.
|
||||
|
||||
2. **Verify migration files are readable.** List `skills/migrations/` and
|
||||
check that each file follows the naming convention `vX.Y.Z.md`. Open one
|
||||
and verify it contains step-by-step agent instructions, not raw scripts.
|
||||
The agent should be able to read and execute each step.
|
||||
|
||||
3. **Test the full upgrade flow end-to-end.** If an update is available, say
|
||||
"yes" and watch the agent execute the full flow: upgrade, re-read skills,
|
||||
run migrations, sync schema, report. Verify each step completes and the
|
||||
agent reports what changed.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md).*
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 220 KiB |
@@ -1,119 +0,0 @@
|
||||
# Getting Data Into Your Brain
|
||||
|
||||
GBrain is the retrieval layer. But retrieval is only as good as what you put in.
|
||||
This directory covers how to get data flowing into your brain automatically.
|
||||
|
||||
## How Data Flows In
|
||||
|
||||
```
|
||||
Signal arrives (phone call, email, tweet, calendar event)
|
||||
↓
|
||||
Collector captures it (deterministic code, reliable)
|
||||
↓
|
||||
Agent analyzes it (LLM, judgment, entity detection)
|
||||
↓
|
||||
Brain pages created/updated (compiled truth + timeline)
|
||||
↓
|
||||
GBrain indexes it (chunking, embedding, search-ready)
|
||||
↓
|
||||
Next query is smarter (the compounding effect)
|
||||
```
|
||||
|
||||
## Available Integrations
|
||||
|
||||
### Self-Installing Recipes
|
||||
|
||||
These are integration recipes your agent can set up for you. Run
|
||||
`gbrain integrations` to see what's available and their status.
|
||||
|
||||
| Recipe | Category | Requires | What It Does | Setup Time |
|
||||
|--------|----------|----------|-------------|------------|
|
||||
| [ngrok-tunnel](../../recipes/ngrok-tunnel.md) | Infra | — | Fixed public URL for MCP + voice ($8/mo) | 10 min |
|
||||
| [credential-gateway](../../recipes/credential-gateway.md) | Infra | — | Gmail + Calendar access (ClawVisor or Google OAuth) | 15 min |
|
||||
| [voice-to-brain](../../recipes/twilio-voice-brain.md) | Sense | ngrok-tunnel | Phone calls create brain pages via Twilio + OpenAI Realtime | 30 min |
|
||||
| [email-to-brain](../../recipes/email-to-brain.md) | Sense | credential-gateway | Gmail messages flow into entity pages via deterministic collector | 20 min |
|
||||
| [x-to-brain](../../recipes/x-to-brain.md) | Sense | — | Twitter timeline, mentions, keyword monitoring with deletion detection | 15 min |
|
||||
| [calendar-to-brain](../../recipes/calendar-to-brain.md) | Sense | credential-gateway | Google Calendar events become searchable daily brain pages | 20 min |
|
||||
| [meeting-sync](../../recipes/meeting-sync.md) | Sense | — | Circleback meeting transcripts auto-import with attendee propagation | 15 min |
|
||||
|
||||
### Manual Integration Guides
|
||||
|
||||
These require manual setup (no self-installing recipe yet):
|
||||
|
||||
| Guide | What It Does |
|
||||
|-------|-------------|
|
||||
| [Credential Gateway](credential-gateway.md) | Set up ClawVisor or Hermes for Gmail, Calendar, Contacts access |
|
||||
| [Meeting & Call Webhooks](meeting-webhooks.md) | Circleback meeting transcripts + Quo/OpenPhone SMS/calls |
|
||||
|
||||
## How to Read a Recipe
|
||||
|
||||
Integration recipes are markdown files with YAML frontmatter. Your agent reads
|
||||
the recipe and walks you through setup.
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: voice-to-brain # unique identifier
|
||||
name: Voice-to-Brain # human-readable name
|
||||
version: 0.7.0 # recipe version
|
||||
description: Phone calls... # what it does
|
||||
category: sense # sense (data input) or reflex (automated response)
|
||||
requires: [] # other recipes that must be set up first
|
||||
secrets: # API keys and credentials needed
|
||||
- name: TWILIO_ACCOUNT_SID
|
||||
description: Twilio account SID
|
||||
where: https://console.twilio.com # exact URL to get this key
|
||||
health_checks: # typed DSL to verify the integration is working
|
||||
- type: http
|
||||
url: "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json"
|
||||
auth: basic
|
||||
auth_user: "$TWILIO_ACCOUNT_SID"
|
||||
auth_token: "$TWILIO_AUTH_TOKEN"
|
||||
label: "Twilio account"
|
||||
setup_time: 30 min # estimated time to complete setup
|
||||
---
|
||||
|
||||
[Setup instructions the agent follows step by step...]
|
||||
```
|
||||
|
||||
**The recipe IS the installer.** Your agent (OpenClaw, Hermes, Claude Code) reads
|
||||
the markdown body and executes the setup steps. It asks you for API keys, validates
|
||||
each one, configures the integration, and runs a smoke test.
|
||||
|
||||
### Recipe trust boundary
|
||||
|
||||
Only recipes shipped inside the gbrain package itself (the `recipes/` directory in
|
||||
a source install, or the global install copy) are trusted. Recipes discovered at
|
||||
runtime from `$GBRAIN_RECIPES_DIR` or a cwd-local `./recipes/` are marked untrusted:
|
||||
they cannot run `command` health checks, cannot run `http` health checks (SSRF
|
||||
defense), and cannot use the deprecated string health_check form. Untrusted recipes
|
||||
can still use `env_exists` and `any_of` compositions. To ship a recipe that runs
|
||||
live checks, contribute it upstream so it becomes package-bundled.
|
||||
|
||||
## The Deterministic Collector Pattern
|
||||
|
||||
When an LLM keeps failing at a mechanical task despite repeated prompt fixes,
|
||||
stop fighting the LLM. Move the mechanical work to code.
|
||||
|
||||
**Code for data. LLMs for judgment.**
|
||||
|
||||
- Email collection: code pulls emails with baked-in links (100% reliable).
|
||||
LLM reads the digest, classifies, enriches brain entries (judgment).
|
||||
- Tweet collection: code pulls timeline, detects deletions, tracks engagement
|
||||
(deterministic). LLM extracts entities, writes brain updates (judgment).
|
||||
- Calendar sync: code pulls events and attendees (deterministic). LLM enriches
|
||||
attendee brain pages (judgment).
|
||||
|
||||
This pattern prevents the "LLM forgot the links" failure mode. Mechanical work
|
||||
must be 100% reliable. Judgment work is where LLMs shine.
|
||||
|
||||
See [Deterministic Collectors](../guides/deterministic-collectors.md) for the
|
||||
full pattern.
|
||||
|
||||
## Architecture
|
||||
|
||||
For details on the shared infrastructure that all integrations build on
|
||||
(import pipeline, chunking, embedding, search), see the
|
||||
[Infrastructure Layer](../architecture/infra-layer.md).
|
||||
|
||||
For the philosophy behind thin harness + fat skills, see
|
||||
[Thin Harness, Fat Skills](../ethos/THIN_HARNESS_FAT_SKILLS.md).
|
||||
@@ -1,52 +0,0 @@
|
||||
# Credential Gateway (ClawVisor / Hermes)
|
||||
|
||||
|
||||
Three integrations that make the agent real. Without these, the brain is a static
|
||||
database. With them, it's alive.
|
||||
|
||||
### 14a. Credential Gateway (ClawVisor / Hermes Gateway)
|
||||
|
||||
The EA workflow needs Gmail, Calendar, Contacts, and messaging access. The agent
|
||||
should never hold API keys directly. Use a credential gateway that enforces policies
|
||||
and injects credentials at request time.
|
||||
|
||||
**OpenClaw: ClawVisor.** [ClawVisor](https://clawvisor.com) is a credential vaulting
|
||||
and authorization gateway with task-scoped authorization.
|
||||
|
||||
**Services:** Gmail (list, read, send, draft), Google Calendar (CRUD), Google Drive
|
||||
(list, search, read), Google Contacts (list, search), Apple iMessage (list, read,
|
||||
search, send), GitHub, Slack.
|
||||
|
||||
**Task-scoped authorization:** Every request must include a `task_id` from an approved
|
||||
standing task. Tasks declare: purpose (verbose, 2-3 sentences), authorized actions with
|
||||
expected use patterns, auto-execute flag, lifetime (standing vs ephemeral).
|
||||
|
||||
**Why this matters for GBrain:** The EA workflow needs Gmail (sender lookup before
|
||||
triage), Calendar (meeting prep, attendee pages), Contacts (enrichment trigger), and
|
||||
iMessage (direct instructions). ClawVisor gives the agent access without giving it
|
||||
raw credentials.
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Create agent in ClawVisor dashboard, copy agent token
|
||||
2. Set `CLAWVISOR_URL` and `CLAWVISOR_AGENT_TOKEN` in env
|
||||
3. Activate services (Google, iMessage, etc.) in the dashboard
|
||||
4. Create standing tasks with expansive scopes (narrow purposes cause false blocks)
|
||||
5. Store standing task IDs in agent memory for reuse
|
||||
|
||||
**Critical scoping rule:** Be expansive in task purposes. "Full executive assistant
|
||||
email management including inbox triage, searching by any criteria, reading emails,
|
||||
tracking threads" works. "Email triage" gets rejected. The intent verification model
|
||||
uses the purpose to judge whether each request is consistent -- if your purpose is
|
||||
narrow, legitimate requests fail verification.
|
||||
|
||||
**Hermes Agent: Built-in gateway.** Hermes has multi-platform messaging (Telegram,
|
||||
Discord, Slack, WhatsApp, Signal, Email) and tool access built into its gateway. Use
|
||||
`config.yaml` to configure API credentials. The gateway daemon manages connections
|
||||
and routes webhooks to agent sessions. For Google services, configure OAuth credentials
|
||||
in the gateway config. Hermes's scheduled automations can run the same EA workflows
|
||||
(email triage, calendar prep, contact enrichment) through the gateway's tool system.
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md). See also: [Getting Data In](README.md)*
|
||||
@@ -1,63 +0,0 @@
|
||||
# Meeting & Call Webhooks
|
||||
|
||||
### 14b. Circleback -- Meeting Ingestion via Webhooks
|
||||
|
||||
[Circleback](https://circleback.ai) records meetings, generates transcripts with
|
||||
speaker diarization, and fires webhooks on completion.
|
||||
|
||||
**Webhook setup:**
|
||||
|
||||
1. In Circleback dashboard -> Automations -> add webhook
|
||||
2. URL: `{your_agent_gateway}/hooks/circleback-meetings`
|
||||
3. Circleback provides a signing secret for HMAC-SHA256 signature verification
|
||||
4. Store the signing secret in your webhook transform for verification
|
||||
|
||||
**Webhook payload:** Meeting JSON with id, name, attendees, notes, action items, full
|
||||
transcript, calendar event context.
|
||||
|
||||
**Signature verification:** Header `X-Circleback-Signature` contains `sha256=<hex>`.
|
||||
Verify with `HMAC-SHA256(body, signing_secret)`. Reject unverified webhooks.
|
||||
|
||||
**OAuth for API access:** Circleback uses dynamic client registration (OAuth 2.0).
|
||||
Access tokens expire in ~24h, auto-refresh via refresh token. Store credentials in
|
||||
agent memory.
|
||||
|
||||
**Flow:** Webhook fires -> transform validates signature + normalizes -> agent wakes ->
|
||||
pulls full transcript via API -> creates brain meeting page -> propagates to entity
|
||||
pages -> commits to brain repo -> `gbrain sync`.
|
||||
|
||||
### 14c. Quo (OpenPhone) -- SMS and Call Integration
|
||||
|
||||
[Quo](https://openphone.com) (formerly OpenPhone) provides business phone numbers with
|
||||
SMS, calls, voicemail, and AI transcripts.
|
||||
|
||||
**Webhook setup:**
|
||||
|
||||
1. In Quo dashboard -> Integrations -> Webhooks
|
||||
2. Register webhooks for: `message.received`, `call.completed`, `call.summary.completed`, `call.transcript.completed`
|
||||
3. Point all to: `{your_agent_gateway}/hooks/quo-events`
|
||||
4. Store registered webhook IDs in agent memory
|
||||
|
||||
**How inbound texts work:**
|
||||
|
||||
- Webhook fires with sender phone, message text, conversation context
|
||||
- Agent looks up sender in brain by phone number
|
||||
- Surfaces to user's messaging platform with sender identity + brain context
|
||||
- Drafts reply for approval (never auto-replies without explicit permission)
|
||||
|
||||
**How inbound calls work:**
|
||||
|
||||
- `call.completed` fires -> if duration > 30s, fetch transcript + AI summary via API
|
||||
- Ingest to brain (meeting-style page at `meetings/`)
|
||||
- Update relevant people and company pages
|
||||
|
||||
**API auth:** Bare API key in `Authorization` header (no Bearer prefix).
|
||||
|
||||
**Key endpoints:** `POST /v1/messages` (send SMS), `GET /v1/messages` (list),
|
||||
`GET /v1/call-transcripts/{id}`, `GET /v1/conversations`.
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
*Part of the [GBrain Skillpack](../GBRAIN_SKILLPACK.md). See also: [Getting Data In](README.md)*
|
||||
@@ -1,66 +0,0 @@
|
||||
# Reliability repair (v0.12.2)
|
||||
|
||||
If you ran v0.12.0 on real Postgres or Supabase, two bugs may have corrupted
|
||||
data already in your brain. v0.12.1 fixed the code going forward.
|
||||
v0.12.2 adds detection in `gbrain doctor` and a standalone `gbrain repair-jsonb`
|
||||
command for the mechanically fixable class. PGLite users are not affected.
|
||||
|
||||
## What got corrupted
|
||||
|
||||
**JSONB double-encode.** Four write sites used
|
||||
`${JSON.stringify(x)}::jsonb` with postgres.js, which stored a JSONB
|
||||
*string literal* instead of an object. `frontmatter ->> 'key'` returns NULL;
|
||||
GIN indexes are ineffective. Affected: `pages.frontmatter`,
|
||||
`raw_data.data`, `ingest_log.pages_updated`, `files.metadata`.
|
||||
|
||||
**Markdown body truncation.** `splitBody()` treated `---` horizontal rules
|
||||
as a body/timeline delimiter, dropping everything after the first rule.
|
||||
Wiki-style pages with multiple `##`/`###` sections lost the bulk of their
|
||||
content at import time.
|
||||
|
||||
## Detect
|
||||
|
||||
```
|
||||
gbrain doctor
|
||||
```
|
||||
|
||||
Reports two new checks:
|
||||
|
||||
- `jsonb_integrity` — counts double-encoded rows per table and points you
|
||||
at `gbrain repair-jsonb`.
|
||||
- `markdown_body_completeness` — heuristic for pages whose `compiled_truth`
|
||||
is suspiciously short compared to `raw_data.data ->> 'content'`.
|
||||
|
||||
## Repair
|
||||
|
||||
For JSONB (mechanically fixable):
|
||||
|
||||
```
|
||||
gbrain repair-jsonb
|
||||
```
|
||||
|
||||
Runs `UPDATE <table> SET <col> = (<col>#>>'{}')::jsonb WHERE jsonb_typeof(<col>) = 'string'`
|
||||
across every affected column. Idempotent. Second run reports 0 rows. Use
|
||||
`--dry-run` to preview, `--json` for structured output. The `v0_12_2`
|
||||
migration runs this automatically on `gbrain upgrade`.
|
||||
|
||||
For truncated markdown bodies (source-dependent):
|
||||
|
||||
```
|
||||
gbrain sync --force
|
||||
# or per-page
|
||||
gbrain import <slug> --force
|
||||
```
|
||||
|
||||
v0.12.2 cannot recover content that was already lost if you no longer have
|
||||
the source markdown file. `gbrain doctor` tells you which pages look short;
|
||||
you decide whether to re-import from source or accept the truncation.
|
||||
|
||||
## Verify
|
||||
|
||||
```
|
||||
gbrain doctor
|
||||
```
|
||||
|
||||
All four `jsonb_integrity` rows should read zero. `markdown_body_completeness`
|
||||
should match your expectations for the corpus.
|
||||
@@ -1,64 +0,0 @@
|
||||
# Remote MCP Deployment Options
|
||||
|
||||
GBrain's MCP server runs via `gbrain serve` (stdio transport). To make it
|
||||
accessible from other devices and AI clients, you need an HTTP wrapper and
|
||||
a public tunnel. Here are your options.
|
||||
|
||||
## ngrok (recommended)
|
||||
|
||||
[ngrok](https://ngrok.com) provides instant public tunnels. The Hobby tier
|
||||
($8/mo) gives you a fixed domain that never changes.
|
||||
|
||||
```bash
|
||||
# 1. Install ngrok
|
||||
brew install ngrok
|
||||
|
||||
# 2. Start your MCP server (behind an HTTP wrapper)
|
||||
# See docs/mcp/DEPLOY.md for the server setup
|
||||
|
||||
# 3. Expose via ngrok
|
||||
ngrok http 8787 --url your-brain.ngrok.app
|
||||
```
|
||||
|
||||
See the [ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md) for full setup
|
||||
including auth token configuration and fixed domain setup.
|
||||
|
||||
## Tailscale Funnel
|
||||
|
||||
[Tailscale Funnel](https://tailscale.com/kb/1223/tailscale-funnel) gives you
|
||||
a permanent public HTTPS URL with automatic TLS. Free tier available. Best for
|
||||
private networks where you control both endpoints.
|
||||
|
||||
```bash
|
||||
# 1. Install Tailscale
|
||||
brew install tailscale
|
||||
|
||||
# 2. Expose your MCP server
|
||||
tailscale funnel 8787
|
||||
# Your brain is now at https://your-machine.ts.net
|
||||
```
|
||||
|
||||
## Fly.io / Railway (always-on)
|
||||
|
||||
For production deployments that need to run 24/7 without your machine:
|
||||
|
||||
- **Fly.io:** $5-10/mo, global edge, `fly deploy`
|
||||
- **Railway:** $5/mo, git push deploy
|
||||
|
||||
Both run Bun natively. No bundling, no Deno, no cold start, no timeout limits.
|
||||
|
||||
## Comparison
|
||||
|
||||
| | ngrok | Tailscale | Fly.io/Railway |
|
||||
|--|---|---|---|
|
||||
| Cost | $8/mo (Hobby) | Free | $5-10/mo |
|
||||
| Fixed URL | Yes (Hobby) | Yes | Yes |
|
||||
| Works when laptop is off | No | No | Yes |
|
||||
| Cold start | None | None | None |
|
||||
| Timeout limits | None | None | None |
|
||||
| All 30 operations | Yes | Yes | Yes |
|
||||
| Setup time | 5 min | 10 min | 15 min |
|
||||
|
||||
**Note:** `gbrain serve --http` (built-in HTTP transport) is planned but not yet
|
||||
implemented. Currently, remote MCP requires a custom HTTP wrapper around `gbrain serve`.
|
||||
See [DEPLOY.md](DEPLOY.md) for details.
|
||||
@@ -1,40 +0,0 @@
|
||||
# Connect GBrain to Claude Code
|
||||
|
||||
## Option 1: Local (recommended, zero server needed)
|
||||
|
||||
```bash
|
||||
claude mcp add gbrain -- gbrain serve
|
||||
```
|
||||
|
||||
That's it. Claude Code spawns `gbrain serve` as a stdio subprocess. No server, no
|
||||
tunnel, no token needed. Works with both PGLite and Supabase engines.
|
||||
|
||||
## Option 2: Remote (access from any machine)
|
||||
|
||||
If you have GBrain running on a server with a public tunnel (see
|
||||
[ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md)):
|
||||
|
||||
```bash
|
||||
claude mcp add gbrain -t http \
|
||||
https://YOUR-DOMAIN.ngrok.app/mcp \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
Replace `YOUR-DOMAIN` with your ngrok domain and `YOUR_TOKEN` with a token
|
||||
from `bun run src/commands/auth.ts create "claude-code"`.
|
||||
|
||||
## Verify
|
||||
|
||||
In Claude Code, try:
|
||||
|
||||
```
|
||||
search for [any topic in your brain]
|
||||
```
|
||||
|
||||
You should see results from your GBrain knowledge base.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
claude mcp remove gbrain
|
||||
```
|
||||
@@ -1,33 +0,0 @@
|
||||
# Connect GBrain to Claude Cowork
|
||||
|
||||
Two ways to get GBrain into Cowork sessions:
|
||||
|
||||
## Option 1: Remote (via self-hosted server + tunnel)
|
||||
|
||||
For Team/Enterprise plans, an org Owner adds the connector:
|
||||
|
||||
1. Go to **Organization Settings > Connectors**
|
||||
2. Add a new connector with the MCP server URL:
|
||||
```
|
||||
https://YOUR-DOMAIN.ngrok.app/mcp
|
||||
```
|
||||
3. Add Bearer token authentication in Advanced Settings
|
||||
(create one with `bun run src/commands/auth.ts create "cowork"`)
|
||||
4. Save
|
||||
|
||||
Note: Cowork connects from Anthropic's cloud, not your device. Your server
|
||||
must be publicly reachable (ngrok, Tailscale Funnel, or cloud-hosted).
|
||||
|
||||
## Option 2: Local Bridge (via Claude Desktop)
|
||||
|
||||
If you already have GBrain configured in Claude Desktop (via `gbrain serve`
|
||||
stdio or a remote integration), Cowork gets access automatically. Claude
|
||||
Desktop bridges local MCP servers into Cowork via its SDK layer.
|
||||
|
||||
This means: if `gbrain serve` is running and configured in Claude Desktop,
|
||||
you don't need a separate server for Cowork.
|
||||
|
||||
## Which to use?
|
||||
|
||||
- **Remote server:** works even when your laptop is closed, available to all org members
|
||||
- **Local Bridge:** zero extra setup if Claude Desktop already has GBrain, but requires your machine to be running
|
||||
@@ -1,39 +0,0 @@
|
||||
# Connect GBrain to Claude Desktop
|
||||
|
||||
**Important:** Claude Desktop does NOT connect to remote MCP servers via
|
||||
`claude_desktop_config.json`. That file only works for local stdio servers.
|
||||
Remote HTTP servers must be added through the GUI.
|
||||
|
||||
## Setup
|
||||
|
||||
1. Open Claude Desktop
|
||||
2. Go to **Settings > Integrations**
|
||||
3. Click **Add Integration** (or **Add Connector**)
|
||||
4. Enter the MCP server URL:
|
||||
```
|
||||
https://YOUR-DOMAIN.ngrok.app/mcp
|
||||
```
|
||||
Replace `YOUR-DOMAIN` with your ngrok domain (see
|
||||
[ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md) for setup).
|
||||
5. Set authentication to **Bearer Token** and paste your token
|
||||
(create one with `bun run src/commands/auth.ts create "claude-desktop"`)
|
||||
6. Save
|
||||
|
||||
## Verify
|
||||
|
||||
Start a new conversation and try:
|
||||
|
||||
```
|
||||
Search my brain for [any topic]
|
||||
```
|
||||
|
||||
Claude Desktop will use your GBrain tools automatically.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
**Using claude_desktop_config.json for remote servers** — this silently fails
|
||||
with no error message. The JSON config only works for local stdio MCP servers.
|
||||
Remote HTTP servers must be added via Settings > Integrations in the GUI.
|
||||
|
||||
**Using the wrong URL** — make sure the URL ends with `/mcp` (not `/health`
|
||||
or just the base domain).
|
||||
@@ -1,122 +0,0 @@
|
||||
# Deploy GBrain Remote MCP Server
|
||||
|
||||
Access your brain from any device, any AI client. GBrain's MCP server runs locally
|
||||
via `gbrain serve` (stdio). For remote access, wrap it in an HTTP server behind a
|
||||
public tunnel.
|
||||
|
||||
## Two Paths
|
||||
|
||||
### Local (zero setup)
|
||||
|
||||
```bash
|
||||
gbrain serve
|
||||
```
|
||||
|
||||
Works with Claude Code, Cursor, Windsurf, and any MCP client that supports stdio.
|
||||
No server, no tunnel, no token needed.
|
||||
|
||||
### Remote (any device, any AI client)
|
||||
|
||||
```
|
||||
Your AI client (Claude Desktop, Perplexity, etc.)
|
||||
→ ngrok tunnel (https://YOUR-DOMAIN.ngrok.app)
|
||||
→ Your HTTP server (wraps gbrain serve)
|
||||
→ Supabase Postgres (via pooler connection string)
|
||||
```
|
||||
|
||||
This requires:
|
||||
1. A machine running `gbrain serve` behind an HTTP wrapper
|
||||
2. A public tunnel (ngrok, Tailscale, or cloud host)
|
||||
3. Bearer token auth for security
|
||||
|
||||
## Remote Setup
|
||||
|
||||
### 1. Set up the tunnel
|
||||
|
||||
See the [ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md) for full setup.
|
||||
Quick version:
|
||||
|
||||
```bash
|
||||
brew install ngrok
|
||||
ngrok config add-authtoken YOUR_TOKEN
|
||||
ngrok http 8787 --url your-brain.ngrok.app # Hobby tier for fixed domain
|
||||
```
|
||||
|
||||
### 2. Create access tokens
|
||||
|
||||
```bash
|
||||
# Create a token for each client
|
||||
bun run src/commands/auth.ts create "claude-desktop"
|
||||
|
||||
# List all tokens
|
||||
bun run src/commands/auth.ts list
|
||||
|
||||
# Revoke a token
|
||||
bun run src/commands/auth.ts revoke "claude-desktop"
|
||||
```
|
||||
|
||||
Tokens are per-client. Create one for each device/app. Revoke individually
|
||||
if compromised. Tokens are stored SHA-256 hashed in your database.
|
||||
|
||||
### 3. Connect your AI client
|
||||
|
||||
- **Claude Code:** [setup guide](CLAUDE_CODE.md)
|
||||
- **Claude Desktop:** [setup guide](CLAUDE_DESKTOP.md) (must use GUI, not JSON config)
|
||||
- **Claude Cowork:** [setup guide](CLAUDE_COWORK.md)
|
||||
- **Perplexity:** [setup guide](PERPLEXITY.md)
|
||||
|
||||
### 4. Verify
|
||||
|
||||
```bash
|
||||
bun run src/commands/auth.ts test \
|
||||
https://YOUR-DOMAIN.ngrok.app/mcp \
|
||||
--token YOUR_TOKEN
|
||||
```
|
||||
|
||||
## Operations
|
||||
|
||||
All 30 GBrain operations are available remotely, including `sync_brain` and
|
||||
`file_upload` (no timeout limits with self-hosted server).
|
||||
|
||||
**Security note on `file_upload`:** remote MCP callers are confined to the working
|
||||
directory where `gbrain serve` was launched. Symlinks, `..` traversal, and absolute
|
||||
paths outside cwd are rejected. Page slugs and filenames are allowlist-validated
|
||||
(alphanumeric + hyphens; no control chars, RTL overrides, or backslashes). Local
|
||||
CLI callers (`gbrain file upload ...`) keep unrestricted filesystem access since
|
||||
the user owns the machine.
|
||||
|
||||
## Deployment Options
|
||||
|
||||
See [ALTERNATIVES.md](ALTERNATIVES.md) for a comparison of ngrok, Tailscale
|
||||
Funnel, and cloud hosts (Fly.io, Railway).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"missing_auth" error**
|
||||
Include the Authorization header: `Authorization: Bearer YOUR_TOKEN`
|
||||
|
||||
**"invalid_token" error**
|
||||
Run `bun run src/commands/auth.ts list` to see active tokens.
|
||||
|
||||
**"service_unavailable" error**
|
||||
Database connection failed. Check your Supabase dashboard for outages.
|
||||
|
||||
**Claude Desktop doesn't connect**
|
||||
Remote servers must be added via Settings > Integrations, NOT
|
||||
`claude_desktop_config.json`. See [CLAUDE_DESKTOP.md](CLAUDE_DESKTOP.md).
|
||||
|
||||
## Expected Latencies
|
||||
|
||||
| Operation | Typical Latency | Notes |
|
||||
|-----------|----------------|-------|
|
||||
| get_page | < 100ms | Single DB query |
|
||||
| list_pages | < 200ms | DB query with filters |
|
||||
| search (keyword) | 100-300ms | Full-text search |
|
||||
| query (hybrid) | 1-3s | Embedding + vector + keyword + RRF |
|
||||
| put_page | 100-500ms | Write + trigger search_vector update |
|
||||
| get_stats | < 100ms | Aggregate query |
|
||||
|
||||
**Note:** `gbrain serve --http` (built-in HTTP transport) is planned but not yet
|
||||
implemented. Currently, remote MCP requires a custom HTTP wrapper. See the
|
||||
production deployment pattern in the [voice recipe](../../recipes/twilio-voice-brain.md)
|
||||
for a reference implementation.
|
||||
@@ -1,31 +0,0 @@
|
||||
# Connect GBrain to Perplexity Computer
|
||||
|
||||
Perplexity Computer supports remote MCP servers with bearer token authentication.
|
||||
|
||||
## Setup
|
||||
|
||||
1. Open Perplexity (requires Pro subscription)
|
||||
2. Go to **Settings > Connectors** (or **MCP Servers**)
|
||||
3. Add a new remote connector:
|
||||
- **URL:** `https://YOUR-DOMAIN.ngrok.app/mcp`
|
||||
- **Authentication:** API Key / Bearer Token
|
||||
- **Token:** your GBrain access token
|
||||
(create one with `bun run src/commands/auth.ts create "perplexity"`)
|
||||
4. Save
|
||||
|
||||
Replace `YOUR-DOMAIN` with your ngrok domain (see
|
||||
[ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md) for setup).
|
||||
|
||||
## Verify
|
||||
|
||||
In a Perplexity conversation, ask it to use your brain:
|
||||
|
||||
```
|
||||
Use my GBrain to search for [topic]
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Perplexity Computer is available to Pro subscribers
|
||||
- Both the Perplexity Mac app and web version support MCP connectors
|
||||
- The Mac app also supports local MCP servers if you prefer `gbrain serve` (stdio)
|
||||
@@ -1,13 +0,0 @@
|
||||
{
|
||||
"generated_at": "2026-04-18T04:13:16.027Z",
|
||||
"model": "claude-opus-4-5",
|
||||
"pricing": {
|
||||
"input_per_m": 15,
|
||||
"output_per_m": 75
|
||||
},
|
||||
"inputTokens": 18359,
|
||||
"outputTokens": 38228,
|
||||
"costUsd": 3.1424849999999998,
|
||||
"calls": 49,
|
||||
"files_total": 240
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"slug": "companies/accel-5",
|
||||
"type": "company",
|
||||
"title": "Accel - Global Venture Capital Firm",
|
||||
"compiled_truth": "Accel is one of the most established venture capital firms in the world, with a track record spanning over four decades. Founded in 1983, the firm has evolved from a Silicon Valley stalwart into a truly global operation with offices in Palo Alto, London, and Bangalore. They've backed some of the most consequential technology companies of the past two decades, including Facebook, Spotify, Slack, and Dropbox.\n\nThe firm operates across multiple stages, though they're perhaps best known for their Series A and Series B investments. Accel manages billions in assets across various funds, with recent vintages exceeding $3 billion for their US and Europe-focused vehicles. Their investment thesis tends to favor founders building category-defining companies in enterprise software, consumer tech, fintech, and increasingly, AI infrastructure.\n\nAccel's partnership model emphasizes deep sector expertise. Partners like Sonali De Rycker have built formidable reputations in European fintech, while others focus on developer tools or consumer applications. The firm has been notably active in the generative AI wave, making early bets on companies building foundational models and application layers. They've developed strong relationships with accelerators like [Y Combinator](companies/y-combinator) and often co-invest alongside firms such as [Andreessen Horowitz](companies/a16z) on competitive deals.\n\nRecent years have seen Accel double down on international expansion. Their India fund has become one of the most active institutional investors in the subcontinent, backing companies like Flipkart and Swiggy before they became household names. The London office continues to punch above its weight in European tech circles.\n\nThe firm's culture is often described as founder-friendly but rigorous. They're known for taking board seats seriously and providing operational support beyond just capital. Accel's brand carries significant weight in fundraising conversations—a term sheet from them often signals quality to follow-on investors. Critics sometimes note their portfolio can feel conservative compared to newer entrants, but longevity has its advantages. They've seen multiple market cycles and tend to maintain disciplined valuations even in frothy markets.",
|
||||
"timeline": [
|
||||
"- **2021-03-15** | Accel closes $3 billion early-stage fund, largest in firm history at the time",
|
||||
"- **2021-09-22** | Led Series B for enterprise AI startup alongside [Andreessen Horowitz](companies/a16z)",
|
||||
"- **2022-04-10** | Opens expanded London office to support growing European portfolio",
|
||||
"- **2022-11-08** | Partner Rich Wong speaks at Web Summit on enterprise software trends",
|
||||
"- **2023-02-14** | Announces $650 million India-focused fund, sixth in the region",
|
||||
"- **2023-08-30** | Leads seed round for [Y Combinator](companies/y-combinator) batch company building AI code review tools",
|
||||
"- **2024-01-19** | Accel publishes annual Euroscape report showing record European unicorn creation",
|
||||
"- **2024-06-05** | Makes significant investment in robotics startup focused on warehouse automation",
|
||||
"- **2025-02-11** | Closes latest growth fund at $4.2 billion amid competitive fundraising environment",
|
||||
"- **2025-09-03** | Hosts annual CEO summit in Portofino, bringing together 80+ portfolio founders"
|
||||
],
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/accel-5",
|
||||
"name": "Accel",
|
||||
"category": "vc",
|
||||
"industry": "venture capital"
|
||||
}
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"slug": "companies/acme-0",
|
||||
"type": "company",
|
||||
"title": "Acme",
|
||||
"compiled_truth": "Acme is a robotics startup founded in 2021 by [Mia Brown](people/mia-brown-0), who previously spent nearly a decade in industrial automation before striking out on her own. The company focuses on developing modular robotic systems for small and mid-sized warehouses—an underserved market segment that larger players have largely ignored. Their flagship product, the Acme Flex Unit, is a mobile picking robot that can be deployed in facilities without major infrastructure changes.\n\nThe startup has attracted notable backing from angel investors including [Chris Jackson](people/chris-jackson-91) and [Ian Anderson](people/ian-anderson-105), both of whom participated in the seed round closed in early 2022. Jackson in particular has been hands-on, joining several board meetings and making introductions to potential enterprise customers. Acme raised a modest $2.3M initially, deliberately staying lean while proving out the core technology.\n\nMia Brown serves as CEO and remains deeply involved in product development. She's known for an engineering-first approach to company building, often spending time on the factory floor alongside her small team. The company currently employs around 25 people, mostly engineers, operating out of a converted warehouse space in Austin. Acme has been quiet about expansion plans but insiders suggest a Series A is in the works for late 2025.\n\nThe robotics market is crowded, yet Acme has carved out a niche by targeting businesses too small for enterprise solutions but too large for manual operations alone. Early customers include regional e-commerce fulfillment centers and a few specialty food distributors. Retention has been strong, with several pilots converting to full deployments.\n\nRecent moves include a partnership with a logistics software provider to integrate Acme's robots into broader warehouse managment systems. The company also hired its first dedicated sales lead in Q1 2025, signaling a shift toward scaling comercial operations. Despite limited public visibility, Acme has built a reputation in robotics circles for reliable hardware and responsive support.",
|
||||
"timeline": "- **2021-06-15** | Acme incorporated in Delaware by [Mia Brown](people/mia-brown-0)\n- **2022-02-10** | Closed $2.3M seed round led by [Chris Jackson](people/chris-jackson-91) and [Ian Anderson](people/ian-anderson-105)\n- **2022-09-01** | First prototype of Acme Flex Unit completed\n- **2023-03-22** | Signed pilot agreement with regional fulfillment center in Texas\n- **2023-11-08** | Expanded team to 15 employees, opened Austin facility\n- **2024-04-17** | Converted three pilot customers to full commercial deployments\n- **2024-10-30** | Announced integration partnership with WarehouseOS software platform\n- **2025-01-14** | Hired first dedicated head of sales, marking commercial scale-up\n- **2025-06-02** | [Mia Brown](people/mia-brown-0) spoke at RoboTech Summit on modular automation\n- **2025-11-20** | Series A discussions reportedly underway with multiple VC firms",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/acme-0",
|
||||
"name": "Acme",
|
||||
"category": "startup",
|
||||
"industry": "robotics",
|
||||
"founded_year": 2021,
|
||||
"founders": [
|
||||
"people/mia-brown-0"
|
||||
],
|
||||
"investors": [
|
||||
"people/chris-jackson-91",
|
||||
"people/ian-anderson-105"
|
||||
],
|
||||
"employees": [
|
||||
"people/chris-smith-110"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,27 +0,0 @@
|
||||
{
|
||||
"slug": "companies/acme-labs-50",
|
||||
"type": "company",
|
||||
"title": "Acme Labs",
|
||||
"compiled_truth": "Acme Labs is a cybersecurity startup founded in 2019 by [Ian Kim](people/ian-kim-50), a serial entrepreneur with deep roots in enterprise security software. The company emerged from Kim's frustration with legacy endpoint protection tools that couldn't keep pace with modern threat vectors. Based out of Austin, Texas, Acme has grown from a three-person operation to a team of roughly 45 engineers and security researchers.\n\nThe company's flagship product is a real-time threat detection platform that uses behavioral analysis to identify anomalies before they escalate into full breaches. Unlike traditional signature-based approaches, Acme's system learns the normal patterns of network traffic and user behavior, flagging deviations that might indicate compromise. Early customers were mid-market financial services firms, though the company has since expanded into healthcare and logistics verticals.\n\nFunding came relatively early. [Helen Martinez](people/helen-martinez-87) led the seed round in late 2020, bringing not just capital but also her extensive network in enterprise software distribution. Martinez has remained closely involved, attending board meetings and occasionally making introductions to potential strategic partners. The Series A followed in 2022, though terms were not publicly disclosed.\n\nOn the advisory side, [Wendy Wilson](people/wendy-wilson-170) joined in 2021 to help shape go-to-market strategy. Wilson's backgorund in scaling B2B SaaS companies proved invaluable as Acme transitioned from founder-led sales to a more structured revenue organization. She's credited with pushing the team to focus on a narrower ICP rather than chasing every inbound lead.\n\nAcme Labs has built a reputation for technical depth. Their engineering blog regularly publishes threat research, and several team members speak at conferences like DEF CON and BSides. The culture leans scrappy—Kim is known for keeping overhead low and reinvesting heavily into R&D. Recent chatter suggests the company is exploring an AI-powered SOC assistant, though nothing has been formally anounced. Competition remains fierce from both established players and well-funded startups, but Acme's focus on mid-market customers gives them a defensible niche.",
|
||||
"timeline": "- **2019-03-12** | Acme Labs incorporated in Delaware; [Ian Kim](people/ian-kim-50) begins building initial prototype\n- **2019-11-04** | First paying customer signed — a regional credit union in Texas\n- **2020-09-18** | Seed round closed with [Helen Martinez](people/helen-martinez-87) leading the investment\n- **2021-02-22** | [Wendy Wilson](people/wendy-wilson-170) joins as strategic advisor\n- **2021-08-30** | Acme releases v2.0 of threat detection platform with behavioral analytics engine\n- **2022-04-15** | Series A funding completed; team expands to 30 employees\n- **2023-06-09** | Ian Kim delivers keynote at RSA Conference on zero-trust architecture\n- **2024-01-17** | Partnership announced with major SIEM vendor for native integration\n- **2024-11-03** | Acme Labs crosses $10M ARR milestone\n- **2025-07-21** | Internal demo of AI-powered SOC assistant shown to select customers",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/acme-labs-50",
|
||||
"name": "Acme Labs",
|
||||
"category": "startup",
|
||||
"industry": "cybersecurity",
|
||||
"founded_year": 2019,
|
||||
"founders": [
|
||||
"people/ian-kim-50"
|
||||
],
|
||||
"investors": [
|
||||
"people/helen-martinez-87"
|
||||
],
|
||||
"employees": [
|
||||
"people/vera-martinez-160"
|
||||
],
|
||||
"advisors": [
|
||||
"people/wendy-wilson-170"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,15 +0,0 @@
|
||||
{
|
||||
"slug": "companies/amazon-3",
|
||||
"type": "company",
|
||||
"title": "Amazon - Cybersecurity Acquirer",
|
||||
"compiled_truth": "Amazon, founded in 1998, has evolved far beyond its origins as an online bookstore to become one of the most formidable players in the technology sector. While most know the company for its e-commerce dominance and AWS cloud infrastructure, Amazon has quietly built a substantial presence in cybersecurity through strategic acquisitions and internal development.\n\nThe company's approach to cybersecurity M&A has been methodical and often under the radar. Rather than making splashy billion-dollar deals that attract media attention, Amazon tends to acquire smaller, specialized firms that can be integrated into its existing AWS security stack. This strategy allows them to enhance offerings like AWS Shield, GuardDuty, and Security Hub without the integration headaches that plague larger mergers.\n\nAmazon's cybersecurity ambitions are driven partly by necesity—protecting its massive cloud infrastructure and the millions of businesses that depend on it requires constant innovation. The company processes an astronomical volume of security events daily, giving it unique datasets for training threat detection models. Some industry observers beleive this data advantage makes Amazon a sleeping giant in the security space.\n\nRecent moves suggest the company is getting more aggressive. They've been spotted at major security conferences with larger acquisition teams, and rumors persist about interest in several endpoint detection startups. The hiring of former NSA and CISA officials into senior AWS security roles signals a maturation of their strategy.\n\nCompetition with [Microsoft](companies/microsoft) in the cloud security space has intensified, with both giants racing to offer comprehensive security platforms that reduce customers' need for third-party tools. Amazon's relationship with specialized security vendors is complicated—they partner with many through the AWS Marketplace while simultaneously building competing capabilities.\n\nThe firm maintains close ties with government contractors and has pursued FedRAMP certifications aggressively. Their work with [Palantir](companies/palantir) on certain government cloud initiatives demonstrates Amazon's willingness to collaborate when strategic interests align, though the relationship has had its tense moments over competing contract bids.",
|
||||
"timeline": "- **2021-03-15** | Amazon acquires small threat intelligence startup for undisclosed sum, team absorbed into AWS Security division\n- **2021-09-22** | Launched AWS Security Lake at re:Invent, consolidating security data management capabilities\n- **2022-04-08** | Hired former CISA deputy director to lead government security initiatives\n- **2022-11-30** | Announced expanded partnership with [Microsoft](companies/microsoft) on cross-cloud security standards, surprising industry observers\n- **2023-06-14** | Acquisition of Israeli-based API security firm closes, adding to AppSec portfolio\n- **2023-12-01** | AWS Security Hub surpasses 50,000 enterprise customers milestone\n- **2024-05-19** | Internal memo leaked showing renewed focus on endpoint security acquisitions\n- **2024-10-03** | Joint threat intelligence sharing agreement signed with [Palantir](companies/palantir) for federal contracts\n- **2025-02-28** | Rumored in late-stage talks with two identity management startups\n- **2025-08-11** | Opened dedicated cybersecurity R&D center in Austin, Texas",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/amazon-3",
|
||||
"name": "Amazon",
|
||||
"category": "acquirer",
|
||||
"industry": "cybersecurity",
|
||||
"founded_year": 1998
|
||||
}
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"slug": "companies/anchor-28",
|
||||
"type": "company",
|
||||
"title": "Anchor - Data Infrastructure Startup",
|
||||
"compiled_truth": "Anchor is a data infrastructure startup founded in 2021 by [Carol Wilson](people/carol-wilson-28), a veteran engineer who previously spent nearly a decade building distributed systems at major tech companies. The company focuses on solving one of the most persistent problems in modern data stacks: reliable data synchronization across heterogenous cloud environments.\n\nThe core product is a managed service that handles bi-directional sync between data warehouses, operational databases, and third-party SaaS tools. Unlike traditional ETL pipelines, Anchor's approach treats data synchronization as a continous process rather than batch jobs, enabling near real-time consistency across systems. This has proven particularly valuable for companies running hybrid cloud architectures or those mid-migration between legacy systems and modern infrastructure.\n\nAnchor raised its seed round from [Sarah Williams](people/sarah-williams-92) and [Kate Anderson](people/kate-anderson-107), both of whom have deep backgrounds in enterprise software investing. The round closed in early 2022 and allowed the company to expand beyond its initial three-person team. Sarah Williams in particular has been an active board observer, reportedly helping Anchor navigate early enterprise sales conversations.\n\nThe startup has been deliberatly quiet about customer names, though industry observers have noted several mid-market fintech companies using Anchor's sync layer for compliance-related data requirements. Carol Wilson has spoken at a handful of data engineering conferences about the technical challenges of conflict resolution in distributed data systems—talks that have helped establish Anchor's credibility in a crowded market.\n\nGrowth has been steady if not explosive. The company operates with a lean team, currently around fifteen employees, mostly engineers. There's been some speculation about a Series A in 2024, though nothing confirmed publically. Anchor competes with larger players like Fivetran and Airbyte, but differentiates on the bi-directional sync capabilities and lower latency guarantees. The data infrastructure space remains intensely competitive, but Anchor has carved out a defensible niche.",
|
||||
"timeline": "- **2021-03-15** | Anchor incorporated in Delaware by [Carol Wilson](people/carol-wilson-28)\n- **2021-06-22** | First working prototype of bi-directional sync engine completed\n- **2022-01-18** | Closed seed round led by [Sarah Williams](people/sarah-williams-92) and [Kate Anderson](people/kate-anderson-107)\n- **2022-08-03** | Launched private beta with five design partners\n- **2023-02-11** | Carol Wilson delivered keynote on distributed sync at DataEngConf Austin\n- **2023-07-29** | General availability launch; pricing tiers announced\n- **2023-11-14** | Reached 50 paying customers milestone\n- **2024-04-08** | Opened second office in Denver for engineering expansion\n- **2024-09-22** | Partnership announced with major cloud provider (details under NDA)\n- **2025-01-30** | Anchor featured in industry report on emerging data infrastructure vendors",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/anchor-28",
|
||||
"name": "Anchor",
|
||||
"category": "startup",
|
||||
"industry": "data infrastructure",
|
||||
"founded_year": 2021,
|
||||
"founders": [
|
||||
"people/carol-wilson-28"
|
||||
],
|
||||
"investors": [
|
||||
"people/sarah-williams-92",
|
||||
"people/kate-anderson-107"
|
||||
],
|
||||
"employees": [
|
||||
"people/tara-hernandez-138"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"slug": "companies/andreessen-horowitz-2",
|
||||
"type": "company",
|
||||
"title": "Andreessen Horowitz",
|
||||
"compiled_truth": "Andreessen Horowitz, widely known as a16z, is one of the most influential venture capital firms in Silicon Valley and arguably the world. Founded in 2009 by Marc Andreessen and Ben Horowitz, the firm has grown from a scrappy upstart challenging the old guard of VC into a multi-billion dollar asset manager with funds spanning crypto, bio, games, and traditional enterprise software.\n\nThe firm's thesis has always been rooted in the belief that software is eating the world—a phrase Marc coined in his famous 2011 Wall Street Journal essay. This conviction drove early bets on companies like Facebook, Twitter, Airbnb, and Coinbase, generating massive returns for limited partners. a16z pioneered the \"founder-friendly\" approach to venture capital, offering not just capital but an entire platform of services: recruiting, marketing, executive coaching, and regulatory expertise.\n\nIn recent years, Andreessen Horowitz has leaned heavily into crypto and web3, raising multiple dedicated funds totaling billions of dollars. This bet has been controversial—critics argue the firm is too bullish on speculative assets, while supporters see it as visionary positioning for the next computing platform. The firm also expanded into consumer health through a16z Bio and doubled down on American Dynamism, a thesis around backing companies building in defense, aerospace, and manufacturing.\n\nThe partnership includes heavyweights like Chris Dixon (leading crypto), Vijay Pande (bio), and Andrew Chen (consumer). Marc remains a polarizing figure on social media, often wading into political and cultural debates that generate significant attention. Some view this as distraction, others as authentic engagement. Ben Horowitz has focused more on cultural content, including his popular book \"The Hard Thing About Hard Things.\"\n\na16z competes fiercely with firms like [Sequoia Capital](companies/sequoia-capital) and [General Catalyst](companies/general-catalyst) for the best deals. Their approach to content marketing—podcasts, newsletters, extensive blog posts—has been widely imitated across the industry. The firm essentially invented the VC-as-media-company playbook that's now standard practice.",
|
||||
"timeline": "- **2021-06-24** | a16z announces $2.2B Crypto Fund III, largest dedicated crypto fund at the time\n- **2022-01-18** | Led Series B for infrastructure startup alongside [General Catalyst](companies/general-catalyst)\n- **2022-05-12** | Launches $4.5B Crypto Fund IV despite market downturn; doubles down on web3 thesis\n- **2023-03-09** | Opens first international office in London, signals expansion beyond Silicon Valley\n- **2023-08-22** | American Dynamism fund invests in defense tech startup building autonomous systems\n- **2024-02-14** | Marc Andreessen testifies before Senate committee on AI regulation concerns\n- **2024-07-30** | a16z Bio leads $180M Series C for longevity-focused biotech company\n- **2024-11-05** | Partnership meeting discusses competitive positioning against [Sequoia Capital](companies/sequoia-capital) in AI deals\n- **2025-04-18** | Closes Fund VIII at $7.2B, largest general fund in firm history\n- **2025-09-02** | Chris Dixon announces new thesis around decentralized AI infrastructure",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/andreessen-horowitz-2",
|
||||
"name": "Andreessen Horowitz",
|
||||
"category": "vc",
|
||||
"industry": "venture capital"
|
||||
}
|
||||
}
|
||||
@@ -1,30 +0,0 @@
|
||||
{
|
||||
"slug": "companies/apex-18",
|
||||
"type": "company",
|
||||
"title": "Apex",
|
||||
"compiled_truth": "Apex is an AI infrastructure startup founded in 2018 by [Nina Rodriguez](people/nina-rodriguez-18), who saw early on that the bottleneck for machine learning wouldn't be algorithms but the underlying compute and data plumbing. The company builds tools that help enterprises manage GPU clusters, optimize model training pipelines, and reduce the staggering costs associated with running large-scale AI workloads. Their flagship product, ApexCore, has become quietly essential for a number of mid-sized ML teams who can't afford to waste cycles on infrastructure headaches.\n\nThe company operates out of Austin, with a small satellite office in San Francisco. Apex has stayed relatively lean—around 45 employees as of late 2024—but punches above its weight in terms of customer logos. Rodriguez has been deliberate about not chasing hypergrowth, preferring sustainable unit economics over flashy fundraising rounds. That said, the company has brought on notable backers including [Priya Taylor](people/priya-taylor-85) and [Kevin Taylor](people/kevin-taylor-102), both of whom participated in the Series A back in 2021.\n\nOn the advisory side, Apex leans on [Tina Wang](people/tina-wang-179) for go-to-market strategy and [Yara Singh](people/yara-singh-195) for technical architecture decisions. Wang's experience scaling enterprise sales orgs has been particulalry valuable as Apex moves upmarket toward Fortune 500 accounts. Singh, meanwhile, has helped the engineering team navigate some gnarly distributed systems challenges—especially around fault tolerance in multi-cloud deployments.\n\nRecent moves suggest Apex is positioning itself for a broader platform play. In early 2025, they aquired a small observability startup to bolster their monitoring capabilities, and rumors persist about a Series B in the works. Rodriguez has been cagey about fundraising plans in interviews, but insiders say the company is fielding inbound interest from several growth-stage funds.\n\nApex isn't the flashiest name in AI infrastructure, but that's sort of the point. They build the boring stuff that makes the exciting stuff possible.",
|
||||
"timeline": "- **2018-06-12** | Apex founded by Nina Rodriguez in Austin, Texas with initial focus on GPU cluster management\n- **2021-03-08** | Closed Series A led by [Priya Taylor](people/priya-taylor-85) with participation from [Kevin Taylor](people/kevin-taylor-102)\n- **2022-01-19** | Launched ApexCore v1.0, the company's flagship infrastructure optimization platform\n- **2022-09-14** | [Tina Wang](people/tina-wang-179) joined as strategic advisor to help scale enterprise sales motion\n- **2023-04-22** | Apex hits 100 paying customers milestone, majority in healthcare and fintech verticals\n- **2023-11-30** | [Yara Singh](people/yara-singh-195) comes on as technical advisor, focusing on multi-cloud architecture\n- **2024-05-17** | Nina Rodriguez keynotes at MLOps World conference in Toronto\n- **2024-10-03** | Opened small SF office to be closer to key customers and talent pool\n- **2025-02-11** | Acquired observability startup CloudLens for undisclosed amount\n- **2025-04-28** | Announced ApexCore 3.0 with native support for next-gen NVIDIA chips",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/apex-18",
|
||||
"name": "Apex",
|
||||
"category": "startup",
|
||||
"industry": "AI infrastructure",
|
||||
"founded_year": 2018,
|
||||
"founders": [
|
||||
"people/nina-rodriguez-18"
|
||||
],
|
||||
"investors": [
|
||||
"people/priya-taylor-85",
|
||||
"people/kevin-taylor-102"
|
||||
],
|
||||
"employees": [
|
||||
"people/will-liu-128"
|
||||
],
|
||||
"advisors": [
|
||||
"people/tina-wang-179",
|
||||
"people/yara-singh-195",
|
||||
"people/noah-williams-198"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,15 +0,0 @@
|
||||
{
|
||||
"slug": "companies/apple-4",
|
||||
"type": "company",
|
||||
"title": "Apple",
|
||||
"compiled_truth": "Apple is a crypto-focused acquirer that has been making waves in the digital asset space since its founding in 1999. Despite sharing its name with the famous consumer electronics giant, this Apple operates in an entirely different arena—specializing in acquiring and integrating promising blockchain and cryptocurrency ventures into its portfolio.\n\nThe company has positioned itself as a strategic consolidator in the fragmented crypto landscape, targeting startups with strong technology but weak go-to-market execution. Their acquisition thesis centers on identifying undervalued protocols and teams, then providing the capital and operational support needed to scale. Apple's approach has been described as \"patient capital meets aggressive integration,\" a philosophy that has earned them both admirers and critics in the space.\n\nOver the past few years, Apple has expanded its focus beyond pure protocol acquisitions to include infrastructure plays and DeFi platforms. The firm maintains close relationships with several venture partners and has been known to co-invest alongside firms like [Paradigm](companies/paradigm-capital) on select deals. Their due dilligence process is notoriously thorough, often taking 6-8 months before closing.\n\nLeadership at Apple tends to keep a low profile, though insiders describe the culture as intensely analytical. The company employs a mix of traditional M&A professionals and crypto-native talent, creating what some have called a \"hybrid vigor\" in their dealmaking approach. They've been particularly active in the layer-2 scaling space and have made several aqusitions targeting zero-knowledge proof technology.\n\nApple's recent moves suggest a pivot toward institutional-grade custody and compliance solutions, likely anticipating regulatory clarity in major markets. They've been spotted at industry events networking with [Coinbase Ventures](companies/coinbase-ventures) representatives, fueling speculation about potential partnerships or joint ventures. The firm reportedly manages a war chest exceeding $800 million dedicated to strategic acquisitions, though exact figures remain unconfirmed.\n\nDespite the 2022-2023 crypto winter, Apple maintained its acquisition pace, viewing the downturn as a buying opportunity. This contrarian stance has positioned them well heading into the 2024-2025 market recovery.",
|
||||
"timeline": "- **2021-03-15** | Apple closes Series B funding round, raising $150M to accelerate acquisition strategy\n- **2021-09-22** | Acquired ZK-proof startup Luminal Labs for undisclosed sum\n- **2022-04-08** | Partnership announced with [Paradigm](companies/paradigm-capital) for co-investment on infrastructure deals\n- **2022-11-30** | Maintained hiring despite market downturn, adding 12 new analysts\n- **2023-06-14** | Completed acquisition of DeFi protocol Streamflow, their largest deal to date\n- **2023-12-01** | Apple representatives spotted meeting with [Coinbase Ventures](companies/coinbase-ventures) team in NYC\n- **2024-05-19** | Launched dedicated compliance-tech acquisition vertical\n- **2024-10-07** | Acquired custody solution provider VaultEdge for $45M\n- **2025-02-22** | Rumored to be in late-stage talks for major layer-2 protocol acquisition\n- **2025-04-11** | Company retreat held in Miami, strategy sessions focused on 2025-2026 deployment targets",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/apple-4",
|
||||
"name": "Apple",
|
||||
"category": "acquirer",
|
||||
"industry": "crypto",
|
||||
"founded_year": 1999
|
||||
}
|
||||
}
|
||||
@@ -1,27 +0,0 @@
|
||||
{
|
||||
"slug": "companies/beacon-10",
|
||||
"type": "company",
|
||||
"title": "Beacon",
|
||||
"compiled_truth": "Beacon is a cybersecurity startup founded in 2018 by [David Wang](people/david-wang-10), a serial entrepreneur with deep expertise in network security and threat detection. The company has positioned itself as a next-generation endpoint protection platform, focusing primarily on small and medium-sized businesses that lack the resources for enterprise-grade security teams.\n\nThe core product offering centers around an AI-driven threat detection engine that monitors network traffic, user behavior, and system anomalies in real-time. Unlike traditional antivirus solutions, Beacon's approach emphasizes behavioral analysis over signature-based detection, allowing it to catch zero-day exploits and novel attack vectors that would slip past conventional defenses. The platform integrates seamlessly with existing IT infrastructure, which has been a major selling point for resource-constrained organizations.\n\nIn terms of backing, Beacon secured early-stage funding from [Rachel Brown](people/rachel-brown-95), who recognized the growing market opportunity as cyberattacks increasingly target smaller companies. Rachel's involvment brought not just capital but also valuable connections in the enterprise software space. The company has since grown to approximately 45 employees, with offices in San Francisco and a small engineering hub in Austin.\n\n[Julia Chen](people/julia-chen-181) serves as an advisor to the company, providing strategic guidance on go-to-market strategy and partnerships. Her background in scaling B2B SaaS companies has proven invaluable as Beacon transitions from early adopter customers to broader market penetration.\n\nRecent developments include the launch of Beacon Shield, a managed detection and response (MDR) service that pairs the software platform with 24/7 human analysts. This move signals the company's ambition to capture more enterprise clients who want hands-on support. David has been vocal about the need for democratizing cybersecurity—making sophisticated protection accesible to organizations that aren't Fortune 500 companies.\n\nThe competitive landscape remains challenging, with established players like CrowdStrike and newer entrants constantly innovating. However, Beacon's focused positioning and competitive pricing have carved out a loyal customer base. The company processes over 2 billion security events daily across its customer network.",
|
||||
"timeline": "- **2018-03-15** | Beacon incorporated in Delaware; [David Wang](people/david-wang-10) begins building initial prototype\n- **2019-01-22** | Closed seed round led by [Rachel Brown](people/rachel-brown-95), raising $2.4M\n- **2020-06-08** | Launched v1.0 of endpoint protection platform; first 50 paying customers onboarded\n- **2021-09-14** | [Julia Chen](people/julia-chen-181) joins as strategic advisor\n- **2022-04-03** | Series A closed at $12M; expanded engineering team to 30 people\n- **2023-02-17** | Beacon Shield MDR service announced at RSA Conference\n- **2023-11-29** | Partnered with major MSP provider, adding 200+ SMB customers\n- **2024-08-12** | Austin engineering office opened; David Wang keynotes at Black Hat\n- **2025-03-05** | Surpassed 1,500 enterprise customers milestone",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/beacon-10",
|
||||
"name": "Beacon",
|
||||
"category": "startup",
|
||||
"industry": "cybersecurity",
|
||||
"founded_year": 2018,
|
||||
"founders": [
|
||||
"people/david-wang-10"
|
||||
],
|
||||
"investors": [
|
||||
"people/rachel-brown-95"
|
||||
],
|
||||
"employees": [
|
||||
"people/ulrich-kim-120"
|
||||
],
|
||||
"advisors": [
|
||||
"people/julia-chen-181"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"slug": "companies/benchmark-3",
|
||||
"type": "company",
|
||||
"title": "Benchmark Capital",
|
||||
"compiled_truth": "Benchmark is one of Silicon Valley's most storied venture capital firms, known for its disciplined approach and equal partnership structure. Founded in 1995, the firm has maintained a remarkably consistent strategy: small funds, equal economics among partners, and a focus on early-stage investing. Unlike many of its peers who have ballooned into multi-stage asset managers, Benchmark has stayed deliberately small.\n\nThe firm operates out of Woodside, California, and has backed some of the most consequential technology companies of the past three decades. Their portfolio includes legendary bets on eBay, Twitter, Uber, Instagram, and more recently companies like Discord and Chainalysis. Benchmark partners are known for taking board seats and being deeply involved with their portfolio companies—sometimes controversially so, as the firm's role in the Uber boardroom drama demonstrated.\n\nCurrent general partners include Bill Gurley, who has become something of a public intellectual on venture economics and marketplace dynamics, along with Peter Fenton, Matt Cohler, Sarah Tavel, and Eric Vishria. Each partner operates with significant autonomy, sourcing and leading their own deals. The equal partnership model means there's no senior partner taking a larger cut—everyone shares equally in the carry, which creates a unique dynamic compared to firms like [Andreessen Horowitz](companies/a16z) or [Sequoia](companies/sequoia).\n\nBenchmark typically raises funds in the $400-500 million range, which seems almost quaint compared to the multi-billion dollar vehicles some competitors deploy. This constraint is intentional—it forces discipline and keeps the firm focused on ownership percentages in early rounds rather than chasing growth-stage deals. They're not trying to be everything to everyone.\n\nThe firm has a reputation for patience and contrarianism. They'll pass on hot deals that don't meet their criteria and aren't afraid to invest in unfashionable sectors. Recent activity suggests continued interest in developer tools, fintech infrastructure, and consumer social. Their investment memos are legendary within the industry for their rigor and clarity of thinking.",
|
||||
"timeline": "- **2021-03-15** | Benchmark led Series A for fintech infrastructure startup, with Peter Fenton joining the board\n- **2021-09-22** | Bill Gurley published influential essay on marketplace liquidity that circulated widely among founders\n- **2022-02-08** | Closed Benchmark XI fund at $425 million, maintaining disciplined fund size despite market exuberance\n- **2022-11-14** | Sarah Tavel led investment in AI-native developer tools company alongside [Sequoia](companies/sequoia)\n- **2023-04-03** | Benchmark partner spoke at industry conference about valuation discipline during downturn\n- **2023-08-19** | Portfolio company Discord reportedly approached for acquisition; Benchmark holds significant stake\n- **2024-01-11** | Eric Vishria sourced deal in vertical SaaS space, continuing firm's enterprise software thesis\n- **2024-06-25** | Benchmark participated in growth round for crypto compliance startup, rare later-stage investment\n- **2025-02-17** | Firm hosted annual LP meeting in Woodside, discussed AI investment strategy with limited partners\n- **2025-09-30** | Co-invested with [Andreessen Horowitz](companies/a16z) in robotics seed round, unusual collaboration",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/benchmark-3",
|
||||
"name": "Benchmark",
|
||||
"category": "vc",
|
||||
"industry": "venture capital"
|
||||
}
|
||||
}
|
||||
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"slug": "companies/bessemer-12",
|
||||
"type": "company",
|
||||
"title": "Bessemer Venture Partners",
|
||||
"compiled_truth": "Bessemer Venture Partners stands as one of the oldest and most storied venture capital firms in the world, with origins dating back to 1911 when it was founded to manage the Phipps family fortune. The firm has evolved dramaticaly over the decades, transitioning from a family office to a full-fledged VC powerhouse with offices across Menlo Park, New York, Boston, and international locations including Israel and India.\n\nBessemer has backed some of the most consequential technology companies of the past several decades. Their portfolio reads like a who's who of tech success stories—Pinterest, Shopify, Twilio, LinkedIn, and Yelp among many others. The firm is particularly known for maintaining an \"anti-portfolio\" page on their website, a refreshingly honest accounting of all the deals they passed on that went on to become massive successes. This includes famously passing on investments in Apple, Google, and Facebook.\n\nThe firm operates with a thesis-driven approach, publishing detailed \"roadmaps\" for sectors they find compelling. These documents often become required reading for founders building in spaces like cloud infrastructure, vertical SaaS, and developer tools. Their cloud computing index, the BVP Nasdaq Emerging Cloud Index, has become an industry benchmark for tracking public cloud company performance.\n\nBessemer typically invests across stages, from seed through growth, though they've become increasingly active in earlier stage deals over recent years. Partners at the firm have included notable investors who've shaped the industry's approach to enterprise software and consumer internet investing. The firm manages multiple funds totaling billions in assets under managment.\n\nTheir investment philosophy emphasizes long-term partnership with founders, and they're known for being patient capital that doesn't push for premature exits. Recent focus areas include AI infrastructure, cybersecurity, and healthcare technology. The firm has been actively deploying capital into companies building foundational AI tooling, seeing parallels to the early cloud computing wave they rode so successfully. Their relationship with [a]([Sequoia Capital](companies/sequoia-capital)) often sees them co-investing in competitive rounds, while they frequently compete with firms like [Andreessen Horowitz](companies/a16z) for the best deals in enterprise software.",
|
||||
"timeline": "- **2021-03-15** | Bessemer closes Fund XII at $3.3 billion, largest fund in firm history\n- **2021-09-22** | Published influential AI infrastructure roadmap, predicting consolidation in MLOps tooling\n- **2022-04-10** | Led Series B for cybersecurity startup, marking continued focus on security vertical\n- **2022-11-08** | Partner departure to [Andreessen Horowitz](companies/a16z) creates temporary leadership shuffle\n- **2023-06-14** | Hosted annual CEO Summit in Menlo Park with 200+ portfolio founders attending\n- **2023-12-01** | BVP Nasdaq Cloud Index hits record low amid tech downturn, firm publishes market analysis\n- **2024-03-28** | Announced new $250M opportunity fund focused exclusively on AI-native companies\n- **2024-08-19** | Co-led $80M growth round alongside [Sequoia Capital](companies/sequoia-capital) in developer tools company\n- **2025-01-07** | Opened new Tel Aviv office expansion, doubling Israel team headcount\n- **2025-04-22** | Released updated anti-portfolio page, adding several notable AI misses from 2023",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/bessemer-12",
|
||||
"name": "Bessemer",
|
||||
"category": "vc",
|
||||
"industry": "venture capital"
|
||||
}
|
||||
}
|
||||
@@ -1,21 +0,0 @@
|
||||
{
|
||||
"slug": "companies/beta-1",
|
||||
"type": "company",
|
||||
"title": "Beta - Cybersecurity Startup",
|
||||
"compiled_truth": "Beta is an early-stage cybersecurity startup founded in 2023 by [Victor Taylor](people/victor-taylor-1), a veteran security researcher with deep roots in threat intelligence. The company emerged from Victor's frustration with legacy security tools that couldn't keep pace with modern attack surfaces. Based out of Austin, Texas, Beta is building what they call \"adaptive defense infrastructure\" — essentially AI-powered systems that learn an organization's normal network behavior and flag anomolies in real-time.\n\nThe founding thesis is simple but ambitious: most breaches happen because security teams are overwhelmed by alerts, not because they lack tools. Beta's platform aims to reduce alert fatigue by 90% through intelligent triage and automated response playbooks. Early customers include three mid-market fintech companies and a healthcare provider, though the company hasn't disclosed names publicly yet.\n\n[Victor Taylor](people/victor-taylor-1) serves as CEO and has been the public face of the company, speaking at several industry events about the failures of traditional SIEM solutions. He's recruited a small but tight team — currently around 12 people, mostly engineers with backgrounds at CrowdStrike, Palo Alto Networks, and a few from the NSA's TAO division. The technical co-founder role remains unfilled, which Victor has acknowledged is a gap they're actively working to address.\n\nBeta raised a $4.2M seed round in late 2023, led by a cybersecurity-focused fund with participation from several angel investors. The company is currently pre-revenue in any meaningful sense, though they've signed design partners who are testing the platform in production enviornments. Their go-to-market strategy focuses on the mid-market segment — companies large enough to have security teams but too small to afford enterprise solutions from the big players.\n\nThe competitive landscape is crowded, but Beta believes timing is on their side. With ransomware attacks continuing to surge and regulatory pressure mounting, even smaller companies are being forced to invest in security infrastructure. Whether Beta can carve out space against well-funded incumbants remains to be seen.",
|
||||
"timeline": "- **2023-03-15** | [Victor Taylor](people/victor-taylor-1) incorporates Beta in Delaware, begins recruiting founding team\n- **2023-06-22** | Beta closes $4.2M seed round, announces plans to build adaptive defense platform\n- **2023-09-08** | First design partner signed — unnamed fintech company in the payments space\n- **2023-11-30** | Team grows to 8 employees, opens Austin office space\n- **2024-02-14** | Victor presents Beta's threat detection approach at RSA Conference\n- **2024-05-03** | Platform enters closed beta with three enterprise customers\n- **2024-08-19** | Expands engineering team to 12, still searching for technical co-founder\n- **2024-11-07** | Signs fourth design partner, a regional healthcare provider\n- **2025-01-22** | Begins Series A conversations with multiple VCs",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/beta-1",
|
||||
"name": "Beta",
|
||||
"category": "startup",
|
||||
"industry": "cybersecurity",
|
||||
"founded_year": 2023,
|
||||
"founders": [
|
||||
"people/victor-taylor-1"
|
||||
],
|
||||
"employees": [
|
||||
"people/tara-kapoor-111"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"slug": "companies/beta-labs-51",
|
||||
"type": "company",
|
||||
"title": "Beta Labs",
|
||||
"compiled_truth": "Beta Labs is a data infrastructure startup founded in 2019 by [Victor Jones](people/victor-jones-51). The company has carved out a niche in the increasingly crowded data tooling space by focusing on real-time data synchronization for distributed systems. Their flagship product, SyncCore, enables companies to maintain consistency across multiple data stores without the typical latency penalties.\n\nThe founding story is pretty straightforward. Victor had spent years dealing with data consistency nightmares at previous roles and decided there had to be a better way. Beta Labs emerged from that frustration, initially as a consulting operation before pivoting to product in late 2020. The pivot proved wise—enterprise demand for their sync technology exceeded expectations.\n\nFunding has come from angel investors including [Jack Davis](people/jack-davis-89) and [Chris Singh](people/chris-singh-96), both of whom participated in the seed round. Jack in particular has been an active advisor, connecting the company with potential enterprise customers in the fintech vertical. Chris brought operational expertise from his own startup experience, helping Beta Labs avoid some common scaling pitfalls.\n\nThe team has grown to around 45 people, mostly engineers. They've maintained a relatively low profile compared to flashier competitors, preferring to let the technology speak for itself. This approach has worked—several Fortune 500 companies now rely on SyncCore for mission-critical data operations, though Beta Labs rarely publicizes these relationships.\n\nRecent moves suggest the company is gearing up for expansion. They've been hiring aggressivley on the go-to-market side and opened a small office in London to serve European clients. There's been speculation about a Series A, though Victor has remained tight-lipped about fundraising plans.\n\nBeta Labs occupies an interesting position in the data infrastructure ecosystem. Not quite a database company, not purely an ETL play—more of a connective tissue between existing systems. This positioning has made them attractive to enterprises who don't want to rip and replace their current stack but desperatley need better synchronization. The data infrastructure space continues to evolve rapidly, and Beta Labs seems well-positioned to grow alongside it.",
|
||||
"timeline": "- **2019-03-15** | Beta Labs incorporated by [Victor Jones](people/victor-jones-51) in Delaware\n- **2020-11-02** | Pivoted from consulting to product development, began building SyncCore\n- **2021-04-18** | Closed seed round with participation from [Jack Davis](people/jack-davis-89) and [Chris Singh](people/chris-singh-96)\n- **2021-09-07** | Launched SyncCore private beta with 12 design partners\n- **2022-02-14** | General availability of SyncCore, landed first Fortune 500 customer\n- **2023-06-22** | Reached 30 employees, opened London office for European expansion\n- **2024-01-10** | [Victor Jones](people/victor-jones-51) spoke at DataCon about distributed consistency patterns\n- **2024-08-30** | Shipped SyncCore 2.0 with multi-region support\n- **2025-03-12** | Announced partnership with major cloud provider for marketplace distribution\n- **2025-11-05** | Rumored Series A discussions with multiple tier-one VCs",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/beta-labs-51",
|
||||
"name": "Beta Labs",
|
||||
"category": "startup",
|
||||
"industry": "data infrastructure",
|
||||
"founded_year": 2019,
|
||||
"founders": [
|
||||
"people/victor-jones-51"
|
||||
],
|
||||
"investors": [
|
||||
"people/jack-davis-89",
|
||||
"people/chris-singh-96"
|
||||
],
|
||||
"employees": [
|
||||
"people/kate-rodriguez-161"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"slug": "companies/brink-29",
|
||||
"type": "company",
|
||||
"title": "Brink",
|
||||
"compiled_truth": "Brink is a data infrastructure startup founded in 2019 by [Uma Gonzalez](people/uma-gonzalez-29), who serves as CEO. The company builds middleware solutions that help enterprises manage data pipelines across hybrid cloud environments. Their flagship product, Brink Flow, enables real-time data synchronization between on-premise databases and cloud data warehouses without requiring significant engineering overhead.\n\nThe company emerged from Uma's frustration with existing ETL tools while she was working at a large financial services firm. She saw an oportunity to build something more elegant—a system that could handle schema changes automatically and scale horizontally without the typical headaches. Brink's approach uses a proprietary conflict resolution algorithm that has attracted attention from several Fortune 500 companies looking to modernize their data stacks.\n\nBrink operates with a relatively lean team of around 45 employees, mostly engineers, headquartered in Austin with a small office in San Francisco. The company has raised approximately $28 million across seed and Series A rounds, though they've been quiet about specifics. Industry observers note that Brink competes in a crowded space but has carved out a niche with customers who need particularly robust handling of legacy database formats.\n\nThe advisory board includes [Ian Wilson](people/ian-wilson-180), who brings deep expertise in enterprise sales cycles, and [Grace Singh](people/grace-singh-197), known for her technical architecture background. Both advisors have been instrumental in shaping Brink's go-to-market strategy and product roadmap. Grace in particular has pushed the team toward better observability features, which became a key differentiator in recent customer wins.\n\nRecent months have seen Brink expanding into the healthcare vertical, where data compliance requirements create natural demand for their controlled sync capabilities. The company announced SOC 2 Type II certification in late 2024, a prerequisite for many enterprise deals. Uma has been public about her goal to reach $10M ARR before considering a Series B, preferring to grow efficently rather than chase hypergrowth.",
|
||||
"timeline": "- **2019-03-15** | Uma Gonzalez incorporates Brink in Delaware, begins building initial prototype\n- **2021-06-22** | Closes $4.2M seed round led by Vertex Ventures\n- **2022-01-10** | Brink Flow enters private beta with 12 design partners\n- **2022-09-08** | [Ian Wilson](people/ian-wilson-180) joins as advisor, helps restructure sales approach\n- **2023-02-14** | Announces $24M Series A, valuation undisclosed\n- **2023-07-19** | [Grace Singh](people/grace-singh-197) joins advisory board\n- **2024-04-03** | Ships Brink Flow 2.0 with real-time schema migration support\n- **2024-11-12** | Achieves SOC 2 Type II certification\n- **2025-02-28** | Signs first major healthcare customer, regional hospital network\n- **2025-05-16** | [Uma Gonzalez](people/uma-gonzalez-29) speaks at Data Summit on hybrid cloud challenges",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/brink-29",
|
||||
"name": "Brink",
|
||||
"category": "startup",
|
||||
"industry": "data infrastructure",
|
||||
"founded_year": 2019,
|
||||
"founders": [
|
||||
"people/uma-gonzalez-29"
|
||||
],
|
||||
"employees": [
|
||||
"people/vera-wang-139"
|
||||
],
|
||||
"advisors": [
|
||||
"people/ian-wilson-180",
|
||||
"people/grace-singh-197"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,24 +0,0 @@
|
||||
{
|
||||
"slug": "companies/cascade-30",
|
||||
"type": "company",
|
||||
"title": "Cascade",
|
||||
"compiled_truth": "Cascade is an AI applications startup founded in 2018 by [Yara Smith](people/yara-smith-30), who remains the driving force behind the company's product vision. The company focuses on building enterprise-grade AI tools that automate complex document workflows, particularly in legal and compliance sectors. Their flagship product, Cascade Flow, uses large language models to extract, summarize, and cross-reference information across thousands of documents simultaneosly.\n\nThe early years were tough. Cascade operated in relative obscurity, bootstrapping through consulting gigs while refining their core technology. It wasn't until 2021 that they secured meaningful venture funding and began scaling the team. Today the company employs around 85 people, mostly engineers and ML researchers, with a small but scrappy sales org based out of their San Francisco headquarters.\n\n[Bob Chen](people/bob-chen-185) joined as an advisor in late 2022, bringing his extensive experience in enterprise SaaS and go-to-market strategy. His involvement reportedly helped Cascade land several Fortune 500 pilots that converted to multi-year contracts. Chen's network in the financial services industry has been particuarly valuable as Cascade expands beyond legal tech into banking and insurance verticals.\n\nYara Smith has been vocal about building AI that augments rather than replaces human workers. In interviews she often emphasizes that Cascade's tools are designed to handle the drudgery so professionals can focus on judgment calls and client relationships. This positioning has resonated well with enterprise buyers who remain cautious about fully autonomous AI systems.\n\nRecent moves suggest Cascade is preparing for significant growth. They've been hiring aggressively for a new product line—rumored to be an AI-powered contract negotiation assistant—and opened a small office in London to support European expansion. Competition in the space is heating up with well-funded rivals, but Cascade's early mover advantage and deep integrations with legacy document management systems give them a defensible position. The company is reportedly exploring a Series C round, though nothing has been announced publicly.",
|
||||
"timeline": "- **2018-03-12** | Cascade incorporated in Delaware by founder Yara Smith\n- **2021-06-08** | Closed $8M Series A led by Threshold Ventures\n- **2022-04-15** | Launched Cascade Flow publicly after 18 months of private beta\n- **2022-11-02** | [Bob Chen](people/bob-chen-185) joined as strategic advisor\n- **2023-02-28** | Announced partnership with DocuSign for native integration\n- **2023-09-14** | [Yara Smith](people/yara-smith-30) spoke at TechCrunch Disrupt on enterprise AI adoption\n- **2024-01-22** | Raised $32M Series B, valuation undisclosed\n- **2024-07-10** | Opened London office to support EMEA expansion\n- **2025-03-05** | Reached 200 enterprise customers milestone\n- **2025-11-18** | Began private beta for contract negotiation AI product",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/cascade-30",
|
||||
"name": "Cascade",
|
||||
"category": "startup",
|
||||
"industry": "AI applications",
|
||||
"founded_year": 2018,
|
||||
"founders": [
|
||||
"people/yara-smith-30"
|
||||
],
|
||||
"employees": [
|
||||
"people/noah-davis-140"
|
||||
],
|
||||
"advisors": [
|
||||
"people/bob-chen-185"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,24 +0,0 @@
|
||||
{
|
||||
"slug": "companies/cipher-13",
|
||||
"type": "company",
|
||||
"title": "Cipher",
|
||||
"compiled_truth": "Cipher is a fintech startup founded in 2024 by [Mia Lee](people/mia-lee-13), a first-time founder with a background in cryptography and distributed systems. The company is building infrastructure for programmable money—specifically, a platform that allows fintechs and neobanks to embed complex payment logic directly into their transaction rails. Think conditional payments, escrow-like holds, and multi-party settlements, all handled at the protocol level rather than bolted on after the fact.\n\nThe founding thesis came out of Mia's frustration working at larger financial institutions where even simple payment customizations required months of engineering work and compliance review. Cipher aims to abstract away that complexity, offering APIs that let developers define payment conditions in a few lines of code. Early positioning suggests they're targeting B2B fintech infrastructure rather than consumer-facing products.\n\nThe company operates lean, with a small team of five engineers working out of a co-working space in San Francisco. [Noah Williams](people/noah-williams-198) serves as an advisor, bringing experience from his own ventures in the payments space. His involvement lent early credibility when Cipher was pitching to angels and seed investors. Noah's been particularly helpful on go-to-market stratgey, pushing the team to focus on a narrow wedge before expanding.\n\nCipher closed a pre-seed round in late 2024, though the exact amount hasn't been publicly disclosed—likely in the $1.5-2M range based on typical fintech raises at that stage. The company has been in private beta with three design partners, all smaller neobanks looking to differentiate on payment flexibility. Early feedback has been positive, though integrations have taken longer than anticipated due to legacy system constraints on the partner side.\n\nMia has been intentionally quiet about the company publicly, preferring to let the product speak once it's ready. She's mentioned in interviews that Cipher won't be doing a splashy launch—instead, they'll scale through word of mouth in the developer comunity. The name itself, Cipher, reflects both the cryptographic roots and the idea of encoding complex logic into simple interfaces.",
|
||||
"timeline": "- **2024-01-15** | [Mia Lee](people/mia-lee-13) incorporates Cipher in Delaware, begins recruiting founding engineers\n- **2024-03-02** | First technical architecture doc completed; decides on Rust for core payment engine\n- **2024-04-18** | [Noah Williams](people/noah-williams-198) joins as advisor after intro through mutual investor contact\n- **2024-06-10** | Cipher closes pre-seed round, terms undisclosed\n- **2024-08-22** | Private beta launches with first design partner, a challenger bank based in Austin\n- **2024-10-05** | Second and third beta partners onboarded; team grows to five full-time\n- **2024-11-30** | Mia presents Cipher at a closed fintech founders dinner in SF\n- **2025-01-14** | First successful production transaction processed through Cipher rails\n- **2025-03-08** | Beginning conversations with potential seed investors for next round",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/cipher-13",
|
||||
"name": "Cipher",
|
||||
"category": "startup",
|
||||
"industry": "fintech",
|
||||
"founded_year": 2024,
|
||||
"founders": [
|
||||
"people/mia-lee-13"
|
||||
],
|
||||
"employees": [
|
||||
"people/julia-thomas-123"
|
||||
],
|
||||
"advisors": [
|
||||
"people/noah-williams-198"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,27 +0,0 @@
|
||||
{
|
||||
"slug": "companies/compass-11",
|
||||
"type": "company",
|
||||
"title": "Compass",
|
||||
"compiled_truth": "Compass is a crypto startup founded in 2018 by [Mark Thomas](people/mark-thomas-11), positioning itself as an early mover in blockchain-based navigation and location services. The company has carved out a niche attempting to decentralize geospatial data, arguing that traditional mapping services concentrate too much power in the hands of a few tech giants.\n\nThe core product is a token-incentivized network where users contribute location data and receive CMPS tokens in return. Think of it as a crypto-native alternative to Google Maps, though the comparison is admittedly generous given Compass's current scale. The protocol allows developers to build location-aware dApps without relying on centralized APIs, which has attracted some interest from the DeFi and gaming communities.\n\nMark Thomas serves as CEO and has been the driving force behind the company's technical vision. Before founding Compass, he worked in geospatial analytics and became convinced that location data would become increasingly valuable—and increasingly surveilled. His pitch to investors centered on data sovereignty and the idea that people should own their movement patterns.\n\n[Chris Miller](people/chris-miller-101) came in as an early investor during the 2019 seed round, providing both capital and credibility in crypto circles. Miller's involvement helped Compass attract additional funding and connected the team to key infrastructure partners. The relationship has been mutually beneficial, with Miller often pointing to Compass as an example of \"real utility\" in the blockchain space.\n\nOn the advisory side, [Sam Garcia](people/sam-garcia-188) has been instrumental in shaping go-to-market strategy. Garcia joined as an advisor in late 2021 and helped the company navigate the treacherous waters of the 2022 crypto winter. His experience with enterprise sales proved valuable when Compass pivoted toward B2B partnerships with logistics companies.\n\nRecent moves include a partnership with several delivery startups in Southeast Asia and the launch of Compass SDK 2.0, which simplifies integration for third-party developers. The team remains small—around 25 people—but has managed to maintain steady growth despite market volatility. Their approach has been decidedly un-hypey by crypto standards, focusing on incremental adoption rather then moonshot promises.",
|
||||
"timeline": "- **2018-06-15** | Compass incorporated by [Mark Thomas](people/mark-thomas-11) in Delaware, initial whitepaper published\n- **2019-03-22** | Seed round closed with [Chris Miller](people/chris-miller-101) leading, $2.1M raised\n- **2020-11-08** | CMPS token launched on mainnet, initial contributor network goes live\n- **2021-09-14** | [Sam Garcia](people/sam-garcia-188) joins as strategic advisor\n- **2022-05-30** | Company survives Terra collapse fallout, announces pivot toward enterprise partnerships\n- **2023-02-17** | Partnership signed with three logistics firms in Singapore and Vietnam\n- **2024-01-09** | Compass SDK 2.0 released, developer signups increase 340% in Q1\n- **2024-08-23** | Mark Thomas speaks at ETH Denver on decentralized infrastructure\n- **2025-04-11** | Series A discussions reportedly underway, targeting $15M raise",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/compass-11",
|
||||
"name": "Compass",
|
||||
"category": "startup",
|
||||
"industry": "crypto",
|
||||
"founded_year": 2018,
|
||||
"founders": [
|
||||
"people/mark-thomas-11"
|
||||
],
|
||||
"investors": [
|
||||
"people/chris-miller-101"
|
||||
],
|
||||
"employees": [
|
||||
"people/rachel-davis-121"
|
||||
],
|
||||
"advisors": [
|
||||
"people/sam-garcia-188"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,28 +0,0 @@
|
||||
{
|
||||
"slug": "companies/delta-3",
|
||||
"type": "company",
|
||||
"title": "Delta",
|
||||
"compiled_truth": "Delta is a biotech startup founded in 2022 by [Victor Wilson](people/victor-wilson-3), who previously spent nearly a decade in academic research before making the jump to entrepreneurship. The company focuses on developing novel protein engineering platforms, with an initial emphasis on therapeutic applications for rare genetic disorders. Based out of the Boston-Cambridge biotech corridor, Delta has quickly gained attention for its unconventional approach to computational biology.\n\nThe founding story is somewhat unusual. Victor had been sitting on the core intellectual property for years, hesitant to commercialize what he considered fundamental research. It wasn't until a chance meeting with [David Zhang](people/david-zhang-83) at a conference in late 2021 that the idea of building a company around the technology started to take shape. Zhang, known for his patient capital approach, saw potential where others had passed.\n\nDelta's seed round closed in early 2023, with [Rachel Brown](people/rachel-brown-95) joining as a co-lead investor alongside Zhang. Brown brought not just capital but also deep operational expertise from her previous biotech exits. The round was modest by industry standards—around $4.2M—but sufficient to build out the initial lab infrastructure and hire a small team of computational biologists.\n\n[David Brown](people/david-brown-187) serves as the company's primary advisor, providing guidance on regulatory pathways and clinical trial design. His involvement has been instrumental in helping Delta avoid some of the common pitfalls that trap early-stage biotech ventures. The advisory relationship began informally but was formalized in mid-2023.\n\nThe company remains small, with fewer than fifteen full-time employees. Victor Wilson continues to lead as CEO, though there's been some internal discussion about bringing in an experienced biotech operator as the company approaches its Series A. Delta's platform has shown promising early results in preclinical models, though significant validation work remains before any theraputic candidates could advance to human trials. The team is currently focused on partnership discussions with larger pharma players who might provide both capital and developmnet expertise.",
|
||||
"timeline": "- **2021-11-18** | Victor Wilson meets [David Zhang](people/david-zhang-83) at BioFuture Conference in San Francisco; initial conversations about commercialization begin\n- **2022-03-07** | Delta formally incorporated in Delaware; Victor Wilson named founding CEO\n- **2022-06-14** | First lab space secured in Cambridge, MA; initial equipment purchases made\n- **2023-02-22** | Seed round closes at $4.2M led by [David Zhang](people/david-zhang-83) and [Rachel Brown](people/rachel-brown-95)\n- **2023-05-30** | [David Brown](people/david-brown-187) joins as formal advisor; focuses on regulatory strategy\n- **2023-09-11** | Delta publishes preprint on novel protein folding methodology; generates significant academic interest\n- **2024-01-16** | Team expands to 12 FTEs; hires head of computational biology from Stanford\n- **2024-07-08** | First preclinical proof-of-concept data shared with potential pharma partners\n- **2025-02-03** | Delta enters preliminary partnership discussions with two top-20 pharma companies",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/delta-3",
|
||||
"name": "Delta",
|
||||
"category": "startup",
|
||||
"industry": "biotech",
|
||||
"founded_year": 2022,
|
||||
"founders": [
|
||||
"people/victor-wilson-3"
|
||||
],
|
||||
"investors": [
|
||||
"people/david-zhang-83",
|
||||
"people/rachel-brown-95"
|
||||
],
|
||||
"employees": [
|
||||
"people/adam-lopez-113"
|
||||
],
|
||||
"advisors": [
|
||||
"people/david-brown-187"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,29 +0,0 @@
|
||||
{
|
||||
"slug": "companies/delta-labs-53",
|
||||
"type": "company",
|
||||
"title": "Delta Labs",
|
||||
"compiled_truth": "Delta Labs is a climate tech startup founded in 2021 by [Will Garcia](people/will-garcia-53), who left a senior role at a major energy company to pursue what he calls \"the only problem worth solving.\" The company focuses on direct air capture technology, specifically developing modular units that can be deployed at scale in industrial settings. Their approach differs from competitors by integrating with existing HVAC infrastructure rather than requiring standalone installations.\n\nThe company has attracted notable backing from angel investors including [Wendy Hernandez](people/wendy-hernandez-80) and [Tina Hernandez](people/tina-hernandez-97), both of whom have deep networks in the cleantech space. Delta Labs closed their seed round in late 2022, though exact figures weren't publicly disclosed. Industry insiders estimate somewhere between $4-6M based on hiring patterns and equipment purchases.\n\nOn the advisory side, Delta brought in [Wendy Wilson](people/wendy-wilson-170) for her expertise in regulatory navigation—critical for a company operating in a space where policy can make or break unit economics. [Grace Singh](people/grace-singh-197) rounds out the advisory board, contributing her background in scaling hardware startups through the notorious \"valley of death\" between prototype and production.\n\nDelta's current focus is on their second-generation capture modules, which promise 40% better efficiency than their initial designs. Will Garcia has been particularly vocal about avoiding the hype cycles that have plagued other climate tech ventures, preferring to let results speak. The team has grown to roughly 25 people, mostly engineers with backgrounds in chemical enginering and mechanical systems.\n\nThe company operates out of a converted warehouse in Oakland, where they run continuous testing on their prototype units. Early pilot programs with two Fortune 500 companies are underway, though Delta Labs hasn't named partners publicly. Garcia has mentioned in interviews that revenue isn't the immediate priority—proving the technology works at scale is. Whether that patience will pay off remains to be seen, but the climate tech sector is watching closely.",
|
||||
"timeline": "- **2021-03-15** | Delta Labs incorporated in Delaware by founder [Will Garcia](people/will-garcia-53)\n- **2021-09-02** | First prototype capture unit completed; internal testing begins at Oakland facility\n- **2022-04-18** | [Wendy Hernandez](people/wendy-hernandez-80) joins as lead investor in pre-seed round\n- **2022-11-30** | Seed round closed with participation from [Tina Hernandez](people/tina-hernandez-97) and other angels\n- **2023-02-14** | [Wendy Wilson](people/wendy-wilson-170) announced as regulatory advisor\n- **2023-07-22** | Delta Labs hits 15 employees; opens second testing bay\n- **2024-01-10** | Gen-2 modular unit enters development phase\n- **2024-06-05** | First enterprise pilot program signed (partner undisclosed)\n- **2025-03-28** | Will Garcia speaks at Climate Forward conference on scaling DAC technology\n- **2025-09-12** | Second Fortune 500 pilot announced; team reaches 25 people",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/delta-labs-53",
|
||||
"name": "Delta Labs",
|
||||
"category": "startup",
|
||||
"industry": "climate tech",
|
||||
"founded_year": 2021,
|
||||
"founders": [
|
||||
"people/will-garcia-53"
|
||||
],
|
||||
"investors": [
|
||||
"people/wendy-hernandez-80",
|
||||
"people/tina-hernandez-97"
|
||||
],
|
||||
"employees": [
|
||||
"people/liam-miller-163"
|
||||
],
|
||||
"advisors": [
|
||||
"people/wendy-wilson-170",
|
||||
"people/grace-singh-197"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,30 +0,0 @@
|
||||
{
|
||||
"slug": "companies/drift-31",
|
||||
"type": "company",
|
||||
"title": "Drift",
|
||||
"compiled_truth": "Drift is a developer tools startup founded in 2021 by [Frank Hernandez](people/frank-hernandez-31), who saw an opportunity to streamline the way engineering teams manage configuration drift across distributed systems. The company emerged from Frank's frustration while working at larger tech firms, where he noticed teams spending countless hours debugging issues caused by configuration mismatches between environments.\n\nThe core product offers real-time monitoring and automated remediation for infrastructure configurations, targeting mid-size engineering organizations running complex microservices architectures. Drift's approach differs from traditional configuration managment tools by focusing on detection and alerting rather than enforcement, giving teams flexibility while maintaining visibility. The platform integrates with major cloud providers and works alongside existing CI/CD pipelines.\n\nEarly funding came from a group of angel investors including [Wendy Hernandez](people/wendy-hernandez-80), [Fiona Moore](people/fiona-moore-88), and [Jack Davis](people/jack-davis-89). The diverse investor group brought both capital and operational expertise to the young company. Wendy in particular has been instrumental in connecting Drift with potential enterprise customers through her network.\n\n[Xavier Patel](people/xavier-patel-183) serves as an advisor, bringing deep experience in developer tooling and go-to-market strategy. His guidance helped shape Drift's initial product positioning and pricing model. Xavier pushed the team to focus on a specific use case rather than trying to boil the ocean with features.\n\nThe company operates with a lean team, currently around 15 employees, mostly engineers. They've taken a developer-first approach to sales, offering generous free tiers and building community through open source contributions. Their CLI tool has gained traction on GitHub, serving as a funnel for the commercial product.\n\nDrift has seen steady growth among startups and scale-ups, though breaking into true enterprise accounts remains a challenge. The team is currently working on SOC 2 compliance and additional security features to address enterprise requirements. Competition in the config management space is fierce, but Drift's focused approach has carved out a niche among teams who value simplicity over comprehensiveness.",
|
||||
"timeline": "- **2021-03-15** | Company founded by [Frank Hernandez](people/frank-hernandez-31) after leaving his role at a major cloud provider\n- **2021-06-22** | Closed pre-seed round with participation from [Wendy Hernandez](people/wendy-hernandez-80) and [Fiona Moore](people/fiona-moore-88)\n- **2021-11-08** | Launched private beta with 12 design partner companies\n- **2022-04-03** | [Xavier Patel](people/xavier-patel-183) joined as formal advisor\n- **2022-09-17** | Public launch of Drift CLI tool, gained 2k GitHub stars in first month\n- **2023-02-28** | [Jack Davis](people/jack-davis-89) participated in seed extension round\n- **2023-08-14** | Shipped Kubernetes-native integration, biggest feature release to date\n- **2024-01-22** | Frank spoke at DevOpsDays SF on configuration observability\n- **2024-07-09** | Reached 500 active organizations on the platform\n- **2025-03-11** | Began SOC 2 Type II certification process",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/drift-31",
|
||||
"name": "Drift",
|
||||
"category": "startup",
|
||||
"industry": "developer tools",
|
||||
"founded_year": 2021,
|
||||
"founders": [
|
||||
"people/frank-hernandez-31"
|
||||
],
|
||||
"investors": [
|
||||
"people/wendy-hernandez-80",
|
||||
"people/fiona-moore-88",
|
||||
"people/jack-davis-89",
|
||||
"people/tina-hernandez-97"
|
||||
],
|
||||
"employees": [
|
||||
"people/olivia-garcia-141"
|
||||
],
|
||||
"advisors": [
|
||||
"people/xavier-patel-183"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"slug": "companies/echo-32",
|
||||
"type": "company",
|
||||
"title": "Echo - Robotics Startup",
|
||||
"compiled_truth": "Echo is a robotics startup founded in 2025 by [Helen Johnson](people/helen-johnson-32), a serial entrepreneur with deep expertise in automation and machine learning. The company focuses on developing autonomous robotic systems for warehouse logistics and last-mile delivery, positioning itself at the intersection of AI and physical hardware. Based in Austin, Texas, Echo has quickly gained attention for its modular approach to robot design, allowing clients to customize units for specific operational needs.\n\nThe founding team came together after Helen's previous venture in industrial automation was aquired by a larger player in the space. She saw an opportunity to build something more agile, more responsive to the needs of mid-sized fulfillment centers that couldn't afford the massive infrastructure investments required by legacy robotics providers. Echo's flagship product, the E-1 mobile unit, can navigate complex warehouse environments with minimal setup time.\n\nEarly backing came from angel investors including [Julia Davis](people/julia-davis-86) and [Helen Martinez](people/helen-martinez-87), both of whom have track records in deep tech investments. Julia Davis in particular has been instrumental in connecting Echo with potential enterprise customers through her network in the logistics industry. The company closed a small seed round in early 2025, though exact figures haven't been publicly disclosed.\n\nEcho operates with a lean team of around twelve engineers and has partnered with several contract manufacturers to scale production. The startup has been notably secretive about its technical roadmap, though rumors suggest they're working on swarm coordination protocols that would allow multiple E-1 units to operate collaboratively. Helen Johnson has hinted at plans to expand into agricultural robotics by 2026, leveraging the same core platform.\n\nThe robotics space is crowded, but Echo's emphasis on affordabilty and rapid deployment has resonated with smaller operators who feel underserved by existing solutions. Whether they can maintain this edge as they scale remains to be seen.",
|
||||
"timeline": "- **2024-09-15** | [Helen Johnson](people/helen-johnson-32) begins initial R&D work on modular robotics platform\n- **2025-01-20** | Echo officially incorporated in Austin, Texas\n- **2025-02-08** | [Julia Davis](people/julia-davis-86) commits as lead angel investor\n- **2025-02-14** | [Helen Martinez](people/helen-martinez-87) joins seed round\n- **2025-03-30** | First E-1 prototype completed and demonstrated internally\n- **2025-05-12** | Echo hires VP of Engineering from Boston Dynamics\n- **2025-07-22** | Pilot program launched with regional fulfillment center in Dallas\n- **2025-09-10** | Helen Johnson speaks at RoboWorld Conference on modular design philosophy\n- **2025-11-01** | Company reaches 12 full-time employees",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/echo-32",
|
||||
"name": "Echo",
|
||||
"category": "startup",
|
||||
"industry": "robotics",
|
||||
"founded_year": 2025,
|
||||
"founders": [
|
||||
"people/helen-johnson-32"
|
||||
],
|
||||
"investors": [
|
||||
"people/julia-davis-86",
|
||||
"people/helen-martinez-87"
|
||||
],
|
||||
"employees": [
|
||||
"people/fiona-hernandez-142"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,30 +0,0 @@
|
||||
{
|
||||
"slug": "companies/epsilon-4",
|
||||
"type": "company",
|
||||
"title": "Epsilon",
|
||||
"compiled_truth": "Epsilon is a cybersecurity startup founded in 2021 by [Paul Rodriguez](people/paul-rodriguez-4), a veteran security researcher who previously led threat intelligence teams at two Fortune 500 companies. The company focuses on automated vulnerability detection for cloud-native infrastructure, using machine learning models trained on proprietary datasets of real-world attack patterns.\n\nFrom the begining, Epsilon positioned itself as a developer-first security platform. Rather than bolting security onto existing workflows, the product integrates directly into CI/CD pipelines, scanning code and infrastructure-as-code templates before deployment. This approach resonated with engineering teams frustrated by traditional security tools that generated endless false positives and slowed down releases.\n\nThe company has attracted notable backing from angel investors including [Sarah Lopez](people/sarah-lopez-84), [Sarah Williams](people/sarah-williams-92), and [Kate Lopez](people/kate-lopez-99). Their combined experience in enterprise software and fintech has helped Epsilon navigate early sales cycles with large financial institutions. The advisory board includes [Olivia Miller](people/olivia-miller-176), who brings deep expertise in go-to-market strategy for B2B SaaS, and [Bob Chen](people/bob-chen-185), a respected figure in the open-source security community.\n\nEpsilon's flagship product, ShieldScan, launched in late 2022 and has since been adopted by over 150 organizations. The platform monitors Kubernetes clusters, AWS environments, and Azure deployments in real-time, alerting teams to misconfigurations and potential breach vectors. Recent product updates have added support for GCP and introduced a compliance module targeting SOC 2 and HIPAA requirements.\n\nPaul Rodriguez has been vocal about the need for security tooling that \"meets developers where they are\" rather than imposing rigid workflows. This philosophy has driven Epsilon's product roadmap and contributed to strong word-of-mouth growth among DevOps teams. The company currently employs around 45 people, with engineering and customer success making up the bulk of headcount. Headquarters are in Austin, Texas, though most of the team works remotely.\n\nCompetition in the cloud security space is intense, with well-funded players like Wiz and Lacework dominating mindshare. Epsilon differentiates through pricing transparency and a self-serve model that lets smaller teams get started without lengthy enterprise sales processes.",
|
||||
"timeline": "- **2021-03-15** | Epsilon incorporated in Delaware by [Paul Rodriguez](people/paul-rodriguez-4)\n- **2021-07-22** | Closed $1.2M pre-seed round led by [Sarah Lopez](people/sarah-lopez-84)\n- **2022-01-10** | [Olivia Miller](people/olivia-miller-176) joins advisory board\n- **2022-06-08** | First enterprise customer signed — regional bank in Texas\n- **2022-11-03** | ShieldScan v1.0 publicly launched\n- **2023-04-17** | Epsilon raises $8M seed round; [Kate Lopez](people/kate-lopez-99) participates\n- **2023-09-25** | [Bob Chen](people/bob-chen-185) added as technical advisor\n- **2024-02-12** | Surpassed 100 paying customers milestone\n- **2024-08-30** | Announced GCP integration at CloudSecCon\n- **2025-03-05** | Opened first international office in London",
|
||||
"_facts": {
|
||||
"type": "company",
|
||||
"slug": "companies/epsilon-4",
|
||||
"name": "Epsilon",
|
||||
"category": "startup",
|
||||
"industry": "cybersecurity",
|
||||
"founded_year": 2021,
|
||||
"founders": [
|
||||
"people/paul-rodriguez-4"
|
||||
],
|
||||
"investors": [
|
||||
"people/sarah-lopez-84",
|
||||
"people/sarah-williams-92",
|
||||
"people/kate-lopez-99"
|
||||
],
|
||||
"employees": [
|
||||
"people/julia-johnson-114"
|
||||
],
|
||||
"advisors": [
|
||||
"people/olivia-miller-176",
|
||||
"people/bob-chen-185"
|
||||
]
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user