* security: path traversal, query bounds, marker injection fixes
LocalStorage: contained() method validates all paths stay within storage root.
file-resolver: resolveFile validates filePath within brainRoot, marker prefix
rejects ../, absolute paths, bare '..'. file_list: LIMIT 100 on slug-filtered
branch + FILE_LIST_LIMIT constant for both branches.
Co-Authored-By: Gus <garagon@users.noreply.github.com>
* security: symlink hardening in all file walkers
All 4 walkers in files.ts (collectFiles, findRedirects, findAndClean, scan)
plus init.ts counter now use lstatSync + isSymbolicLink skip. Tests import
production collectFiles instead of reimplementing it. node_modules skipped.
CLI file list and verify queries bounded with LIMIT.
Co-Authored-By: Gus <garagon@users.noreply.github.com>
* feat: typed health check DSL + recipe migration
4 DSL types: http, env_exists, command, any_of. Replaces raw execSync
on recipe YAML. All 7 first-party recipes migrated from shell strings
to typed objects. String health_checks still accepted with deprecation
warning + metachar validation for non-embedded recipes. isUnsafeHealthCheck
blocks shell injection for user-created recipes.
Co-Authored-By: Gus <garagon@users.noreply.github.com>
* chore: bump version and changelog (v0.9.3)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test: E2E test for file_list LIMIT enforcement against real Postgres
Inserts 150 file rows for one slug, verifies file_list returns at most
100 (both slug-filtered and unfiltered branches). Proves the LIMIT
works at the database level, not just in unit tests.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Gus <garagon@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1. statement_timeout: 8s moved from global connection config to
searchKeyword/searchVector only. Prevents DoS on search without
killing embed --all or bulk imports that need longer than 8s.
2. upload-raw now writes the .redirect.yaml pointer file to disk
(was creating the pointer object but never calling writeFileSync).
3. publish inlines marked.js from node_modules instead of loading
from cdn.jsdelivr.net. Generated HTML is now truly self-contained
with no external dependencies.
4. v0.9.1 migration doc updated with slug authority breaking change
warning for brains that use frontmatter slug: overrides.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Anthropic key is optional (graceful fallback), not required
- Remove fragile shell sourcing, add PATH export + restart note
- Integrations: ask user which ones, not "set up EVERY recipe"
- Note gbrain integrations doctor needs at least one configured
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Clone-based install (repo is home base, upgrades via git pull).
Repo URL prominent. API keys called out explicitly. Brain repo vs
tool repo confusion eliminated. Shell compatibility fixed. Cron
jobs named with frequencies. Dream cycle highlighted as the thing
that makes the brain compound.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: battle-tested skill patterns from production deployment
Backport production-learned brain-operations patterns:
- Iron Law of Back-Linking (mandatory bidirectional linking)
- Brain filing rules (file by primary subject, not format)
- Enrichment protocol (7-step pipeline, 3-tier system, person/company templates)
- Media ingest workflows (articles, videos, podcasts, PDFs, screenshots)
- Citation requirements (mandatory [Source: ...] on every fact)
- Test Before Bulk operating principle
- Voice recipe: unicode crash fix, PII scrub, identity-first prompt, DIY STT+LLM+TTS
- X-to-Brain recipe: image OCR, Filtered Stream, tweet rating rubric, cron stagger
* chore: bump version and changelog (v0.8.1)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add _brain-filing-rules.md to CLAUDE.md key files
* feat: smart file upload with TUS resumable and .redirect.yaml pointers
- Supabase Storage auto-selects upload method by file size:
< 100 MB standard POST, >= 100 MB TUS resumable (6 MB chunks + retry)
- Signed URL generation for private bucket access (1-hour expiry)
- New `upload-raw` command with size routing: small text stays in git,
large/media files go to cloud with .redirect.yaml pointer
- New `signed-url` command for generating access links
- File resolver supports both .redirect.yaml (v0.9+) and .redirect (legacy)
- Redirect format upgraded: 10 fields with full metadata
- All migration commands (mirror, redirect, restore, clean) handle both formats
* feat: skills reference actual gbrain file commands
- Filing rules document upload-raw, signed-url, and .redirect.yaml format
- Ingest skill uses gbrain files upload-raw for raw source preservation
- Maintain skill adds file storage health checks
- Setup skill adds storage configuration phase with migration guidance
- Voice recipe uses upload-raw for call audio storage
- Migration v0.9.0 with complete storage setup instructions
* chore: bump version and changelog (v0.9.0)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: gbrain publish -- shareable HTML with password protection
First code+skill pair: deterministic code does the work (strip private data,
encrypt with AES-256-GCM, generate self-contained HTML), the skill tells the
agent when and how to use it. 34 new tests.
See: https://x.com/garrytan/status/2042925773300908103
* feat: backlinks check/fix, page lint, and report commands
Three new deterministic tools (zero LLM calls):
- gbrain backlinks check/fix -- scans brain for entity mentions without
back-links, creates them. Enforces the Iron Law from the skills.
- gbrain lint [--fix] -- catches LLM preambles, code fence wrapping,
placeholder dates, missing frontmatter, broken citations, empty sections.
--fix auto-strips fixable artifacts.
- gbrain report --type <name> -- saves timestamped reports to
brain/reports/{type}/YYYY-MM-DD-HHMM.md for audit trails.
33 new tests (409 total, 0 fail).
* feat: v0.9.0 migration tells agents to swap scripts for built-in commands
Migration file now:
- Lists all 5 new deterministic commands with usage examples
- Includes a script-to-command replacement table (old -> new)
- Tells the agent to find custom script references in AGENTS.md,
skills, and cron jobs and replace with gbrain commands
- Adds recommended cron jobs for daily backlink fix + weekly lint
- References the Thin Harness, Fat Skills thread
* fix: CLI routing bugs found during DX review
- Fixed subArgs reference error in handleCliOnly (used wrong variable name)
- Renamed gbrain backlinks check/fix to gbrain check-backlinks to avoid
conflict with existing backlinks operation (per-page incoming links)
- Added TOOLS section to --help output showing publish, check-backlinks,
lint, report
- Added upload-raw and signed-url to FILES section in --help
- Updated all docs/migration references to use check-backlinks
* fix: security hardening from adversarial review
- XSS: sanitize marked.parse() output (strip script/iframe/on* attrs)
- Path traversal: validate report --type against [a-z0-9-] pattern
- TUS: HEAD request before retry to get server's actual offset (TUS spec)
- Pointer: upload-raw now includes pointer content in JSON output
- Symlinks: use lstatSync in all walkers to prevent directory escape
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
- XSS: sanitize marked.parse() output (strip script/iframe/on* attrs)
- Path traversal: validate report --type against [a-z0-9-] pattern
- TUS: HEAD request before retry to get server's actual offset (TUS spec)
- Pointer: upload-raw now includes pointer content in JSON output
- Symlinks: use lstatSync in all walkers to prevent directory escape
Migration file now:
- Lists all 5 new deterministic commands with usage examples
- Includes a script-to-command replacement table (old -> new)
- Tells the agent to find custom script references in AGENTS.md,
skills, and cron jobs and replace with gbrain commands
- Adds recommended cron jobs for daily backlink fix + weekly lint
- References the Thin Harness, Fat Skills thread
First code+skill pair: deterministic code does the work (strip private data,
encrypt with AES-256-GCM, generate self-contained HTML), the skill tells the
agent when and how to use it. 34 new tests.
See: https://x.com/garrytan/status/2042925773300908103
- Supabase Storage auto-selects upload method by file size:
< 100 MB standard POST, >= 100 MB TUS resumable (6 MB chunks + retry)
- Signed URL generation for private bucket access (1-hour expiry)
- New `upload-raw` command with size routing: small text stays in git,
large/media files go to cloud with .redirect.yaml pointer
- New `signed-url` command for generating access links
- File resolver supports both .redirect.yaml (v0.9+) and .redirect (legacy)
- Redirect format upgraded: 10 fields with full metadata
- All migration commands (mirror, redirect, restore, clean) handle both formats
* chore: remove Supabase Edge Function MCP deployment
The Edge Function never worked reliably. All MCP traffic goes through
self-hosted server + ngrok tunnel. Removes deploy-remote.sh, edge-entry.ts,
supabase/functions/, .env.production.example, and CHATGPT.md (OAuth not
implemented).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: rewrite MCP docs for self-hosted + ngrok deployment
All per-client guides updated from Edge Function URLs to self-hosted
server + ngrok tunnel pattern. DEPLOY.md rewritten with local vs remote
paths. ALTERNATIVES.md now shows self-hosted as primary, with ngrok,
Tailscale, and Fly.io/Railway comparison.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: voice recipe v0.8.0 — 25 production patterns from real deployment
Identity separation, pre-computed bid system, conversation timing fix,
proactive advisor mode, radical prompt compression, OpenAI Realtime
Prompting Guide structure, auth-before-speech, brain escalation, stuck
watchdog, never-hang-up rule, thinking sounds, fallback TwiML, tool set
architecture, trusted user auth, caller routing, dynamic VAD, on-screen
debug UI, live moment capture, belt-and-suspenders post-call, mandatory
3-step post-call, WebRTC parity, dual API events, report-aware query
routing. WebRTC pseudocode updated with native FormData and 6 gotchas.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: post-upgrade feature discovery framework
upgrade.ts captures old version before upgrading, then execs
gbrain post-upgrade (new binary) to read migration files and print
feature pitches. Migration files get YAML frontmatter with feature_pitch
field (headline, description, recipe, tiers). CLI prints excited builder
tone post-upgrade. v0.8.0 migration offers voice setup with environment
detection (server vs local) and 3-tier progressive disclosure.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add Voice section to README with WebRTC screenshot + tweet link
Her out of the box: voice-to-brain with 25 production patterns. WebRTC
client screenshot embedded. Remote MCP section rewritten for self-hosted
+ ngrok. Setup block genericized.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: add recipe validation tests + genericize personal refs
5 new integration tests: secrets completeness, semver version, requires
resolution, all-recipes-parse, no-personal-references. Test fixture
genericized. CLAUDE.md/TODOS.md/SKILLPACK updated for v0.8.0. build:edge
script removed from package.json.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v0.8.0)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
GBrain needs a persistent agent for cron jobs, background sync, and
dream cycles. Claude Code is session-based so those features won't
work. Recommending it leads to a bad first experience.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: extract shared utils, add runMigration + getChunksWithEmbeddings to BrainEngine
Extract validateSlug, contentHash, rowToPage, rowToChunk, rowToSearchResult
from postgres-engine.ts into shared utils.ts. Add rowToChunk includeEmbedding
parameter for migration support.
Add two new methods to BrainEngine interface:
- runMigration(version, sql) — replaces internal eng.sql access in migrate.ts
- getChunksWithEmbeddings(slug) — returns chunks with embedding data for migration
Replace 'sqlite' with 'pglite' in EngineConfig and GBrainConfig types.
Fix loadConfig to infer engine from database_path.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: pluggable engine factory + hybridSearch keyword-only fallback
Add createEngine() factory with dynamic imports so PGLite WASM is never
loaded for Postgres users. Wire CLI to use factory instead of hardcoded
PostgresEngine.
Force workers=1 for PGLite imports (single-connection architecture).
Fix hybridSearch to check OPENAI_API_KEY before calling embed(). When
unset, returns keyword-only results instead of throwing. Critical for
local PGLite users who don't need vector search.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: PGLiteEngine — embedded Postgres 17.5 via WASM, same SQL everywhere
Full BrainEngine implementation (37 methods) using @electric-sql/pglite.
Same SQL as PostgresEngine — tsvector triggers, pgvector HNSW, pg_trgm
fuzzy matching, recursive CTEs, JSONB. Only the driver call syntax differs
(parameterized queries instead of tagged templates).
PGLite schema is the Postgres schema minus RLS, advisory locks, and
remote auth tables (access_tokens, mcp_request_log, files).
No server. No subscription. One directory. Works offline.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: smart init (PGLite default) + bidirectional engine migration
gbrain init now defaults to PGLite — brain ready in 2 seconds, no
server needed. Scans target directory: <1000 .md files = PGLite,
>=1000 = suggests Supabase. --supabase and --pglite flags override.
gbrain migrate --to supabase/pglite transfers all data between engines
with manifest-based resume. Copies pages, chunks (with embeddings),
tags, timeline, raw data, links, and config. --force overwrites
non-empty target.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: 60 new tests for PGLite engine, utils, and factory
41 PGLite engine tests covering all 37 BrainEngine methods: CRUD,
tsvector keyword search, pg_trgm fuzzy matching, chunk upsert with
COALESCE, graph traversal via recursive CTE, transactions, cascade
deletes, stats/health, and embedding round-trip.
14 shared utility tests (validateSlug, contentHash, row mappers).
5 engine factory tests (dispatch, error messages).
All run in-memory — zero Docker, zero DATABASE_URL, instant in CI.
Add P0 TODO: submit Bun PR for WASM embedding in bun build --compile
(oven-sh/bun#15032).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v0.7.0)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: update project documentation for v0.7.0 PGLite engine
- CLAUDE.md: add PGLite key files, update architecture, add migrate command, add 3 test files
- README.md: PGLite as default init, zero-config getting started, migration path to Supabase
- docs/ENGINES.md: PGLiteEngine shipped (v0.7), capability matrix, migration docs
- docs/SQLITE_ENGINE.md: marked superseded by PGLite
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: remove stale v0.4 README update prompt
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: remove SQLITE_ENGINE.md (superseded by PGLite)
PGLite uses the same SQL as Postgres, making a separate SQLite
engine unnecessary. docs/ENGINES.md covers PGLiteEngine.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: update README step 2 to default to PGLite
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add schema setup step and install-all-integrations step to README
Step 3 now tells agents to read GBRAIN_RECOMMENDED_SCHEMA.md and set up
the MECE directory structure before importing. Step 7 tells agents to
install every available integration recipe, not just list them.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: update install goal to match full opinionated setup
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add 'Need an AI agent first?' section with one-click deploy links
New users who don't have OpenClaw or Hermes Agent get pointed to
AlphaClaw on Render and the Hermes Agent Railway template. One click
each. Claude Code mentioned for users who already have it.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: add migrate to CLI_ONLY + help output, fix standalone example
- migrate command was missing from CLI_ONLY set (errored as "Unknown command")
- migrate now shows in --help under SETUP
- init help line shows --pglite flag
- standalone CLI example uses gbrain init (not --supabase)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: set realistic time expectation (~30 min to working brain)
DB is 2 seconds. But schema + import + embeddings + integrations
is 15-30 minutes. The agent does the work, you answer API key
questions. Don't oversell time-to-value.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix AlphaClaw Render requirement (8GB+ RAM, not free tier)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: final README polish for launch
- GOAL line: "Garry Tan's exact setup" (not Claude Code specific)
- Remove markdown links from code block (won't render)
- STEP 2 renamed from "START HERE" to "DATABASE"
- Tighten Supabase fallback text
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: remove duplicate old install block from README
The v0.5-era "With OpenClaw or Hermes Agent" paste block was
superseded by the top-level "Start here" block. Having both
confused users and the old one still said --supabase as step 2.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: clean up README consistency and remove duplicated content
- Remove duplicate "Try it" section (old 4-act walkthrough that
repeated the install flow and contradicted "~30 min" with "90 sec")
- Remove duplicate Setup section (third repetition of gbrain init)
- Fix brain.db → brain.pglite (actual default path)
- Fix "coming in v0.7" → "not yet implemented" (we ARE v0.7)
- Remove "You don't need Postgres" (confusing since PGLite IS Postgres)
- Deduplicate "competitive dynamics" query (appeared 3 times)
- Collapse redundant standalone CLI section
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: break SKILLPACK into 17 individual guides
The 1,281-line SKILLPACK monolith is now 17 individually linkable guides
in docs/guides/, organized by category: core patterns, data pipelines,
operations, search, and administration.
GBRAIN_SKILLPACK.md becomes a structured index with categorized tables
linking to each guide. The URL stays stable for backward compatibility.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add integration guides, architecture docs, and ethos
New documentation directories:
- docs/integrations/ — "Getting Data In" landing page, credential gateway,
meeting webhooks. Includes recipe format documentation.
- docs/architecture/ — Infrastructure layer doc (import, chunk, embed, search)
- docs/ethos/ — "Thin Harness, Fat Skills" essay with agent decision guide
- docs/designs/ — "Homebrew for Personal AI" 10-star vision document
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add gbrain integrations command + voice-to-brain recipe
New CLI command: gbrain integrations (list/show/status/doctor/stats/test)
- Standalone command, no database connection needed
- Uses gray-matter directly for recipe parsing (not parseMarkdown)
- --json flag on every subcommand for agent-parseable output
- Bare command shows senses/reflexes dashboard
- Health heartbeat via ~/.gbrain/integrations/<id>/heartbeat.jsonl
First recipe: recipes/twilio-voice-brain.md
- Phone calls create brain pages via Twilio + OpenAI Realtime
- Opinionated defaults: caller screening, brain-first lookup, quiet hours
- Outbound call smoke test (GBrain calls the user to prove it works)
- Validate-as-you-go credential testing
- Twilio signature validation for webhook security
Migration file for v0.7.0 with agent-readable changelog.
13 unit tests covering parseRecipe, CLI routing, and recipe validation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add Getting Data In to README, update CLAUDE.md and manifest
README: voice calls in intro bullet list, new "Getting Data In" section
with integration table (voice, email, X, calendar) and recipe philosophy.
CLAUDE.md: reference new files (integrations.ts, recipes/, docs/guides/,
docs/integrations/, docs/architecture/, docs/ethos/).
manifest.json: bump to v0.7.0, add recipes_dir field.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: v0.7.0 CHANGELOG, TODOS, VERSION bump
CHANGELOG: v0.7.0 entry covering integration recipes, voice-to-brain,
gbrain integrations command, SKILLPACK breakout, and new documentation.
TODOS: 3 new items from CEO/DX reviews (constrained health_check DSL,
community recipe submission, always-on deployment recipes).
VERSION + package.json: bump to 0.7.0.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: rewrite voice recipe with agent instructions and verified links
Major improvements to recipes/twilio-voice-brain.md:
- Agent preamble: explains WHY sequential execution matters (each step
depends on the previous), defines 4 stop points where the agent MUST
pause and verify, tells agent to never say "something went wrong"
but instead explain the exact error and fix
- User actions are now specific: exact URLs for every credential
(Twilio console, OpenAI API keys page, ngrok dashboard), what
buttons to click, what fields to copy, common failure modes
- All URLs verified via web search against current 2026 documentation:
Twilio SID/token at twilio.com/console, OpenAI keys at
platform.openai.com/api-keys, ngrok token at
dashboard.ngrok.com/get-started/your-authtoken
- Cost estimate corrected: OpenAI Realtime is $0.06/min input +
$0.24/min output (was understated), total ~$20-22/mo for 100 min
- Validate-as-you-go: each credential tested immediately with exact
curl commands, failure messages explain what went wrong and how to fix
- Smoke test flow: tells user exactly what to say, verifies ALL
three outputs (messaging notification + brain page + search result)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add "Homebrew for Personal AI" essay (markdown is code)
New essay at docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md — the distribution
corollary to "Thin Harness, Fat Skills." Argues that markdown skill files
are simultaneously documentation, specification, package, and source code.
The agent is the package manager. The git repo is the app store.
Referenced from SKILLPACK index and CLAUDE.md.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: rewrite agent instructions as command language, promote skills
The OpenClaw/Hermes install block is now a drill sergeant, not a tour guide.
Every step is an imperative command with exact verification criteria and
explicit stop-on-failure behavior. No FYI, no suggestions, just rails.
Key changes:
- 11-step setup with STOP points after each step
- Exact user instructions for Supabase connection string (what to click,
what NOT to give the agent, what the string looks like)
- "Verify: run X. You must see Y. If not: Z" after every step
- Skills table now links to both skill files AND guide docs
- Integration recipes table simplified (no "coming soon" placeholders)
- Docs section reorganized: for agents / for humans / reference
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: 4 codex findings + add email-to-brain recipe
Codex review found 4 issues, all fixed:
1. getStatus() returned "configured" if ANY secret was set (e.g. just
OPENAI_API_KEY). Now requires ALL required secrets before marking
configured. Prevents false "configured" status and spurious doctor runs.
2. Twilio health check hit unauthenticated endpoint (always 401). Now
uses authenticated curl with SID:token, matching the setup validation.
3. README anchor docs/GBRAIN_SKILLPACK.md#the-dream-cycle broken after
SKILLPACK rewrite. Updated to point to docs/guides/cron-schedule.md.
4. Compiled binary can't find recipes/ via import.meta.dir. Added
GBRAIN_RECIPES_DIR env var override + global bun install path fallback.
Also adds recipes/email-to-brain.md: Gmail deterministic collector pattern
with ClawVisor credential gateway, validate-as-you-go, agent instructions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add email, X, calendar, and meeting sync recipes
Four new integration recipes extracted from production wintermute patterns:
- recipes/email-to-brain.md: Gmail via ClawVisor, deterministic collector
pattern (code pulls emails with baked-in links, agent does judgment),
noise filtering, signature detection, digest generation
- recipes/x-to-brain.md: X API v2, timeline + mentions + keyword search,
deletion detection (diffs previous run, verifies 404), engagement
velocity tracking, rate limit awareness
- recipes/calendar-to-brain.md: Google Calendar via ClawVisor, historical
backfill (years of data), daily markdown files with attendees + locations,
attendee enrichment for brain pages
- recipes/meeting-sync.md: Circleback API, transcript import with speaker
labels, attendee detection + filtering, entity propagation to people/
company pages, action item extraction, idempotent by source_id
All recipes follow the same format: agent preamble with sequential execution
rules, validate-as-you-go credentials, exact URLs for API key setup,
stop-on-failure verification, and heartbeat logging.
Updated README, SKILLPACK index, and integrations landing page with all 5 recipes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add Google OAuth as alternative to ClawVisor in email + calendar recipes
Both recipes now offer two auth options:
- Option A: ClawVisor (recommended, handles OAuth + token refresh)
- Option B: Google OAuth2 directly (no extra service, you manage tokens)
Option B includes step-by-step instructions for Google Cloud Console:
exact URLs, which buttons to click, which scopes to add, how to enable
the API, and the OAuth flow for token exchange.
This removes ClawVisor as a hard dependency for getting started.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add implementation guides with pseudocode and test suggestions
Every recipe now includes an "Implementation Guide" section with:
- Production-tested pseudocode the agent can follow to build each collector
- Edge cases and failure modes discovered in real deployment
- Non-obvious implementation details (why the 48h staleness heuristic,
why Gmail links need authuser, why SSE responses need double-parsing)
- Test suggestions: what the agent should verify after setup
email-to-brain: noise filtering algorithm, signature detection patterns,
Gmail link generation (authuser is critical), sent-mail dedup
x-to-brain: deletion detection with 3 heuristics (7-day, 48h staleness,
API verification), engagement velocity thresholds (50 min for 2x, 100
absolute jump), atomic writes, stdout contract, rate limit handling
calendar-to-brain: smart chunking (monthly for sparse years, weekly for
dense), attendee filtering (rooms, groups, distros), merge-with-existing
(only replace ## Calendar section), date/time parsing edge cases
meeting-sync: SSE double-JSON parsing, idempotency double-check (grep +
filename), auto-tagging from meeting names, git commit after sync
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: 6 new guides from production patterns (wintermute extraction)
New guides extracted and generalized from production deployment:
- repo-architecture.md: Two-repo pattern (agent behavior vs world knowledge).
Strict boundary rules, decision tree, hard rule: never write knowledge
to the agent repo.
- sub-agent-routing.md: Model routing table by task type. Signal detector
pattern (spawn Sonnet on every message). Research pipeline pattern
(Opus plans, DeepSeek executes, Opus synthesizes). Cost optimization.
- skill-development.md: 5-step cycle (concept, prototype, evaluate, codify,
cron). MECE discipline (no overlapping skills). Quality bar checklist.
"If you ask twice, it should already be a skill."
- idea-capture.md: Originality distribution rating (0-100 across 4
populations). Depth test ("could someone unfamiliar understand WHY?").
Deep cross-linking mandate. Notability filtering.
- quiet-hours.md: Hold notifications 11pm-8am local time. Held messages
directory pattern. Timezone-aware delivery. Morning briefing pickup.
- diligence-ingestion.md: 9-step pipeline for data room materials. Detection
patterns (PDF filenames, spreadsheet tabs, user language). Index.md
template with bull/bear case. Company page enrichment.
All PII scrubbed. Patterns generalized for any user.
SKILLPACK index updated with 6 new entries. CLAUDE.md references added.
All 37 SKILLPACK links verified.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: upgrade all guides to operational playbooks with pseudocode
Every guide now follows the playbook structure:
- Goal: one sentence, what this achieves
- What the User Gets: without this / with this
- Implementation: pseudocode with actual gbrain commands
- Tricky Spots: production-tested gotchas
- How to Verify: test steps the agent runs after setup
Guides upgraded (15 files):
- brain-agent-loop: on_message() loop with read/write/sync pseudocode
- brain-first-lookup: 4-step lookup cascade with exact commands
- brain-vs-memory: routing algorithm for 3 knowledge layers
- compiled-truth: page structure + rewrite vs append rules
- content-media: 3 ingest patterns (YouTube, social, PDFs)
- cron-schedule: full schedule table + dream cycle pseudocode
- enrichment-pipeline: 7-step protocol with tier classification
- entity-detection: spawn pattern + detection prompt + notability filter
- executive-assistant: 3 workflow algorithms (triage, prep, post-inbox)
- meeting-ingestion: 6-step transcript-to-brain flow
- operational-disciplines: 5 executable discipline blocks
- originals-folder: detection + exact-phrasing capture + cross-linking
- search-modes: decision tree for keyword vs hybrid vs direct
- source-attribution: citation format + hierarchy + conflict resolution
- Plus Goal/What User Gets headers on 6 newer guides
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add WebRTC to voice recipe + ngrok Hobby setup guide
Voice recipe updates:
- Added WebRTC endpoint (POST /session, GET /call, POST /tool) for
browser-based calling with RNNoise noise suppression
- WebRTC pseudocode with the 4 non-obvious gotchas from production
(voice under audio.output.voice, no turn_detection, no session.update
on connect, trigger greeting via data channel)
- Recommend ngrok Hobby ($8/mo) for fixed domain instead of free tier
- Fixed domain means URLs never change, Twilio never breaks
New guide: docs/mcp/NGROK_SETUP.md
- How to set up ngrok Hobby for both MCP and voice agent
- Fixed domain setup, watchdog pattern, AI client configuration
- Claude Desktop requires Settings > Integrations (not JSON config)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add dependency graph + ngrok-tunnel + credential-gateway recipes
Recipes now have real dependencies via the `requires` field:
- voice-to-brain requires ngrok-tunnel (needs public URL for Twilio)
- email-to-brain requires credential-gateway (needs Gmail access)
- calendar-to-brain requires credential-gateway (needs Calendar access)
- x-to-brain and meeting-sync are standalone (direct API keys)
Two new infrastructure recipes:
- ngrok-tunnel: fixed public URL for MCP + voice. Recommends Hobby
($8/mo) for a domain that never changes. Includes watchdog pattern.
- credential-gateway: secure Google service access via ClawVisor
(recommended) or direct OAuth2. One setup, all Google recipes use it.
Moved ngrok from docs/mcp/ to recipes/ — it's shared infrastructure,
not MCP-specific.
README and integrations landing page show dependency chains.
When agent installs voice-to-brain, it sets up ngrok-tunnel first.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: add infra category, fix dashboard alignment, show dependencies
DX audit found two bugs in gbrain integrations dashboard:
1. Column alignment broken — IDs > 18 chars ran into descriptions
with no space. Fixed: pad to 22 chars.
2. ngrok-tunnel and credential-gateway showed as SENSES but they're
infrastructure. Added 'infra' category. Dashboard now shows three
sections: INFRASTRUCTURE (set up first), SENSES, REFLEXES.
3. Dependencies now shown inline: "AVAILABLE (needs credential-gateway)"
Also added 'requires' field to JSON output for agent consumption.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add frontier model requirement disclaimer to README
GBrain's markdown-is-code approach requires models capable of
interpreting intent and implementing from architecture descriptions.
Tested with Claude Opus 4.6 and GPT-5.4 Thinking. Smaller models
will struggle with the recipe format.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add PGLite → Supabase upgrade path to README
Clarify the database progression: start with PGLite (Postgres as WASM,
zero infrastructure, pgvector built in, nothing to install). Graduate
to Supabase or self-hosted Postgres when you need connection pooling,
concurrency, and remote MCP access from Claude Desktop, Cowork,
ChatGPT, Perplexity Computer, or any MCP-compatible agent.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: revert PGLite mention (coming in next branch)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: make all 23 guides consistent (Goal/Impl/Tricky/Verify)
Every guide now has exactly these sections in this order:
- ## Goal (one sentence)
- ## What the User Gets (without this / with this)
- ## Implementation (pseudocode with gbrain commands)
- ## Tricky Spots (3-5 numbered gotchas)
- ## How to Verify (3-5 numbered test steps)
11 guides restructured from non-standard headings:
- deterministic-collectors, live-sync, upgrades-auto-update (full rewrites)
- entity-detection, diligence-ingestion, idea-capture, quiet-hours,
repo-architecture, skill-development, sub-agent-routing (restructured)
23/23 guides now pass consistency audit.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: restructure README around the #1 blocker (getting data in)
The README was leading with Postgres and database architecture. Most
users are stuck at step zero: "I have an agent but it doesn't know
anything about my life."
New structure:
1. The Problem — your agent doesn't know your life
2. Getting Data In — integration recipes, front and center
3. The Compounding Thesis — why this matters
4. How this happened — credibility, origin story
5. When you need Postgres — scale, not starting point
Postgres is de-emphasized from a full section to two paragraphs:
"You don't need Postgres to start" and "When you need Postgres"
(1,000+ files, remote MCP access, multiple AI clients).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: move Install to top of README, remove duplicate section
Install now appears right after Getting Data In (line 38), not buried
at line 295. The user sees: Problem → Getting Data In → Install.
Removed the duplicate Install section (262 lines) that was lower in
the README. The agent instructions block, CLI quickstart, and all
content is now in the single Install section near the top.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: move agent install block to first thing in README
"Start here: paste this into your agent" is now the first section,
right after the one-line pitch. No scrolling, no context, no preamble.
User opens the README, sees the paste block, copies it into OpenClaw
or Hermes, and the agent takes over.
Flow: pitch → paste block → Getting Data In → Compounding Thesis → origin story
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: compress install block from 11 steps to 5
The agent install block was 102 lines and 11 steps. Now it's 40 lines
and 5 steps. Same coverage, half the text.
Changes:
- Merged "prove keyword search" + "embed" + "prove hybrid search"
into one SEARCH step (the user doesn't care about the intermediate)
- Merged skillpack, sync, auto-update, integrations, verification
into one GO LIVE step with sub-items (post-install polish, not install)
- Shortened database instructions (one line instead of 5 sub-steps)
- Removed redundant preamble ("YOU MUST COMPLETE EVERY STEP" is now
just "Do not skip steps. Verify each step.")
The 5 steps: INSTALL → DATABASE → IMPORT → SEARCH → GO LIVE
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* security: gitignore all .env files, not just specific ones
CSO audit found .gitignore covered .env.testing and .env.production
but not bare .env. A user creating .env with database credentials
could accidentally commit it.
Fix: .env and .env.* are now gitignored. .env.*.example files are
explicitly un-ignored so templates remain tracked.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* security: scrub PII from essay and recipe examples
- 510-MY-GARRY phone mnemonic → "Your Phone Number"
- "Garry → Authenticated Mode" → "Owner → Authenticated Mode"
- "Telegram" → "secure channel" in auth example
- @garrytan → @yourhandle in X recipe example
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: validateSlug accepts ellipsis filenames, rejects only real path traversal
Changed regex from /\.\./ to /(^|\/)\.\.($|\/)/ so filenames with "..." (like
YouTube transcripts, TED talks, podcast titles) are no longer falsely rejected.
The old regex matched ".." anywhere as a substring. The new one only matches ".."
as a complete path component (e.g., ../foo, foo/../bar, bare ..).
Fixes 1.2% silent data loss on real-world import corpora.
Co-Authored-By: orendi84 <orendi84@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: import walker skips node_modules, handles broken symlinks, supports .mdx
Three improvements to the file walker:
- Skip node_modules directories (prevents crashes importing JS/TS projects)
- try/catch around statSync for broken symlinks (warns and continues)
- Accept .mdx files alongside .md (extends to slugifyPath and isSyncable)
Co-Authored-By: mattbratos <mattbratos@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: init exits cleanly, auto-creates pgvector, updates Supabase UI hint
Three init improvements:
- process.stdin.pause() after reading URL input (prevents event loop hang)
- Auto-run CREATE EXTENSION IF NOT EXISTS vector with fallback message
- Update Supabase session pooler navigation hint to match current dashboard UI
Co-Authored-By: changergosum <changergosum@users.noreply.github.com>
Co-Authored-By: eric-hth <eric-hth@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* perf: parallelize keyword search with embedding pipeline
Run keyword search concurrently with the embed+vector pipeline instead of
sequentially. Keyword search has no embedding dependency so it can overlap
with the OpenAI API call, saving ~200-500ms per search.
Co-Authored-By: irresi <irresi@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update Hermes Agent link to NousResearch GitHub repo
Co-Authored-By: howardpen9 <howardpen9@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add community PR wave process to CLAUDE.md
Documents the fix wave workflow: categorize, deduplicate, collector branch,
test, close with context, ship as one PR with attribution.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: bump version and changelog (v0.6.1)
Community fix wave: 9 PRs re-implemented with full test coverage.
6 bug fixes, 1 perf improvement, 2 feature additions, 8 contributors.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: migrate gstack from vendored to team mode
Remove vendored .claude/skills/gstack/ from git tracking. The global install
at ~/.claude/skills/gstack/ is the source of truth. Each developer runs
`cd ~/.claude/skills/gstack && ./setup` to set up symlink stubs locally.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: untrack skill symlink stubs
These are generated locally by gstack's ./setup script. Not project code.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: credit community contributors in CHANGELOG
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update OpenClaw links from .com to .ai
openclaw.com is a parked page. openclaw.ai is the real product.
Co-Authored-By: joshua-morris <joshua-morris@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: orendi84 <orendi84@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: mattbratos <mattbratos@users.noreply.github.com>
Co-authored-by: changergosum <changergosum@users.noreply.github.com>
Co-authored-by: eric-hth <eric-hth@users.noreply.github.com>
Co-authored-by: irresi <irresi@users.noreply.github.com>
Co-authored-by: howardpen9 <howardpen9@users.noreply.github.com>
Co-authored-by: joshua-morris <joshua-morris@users.noreply.github.com>
Map all externalized bare imports (anthropic, aws-sdk, gray-matter, child_process)
and MCP SDK subpath imports to explicit npm:/node: specifiers for Deno compatibility.
* fix: 7 bug fixes from Issue #9 and #22
- fix(mcp): use ListToolsRequestSchema/CallToolRequestSchema instead of string literals (Issue #9, PR #25)
- fix(mcp): handleToolCall reads dry_run from params instead of hardcoding false (#22 Bug #11)
- fix(search): keyword search returns best chunk per page via DISTINCT ON, not all chunks (#22 Bug #8)
- fix(search): dedup layer 1 keeps top 3 chunks per page instead of collapsing to 1 (#22 Bug #12)
- fix(engine): transaction uses scoped engine via Object.create, no shared state mutation (#22 Bug #2)
- fix(engine): upsertChunks uses UPSERT instead of DELETE+INSERT, preserves existing embeddings (#22 Bug #1)
- fix(slugs): validateSlug normalizes to lowercase, pathToSlug lowercases consistently (#22 Bug #4)
- schema: add unique index on content_chunks(page_id, chunk_index) for UPSERT support
- schema: add access_tokens and mcp_request_log tables via migration
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: embed schema.sql at build time, remove fs dependency from initSchema
initSchema() previously read schema.sql from disk at runtime via readFileSync,
which broke in compiled Bun binaries and Deno Edge Functions. Now uses a
generated schema-embedded.ts constant (run `bun run build:schema` to regenerate).
- Removes fs and path imports from postgres-engine.ts and db.ts
- Adds scripts/build-schema.sh for one-source-of-truth generation
- Adds build:schema npm script
Fixes Issue #22 Bug #6.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: 5 more bug fixes from Issue #22
- fix(file_upload): call storage.upload() in all 3 paths (operation, CLI upload, CLI sync) with rollback semantics (#22 Bug #9)
- fix(import): use atomic index counter for parallel queue instead of array.shift() race, preserve checkpoint on errors (#22 Bug #3)
- fix(s3): replace unsigned fetch with @aws-sdk/client-s3 for proper SigV4 auth, supports R2/MinIO via forcePathStyle (#22 Bug #10)
- fix(redirect): verify remote file exists before deleting local copy, skip files not found in storage (#22 Bug #5)
- deps: add @aws-sdk/client-s3
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: remote MCP server via Supabase Edge Functions
Deploy GBrain as a serverless remote MCP endpoint on your existing Supabase
instance. One brain, accessible from Claude Desktop, Claude Code, Cowork,
Perplexity Computer, and any MCP client. Zero new infrastructure.
New files:
- supabase/functions/gbrain-mcp/index.ts — Edge Function with Hono + MCP SDK
- supabase/functions/gbrain-mcp/deno.json — Deno import map
- src/edge-entry.ts — curated bundle entry point (excludes fs-dependent modules)
- src/commands/auth.ts — standalone token management (create/list/revoke/test)
- scripts/deploy-remote.sh — one-script deployment
- .env.production.example — 3-value config template
Changes:
- config.ts: lazy-evaluate CONFIG_DIR (no homedir() at module scope)
- schema.sql: add access_tokens + mcp_request_log tables
- package.json: add build:edge script
Auth: bearer tokens via access_tokens table (SHA-256 hashed, per-client, revocable)
Transport: WebStandardStreamableHTTPServerTransport (stateless, Streamable HTTP)
Health: /health endpoint (unauth: 200/503, auth: postgres/pgvector/openai checks)
Excluded from remote: sync_brain, file_upload (may exceed 60s timeout)
Setup: clone, fill .env.production, run scripts/deploy-remote.sh, create token, done.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: per-client MCP setup guides
- docs/mcp/DEPLOY.md — deployment walkthrough, auth, troubleshooting, latency table
- docs/mcp/CLAUDE_CODE.md — claude mcp add command
- docs/mcp/CLAUDE_DESKTOP.md — Settings > Integrations (NOT JSON config!)
- docs/mcp/CLAUDE_COWORK.md — remote + local bridge paths
- docs/mcp/PERPLEXITY.md — Perplexity Computer connector setup
- docs/mcp/CHATGPT.md — coming soon (requires OAuth 2.1, P0 TODO)
- docs/mcp/ALTERNATIVES.md — Tailscale Funnel + ngrok self-hosted options
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v0.6.0)
GBrain v0.6.0: Remote MCP server via Supabase Edge Functions + 12 bug fixes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add Remote MCP Server section to README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: make document-release mandatory in CLAUDE.md, add MCP key files
Post-ship requirements section: document-release is NOT optional. Lists every
file that must be checked on every ship. A ship without updated docs is incomplete.
Also adds remote MCP server files to Key files section.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: batch upsertChunks into single statement to prevent deadlocks
The per-chunk UPSERT loop caused deadlocks under parallel workers because
each INSERT ON CONFLICT acquired row-level locks sequentially. Multiple
workers upserting different pages could deadlock on the shared unique index.
Fix: batch all chunks into a single multi-row INSERT ON CONFLICT statement.
One round-trip, one lock acquisition. COALESCE preserves existing embeddings
when the new value is NULL.
Fixes CI failure: "E2E: Parallel Import > parallel import with --workers 4"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: advisory lock in initSchema() prevents deadlock on concurrent DDL
When multiple processes call initSchema() concurrently (e.g., test setup +
CLI subprocess, or parallel workers during E2E tests), the schema SQL's
DROP TRIGGER + CREATE TRIGGER statements acquire AccessExclusiveLock on
different tables, causing deadlocks.
Fix: pg_advisory_lock(42) serializes all initSchema() calls within the
same database. The lock is session-scoped and released in a finally block.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: add explicit test timeouts for CLI subprocess E2E tests
CLI subprocess tests (Setup Journey, Doctor Command, Parallel Import)
spawn `bun run src/cli.ts` which takes several seconds to JIT compile +
connect. The Bun test framework default 5000ms per-test timeout is too
tight for CI. Added 30-60s timeouts matching each subprocess's own
timeout to prevent false failures.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: infinite recursion in config.ts exported getConfigDir/getConfigPath
The replace_all refactor created recursive functions: the exported
getConfigDir() called the private getConfigDir() which called itself.
Renamed exports to configDir()/configPath() to avoid shadowing.
Also adds scripts/smoke-test-mcp.ts — verified all 8 MCP tool calls
work against a real Postgres database.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The replace_all refactor created recursive functions: the exported
getConfigDir() called the private getConfigDir() which called itself.
Renamed exports to configDir()/configPath() to avoid shadowing.
Also adds scripts/smoke-test-mcp.ts — verified all 8 MCP tool calls
work against a real Postgres database.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CLI subprocess tests (Setup Journey, Doctor Command, Parallel Import)
spawn `bun run src/cli.ts` which takes several seconds to JIT compile +
connect. The Bun test framework default 5000ms per-test timeout is too
tight for CI. Added 30-60s timeouts matching each subprocess's own
timeout to prevent false failures.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When multiple processes call initSchema() concurrently (e.g., test setup +
CLI subprocess, or parallel workers during E2E tests), the schema SQL's
DROP TRIGGER + CREATE TRIGGER statements acquire AccessExclusiveLock on
different tables, causing deadlocks.
Fix: pg_advisory_lock(42) serializes all initSchema() calls within the
same database. The lock is session-scoped and released in a finally block.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Resolved conflicts:
- VERSION: keep 0.6.0
- CHANGELOG.md: keep both 0.6.0 and 0.5.1 entries in order
- src/core/migrate.ts: renumber migrations (master's v2 slugify first, then v3 unique_chunk_index, v4 access_tokens)
- test/sync.test.ts: keep our test name ('normalizes to lowercase')
* feat: slugify file paths with spaces and special characters
Apple Notes files (e.g., "2017-05-03 ohmygreen.md") now get clean,
URL-safe slugs instead of raw filenames with spaces. Spaces become
hyphens, special chars are stripped, accented chars normalize to ASCII.
Both import (inferSlug) and sync (pathToSlug) pipelines now use the
same slugifyPath() function, eliminating the case-preservation mismatch.
* feat: one-time migration to slugify existing page slugs
Extends Migration interface with optional TypeScript handler for
application-level data transformations. Adds version 2 migration that
renames all existing slugs to their slugified form, including link
rewriting. Collision handling via try/catch + warning.
* test: slugify unit tests, E2E tests, and updated expectations
22 new unit tests for slugifySegment and slugifyPath covering spaces,
special chars, unicode, dots, empty segments, and all 4 bug report
examples. Updated pathToSlug tests for new lowercase behavior. Updated
E2E tests for slugified Apple Notes slugs. Added 2 new E2E tests for
space-named file import and sync.
* chore: bump version and changelog (v0.5.1)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: fix changelog example to show directory with spaces
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The per-chunk UPSERT loop caused deadlocks under parallel workers because
each INSERT ON CONFLICT acquired row-level locks sequentially. Multiple
workers upserting different pages could deadlock on the shared unique index.
Fix: batch all chunks into a single multi-row INSERT ON CONFLICT statement.
One round-trip, one lock acquisition. COALESCE preserves existing embeddings
when the new value is NULL.
Fixes CI failure: "E2E: Parallel Import > parallel import with --workers 4"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Post-ship requirements section: document-release is NOT optional. Lists every
file that must be checked on every ship. A ship without updated docs is incomplete.
Also adds remote MCP server files to Key files section.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- fix(file_upload): call storage.upload() in all 3 paths (operation, CLI upload, CLI sync) with rollback semantics (#22 Bug #9)
- fix(import): use atomic index counter for parallel queue instead of array.shift() race, preserve checkpoint on errors (#22 Bug #3)
- fix(s3): replace unsigned fetch with @aws-sdk/client-s3 for proper SigV4 auth, supports R2/MinIO via forcePathStyle (#22 Bug #10)
- fix(redirect): verify remote file exists before deleting local copy, skip files not found in storage (#22 Bug #5)
- deps: add @aws-sdk/client-s3
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
initSchema() previously read schema.sql from disk at runtime via readFileSync,
which broke in compiled Bun binaries and Deno Edge Functions. Now uses a
generated schema-embedded.ts constant (run `bun run build:schema` to regenerate).
- Removes fs and path imports from postgres-engine.ts and db.ts
- Adds scripts/build-schema.sh for one-source-of-truth generation
- Adds build:schema npm script
Fixes Issue #22 Bug #6.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- fix(mcp): use ListToolsRequestSchema/CallToolRequestSchema instead of string literals (Issue #9, PR #25)
- fix(mcp): handleToolCall reads dry_run from params instead of hardcoding false (#22 Bug #11)
- fix(search): keyword search returns best chunk per page via DISTINCT ON, not all chunks (#22 Bug #8)
- fix(search): dedup layer 1 keeps top 3 chunks per page instead of collapsing to 1 (#22 Bug #12)
- fix(engine): transaction uses scoped engine via Object.create, no shared state mutation (#22 Bug #2)
- fix(engine): upsertChunks uses UPSERT instead of DELETE+INSERT, preserves existing embeddings (#22 Bug #1)
- fix(slugs): validateSlug normalizes to lowercase, pathToSlug lowercases consistently (#22 Bug #4)
- schema: add unique index on content_chunks(page_id, chunk_index) for UPSERT support
- schema: add access_tokens and mcp_request_log tables via migration
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add SKILLPACK Section 18 — Live Sync (MUST ADD)
Contract-first guide for keeping the vector DB in sync with the brain
repo. Documents the pooler prerequisite (Session mode required for
transactions), sync + embed primitives, four example approaches (cron,
--watch, webhook, git hook), isSyncable exclusions, silent skip warning,
and OpenClaw/Hermes cron registration examples.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add GBRAIN_VERIFY.md installation verification runbook
Six-check runbook: schema (doctor), skillpack loaded, auto-update,
live sync (coverage check + embed check + end-to-end push-and-search
test), embedding coverage, brain-first lookup protocol. Emphasizes
"sync ran" != "sync worked" — the real test is searching for corrected
text after a push.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add setup Phases H (Live Sync) and I (Verification)
Phase H: MUST ADD live sync setup — pooler prerequisite check, automatic
sync configuration (agent picks approach), sync+embed chaining, coverage
verification. Phase I: run GBRAIN_VERIFY.md end-to-end before declaring
setup complete.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add install steps 8-9 (live sync + verification)
Step 8: set up automatic sync with SKILLPACK Section 18 reference.
Step 9: run GBRAIN_VERIFY.md runbook. Add GBRAIN_VERIFY.md to docs
section.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add API key loading instructions to CLAUDE.md
Source ~/.zshrc before running Tier 2 tests so OPENAI_API_KEY and
ANTHROPIC_API_KEY are available. Without this, embedding and skills
tests skip silently.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: bump version to v0.5.0
Live sync, verification runbook, API key loading instructions.
Version markers updated in SKILLPACK and RECOMMENDED_SCHEMA.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add anti-hand-roll rule to skill routing in CLAUDE.md
Explicitly prohibit manually running git commit + push + gh pr create
when /ship is available. /ship handles VERSION, CHANGELOG,
document-release, reviews, and coverage audit. Hand-rolling skips
all of these. Added "commit and ship" / "push and ship" variants
to the ship routing rule.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: changelog voice rule + rewrite 0.5.0 changelog to sell the upgrade
CLAUDE.md: add changelog voice guidance — lead with benefits, not
implementation details. Make users want to upgrade.
CHANGELOG: rewrite 0.5.0 entries from dry feature descriptions to
capability-focused bullets ("your brain never falls behind" not
"SKILLPACK Section 18 added").
SKILLPACK Section 17: update the auto-update message template to
instruct agents to sell the upgrade, not just summarize the diff.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add v0.5.0 migration directive for live sync + verification
Agents upgrading from v0.4.x will automatically: check their pooler
connection string, set up automatic sync, and run the verification
runbook. Without this migration file, upgrading agents would learn
about live sync (by re-reading Section 18) but wouldn't set it up.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: sharpen migration file guidance in CLAUDE.md
Replace vague "requires agent action" with concrete trigger list:
new setup steps existing users don't have, MUST ADD skillpack sections,
schema changes, deprecated commands, new verification steps, new crons.
Add the key test: "if an existing user upgrades and does nothing else,
will their brain work worse?"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: make Section 17 upgrade flow work for direct user requests
Section 17 was structured as a cron-initiated flow only. An agent
handling "upgrade gbrain" might just run the command and stop, missing
the post-upgrade steps where the value is (re-read skills, run
migrations, schema sync). Added explicit entry point for direct
upgrade requests. Made Steps 2-4 more concrete about where to find
files and why migrations can't be skipped.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: add E2E sync tests — git-to-DB pipeline (11 tests)
Tests the full sync lifecycle against real Postgres+pgvector:
- First sync imports all pages from a git repo
- Second sync with no changes returns up_to_date
- Incremental sync picks up new files (add → commit → sync → verify)
- Incremental sync picks up modifications — THE CRITICAL TEST:
corrected text appears in DB and keyword search after sync
- Incremental sync handles deletes
- Non-syncable files are excluded (README, .raw/, ops/)
- Sync state (last_commit, last_run) persisted to config
- Sync logged to ingest_log
- --full reimports everything
- --dry-run shows changes without applying
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: strengthen CLAUDE.md to always run ALL test tiers
Replace passive "source zshrc" suggestion with ALWAYS directive.
Explicitly state that "run all tests" means ALL tiers including
Tier 2 with API keys. Do not skip Tier 2 just because keys need
loading.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: Tier 2 E2E tests — correct openclaw CLI invocation
The tests used `openclaw -p` which doesn't exist. The correct command
is `openclaw agent --local --agent <id> --message <prompt>`. Also fixed
JSON output parsing (structured JSON goes to stderr, not stdout — use
non-JSON mode instead). Fixed ingest test to assert on agent response
text rather than test DB state (the agent writes to its own configured
DB, not the ephemeral test DB).
82 tests pass, 0 fail, 0 skip across all 5 E2E files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* security: pin GitHub Actions to commit SHAs, add gitleaks CI
- Pin all 5 actions (checkout, setup-bun, upload-artifact, download-artifact,
action-gh-release) to commit SHAs across 3 workflow files
- Add permissions: contents: read to test.yml and e2e.yml
- Add gitleaks secret scanning job to test.yml
- Pin openclaw install to v2026.4.9 in e2e.yml
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* security: add .gitleaks.toml config
Allowlists test fixtures, example env files, and skill documentation
to prevent false positives from the gitleaks CI step.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add GitHub Actions SHA maintenance rule to CLAUDE.md
Instructs /ship and /review to check for stale SHA pins and update
them, keeping action versions fresh without manual effort.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add S3 Sig V4 TODO from CSO audit
Deferred from security audit. S3 storage backend accepts credentials
but sends unsigned requests. Implement when S3 becomes a real
deployment path.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v0.4.2)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
OpenClaw ships DREAMS.md by default. Hermes users get a cron job
recipe with session_search + gbrain + memory consolidation, plus
Honcho for dialectic reasoning.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
GBrain install instructions and skills work with both OpenClaw and
Hermes Agent. First mention in each file says OpenClaw/Hermes,
subsequent references say OpenClaw.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New flow: Get Connected > Direct Connection String > Session Pooler >
copy Shared Pooler. The old gear icon > Project Settings path is stale.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
