mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-28 14:59:47 +00:00
a86f995883
* feat: contract-first operations.ts with OperationError, dry_run, importFromContent 30 shared operations as single source of truth for CLI and MCP. - OperationError with typed error codes (page_not_found, invalid_params, etc.) - dry_run support on all mutating operations - importFromContent split from importFile with transaction wrapping - Idempotency hash now includes ALL fields (title, type, frontmatter, tags) - Config env var fallback: GBRAIN_DATABASE_URL > DATABASE_URL > config file Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor: rewrite MCP server + CLI + tools-json from operations server.ts: 233 -> ~80 lines. Tool definitions and dispatch generated from operations[]. cli.ts: shared operations auto-registered, CLI-only commands kept as manual dispatch. tools-json: generated FROM operations[], eliminating the third contract surface. Parity test verifies structural contract between operations, CLI, and MCP. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor: delete 12 command files migrated to operations.ts Handler logic for get, put, delete, list, search, query, health, stats, tags, link, timeline, and version now lives in operations.ts. Kept: init, upgrade, import, export, files, embed, sync, serve, call, config. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: init --non-interactive, upgrade verification, schema migration - gbrain init --non-interactive --url <url> for plugin mode (no TTY required) - Post-upgrade version verification in gbrain upgrade - Drop storage_url from files table (storage_path is the only identifier) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: tool-agnostic skills + new setup skill All 7 skills rewritten with intent-based language instead of CLI commands. Works with both CLI and MCP plugin contexts. New setup skill replaces install: auto-provision Supabase via CLI, AGENTS.md injection, target TTHW < 2 min. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: ClawHub bundle plugin, CI workflows, v0.3.0 - openclaw.plugin.json with configSchema, MCP server config, skill listing - GitHub Actions: test on push/PR, multi-platform release (macOS arm64 + Linux x64) - Version bump 0.3.0, CHANGELOG, README ClawHub section, CLAUDE.md updated Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: idempotency hash mismatch + MCP dry_run passthrough importFromContent now passes its all-fields hash through putPage via content_hash on PageInput, so the stored hash matches the computed hash. Previously the skip-if-unchanged check never fired because the hash formulas differed. MCP server now passes dry_run from tool params to OperationContext. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.3.0.0) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: schema loader handles PL/pgSQL $$ blocks Delete the semicolon-based SQL splitter in db.ts which broke on PL/pgSQL trigger functions containing semicolons inside $$ delimiter blocks. Use single conn.unsafe(schemaSql) call instead — the postgres driver handles multi-statement SQL natively. schema.sql already uses IF NOT EXISTS / CREATE OR REPLACE for idempotency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: E2E test infrastructure + realistic brain fixtures Add test infrastructure for running E2E tests against real Postgres+pgvector. Includes: - test/e2e/helpers.ts: DB lifecycle, fixture import, timing, diagnostics - 13 fixture files as a miniature realistic brain (people, companies, deals, meetings, concepts, projects, sources) following the compiled truth + timeline format from GBRAIN_RECOMMENDED_SCHEMA.md - docker-compose.test.yml: local pgvector convenience (port 5433) - .env.testing.example: template for test credentials - package.json: add test:e2e script Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: E2E test suites + CI workflow Tier 1 (mechanical.test.ts): 14 test suites covering all operations against real Postgres — page CRUD, search with quality scoring, links, tags, timeline, versions, admin, chunks, resolution, ingest log, raw data, files, idempotency stress, setup journey (full CLI flow), init edge cases, schema idempotency, schema diff guard, performance baselines. Tier 1 (mcp.test.ts): MCP protocol test — spawns server, sends JSON-RPC, verifies tools/list matches operations count. Tier 2 (skills.test.ts): OpenClaw skill tests — ingest, query, health. Skips gracefully when dependencies missing. CI (.github/workflows/e2e.yml): Tier 1 on every PR (pgvector service), Tier 2 nightly/manual with API key secrets. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: E2E test fixes + traverseGraph jsonb cast - Fix traverseGraph query: cast json_agg to jsonb_agg so SELECT DISTINCT works - Fix put_page tests to use importFromContent with noEmbed (no OpenAI key in Tier 1) - Fix get_health assertion (page_count not total_pages) - Fix raw_data test to handle JSONB string/object return - Simplify MCP test to verify tool generation directly - Add timeouts to CLI subprocess tests - Use port 5434 for docker-compose (5433 often in use) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: update all project docs for E2E test suite - CLAUDE.md: updated test count (9 unit + 3 E2E), added E2E test instructions, fixed skill count to 8 - CONTRIBUTING.md: updated project structure with test/e2e/, added E2E test instructions, rewrote "Adding a new command" to reflect contract-first architecture (add to operations.ts, done) - README.md: fixed table count (10 not 9), added recommended schema doc to Docs section, added E2E instructions to Contributing section - CHANGELOG.md: added E2E test suite, docker-compose, schema loader fix, and traverseGraph jsonb fix to v0.3.0 entry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3.0 KiB
3.0 KiB
type, title, tags
| type | title | tags | ||
|---|---|---|---|---|
| project | GBrain |
|
GBrain
Personal knowledge brain built on Postgres with pgvector. A managed Supabase instance provides the database layer. GBrain stores, searches, and retrieves personal knowledge using a hybrid RAG architecture.
Architecture
- Contract-first design —
src/core/operations.tsdefines ~30 shared operations. Both the CLI and the MCP server are generated from this single source of truth. Adding a new operation means defining it once and getting both interfaces for free. - Postgres-native — All data lives in Postgres. Embeddings are stored using pgvector. Full-text search uses Postgres tsvector/tsquery. No external search services required.
- Hybrid search — Combines vector similarity search with keyword full-text search using Reciprocal Rank Fusion (RRF). This handles both exact keyword matches and semantic near-matches. Multi-query expansion and deduplication further improve recall and precision.
- Compiled truth pages — All knowledge pages use the two-layer compiled truth + timeline format. This means retrieved content is pre-synthesized rather than raw note fragments, producing higher quality RAG responses.
Key Components
- Pluggable engine interface (BrainEngine) with Postgres + pgvector implementation
- 3-tier chunking: recursive, semantic, and LLM-guided
- OpenAI text-embedding-3-large for vector embeddings with batch processing and retry
- Skills system: fat markdown files that work in both CLI and plugin contexts
- MCP stdio server for integration with Claude and other LLM tools
Current Status
v0.3 shipped with hybrid search, contract-first architecture, and the ClawHub bundle plugin. Active development continues on search quality improvements and new skills.
Retrieval-Augmented Generation
GBrain uses RAG as its core query mechanism. The compiled truth pattern is a deliberate alternative to standard RAG's fragment-retrieval approach: by maintaining pre-synthesized pages, retrieved context is higher quality and more coherent than raw chunks.
Timeline
2025-02-01 — Project Started
Initial implementation with keyword-only search. Postgres + Supabase backend. Basic CLI for import and query operations.
2025-03-01 — Contract-First Refactor
Refactored to contract-first architecture. Operations defined in a single source file, with CLI and MCP server both generated from the same definitions. This eliminated drift between the two interfaces and simplified adding new operations.
2025-03-28 — Hybrid Search Decision
Weekly sync decision to ship hybrid search in v0.3. Keyword-only search was missing relevant results when queries used different terminology than stored documents. Adopted pgvector for embeddings and Reciprocal Rank Fusion (RRF) for merging vector and keyword result sets.
2025-04-01 — v0.3 Shipped
Released v0.3 with hybrid search, ClawHub bundle plugin, and several new skills. Contract-first parity between CLI, MCP, and tools-json verified by automated tests.