CABRAIN
CaBrain
Pages · CaBrain

CaBrain — decision log (deltas on top of SPEC.md)

Running ADR-style log. SPEC.md is the original contract; this file records decisions and reality-checks made during the build. Newest at top.

D6 — brain owns its schema + queries in Go (togo plugin-schema pattern) (2026-07-16)

Confirmed from the real togo-framework plugins in the module cache: a plugin that needs tables provisions them at runtime in Go — k.SQL() + db.ExecContext("CREATE TABLE IF NOT EXISTS …"), dialect-portable via k.Dialect().Placeholder(n) (see cache.cache_entries, settings.settings). Plugins do not ship into the host app's sqlc/atlas/make:resource codegen. This is the self-contained, publishable pattern.

Adopted for brain:

  • Schema in Go. internal/brain/schema.sql (the full SPEC §3 DDL) is go:embeded and run by Migrate(). Ships with the plugin; no host codegen coupling.
  • Hand-written pgx queries (retain/recall) — not sqlc. The exotic types (vector(1024), bm25, partitioning) don't round-trip through the app's sqlite-sqlc flow anyway; hand SQL is both necessary and idiomatic here (matches cache/settings).
  • Consumer surface is MCP tools + retain/recall handlers (SPEC §5), not generic CRUD REST on memories. So make:resource's CRUD/GraphQL scaffolding is not the right tool for these tables. (If a resource genuinely needs admin CRUD later, add it then.)
  • Provider seams as interfaces (Embedder, Reranker, Engine) so brain-tei / brain-cognee register drivers — mirrors togo's driver-registry plugins (D3).
  • The app-level sqlc.yaml (engine sqlite) is left untouched; brain doesn't use it.

This overrides the literal SPEC §7-step-3 ("generate the resources → sqlc + Atlas + REST/GraphQL") where it conflicts: the engine-agnostic contracts (schema + tools) are what's load-bearing, and the plugin-native Go path realizes them correctly on postgres.

D5 — Live infra reality vs SPEC/§4 bundle (2026-07-16)

Empirically probed from the Coder workspace (pgx). What is actually reachable and true:

  • Postgres at host.docker.internal:5432 (workspace superuser; creds in the stack, not here) is PostgreSQL 16.14 (Debian), vanilla — installed extensions: only plpgsql; none of vector, pg_search, vchord, vchord_bm25, pg_tokenizer, pg_partman, pg_duckdb, pg_cron are even available. Databases present: fadymondy, flowos, flowos_live, flowos_ref, flowos_v2, postgres, togo. No cabrain database, no cabrain_sleep role.
  • Redis host.docker.internal:6379 — reachable. NATS :4222 — reachable.
  • The pg:5432 internal hostname from the §4 bundle is not reachable from the workspace (it's inside Docker net stack_stacknet).

Conclusion: the extension-equipped CaBrain DB described in the §4 bundle (dedicated cabrain DB + cabrain_sleep role on stack-togo-postgres:latest with the vchord stack) is not yet live / not reachable — consistent with the infra note that the finalizer hasn't completed. The services-page image string (PG17 + pg_duckdb + pg_search + vector + pg_cron) does not match the reachable server either, so treat it as aspirational until the finalizer confirms.

Actions:

  • Keep db/schema.sql on the VectorChord stack per SPEC §3/§8 (deliberate choice over ParadeDB for Arabic pg_tokenizer BM25). Do not rewrite for ParadeDB based on the services page.
  • Blocker B stands for live migrate/serve and for anything needing vector/BM25/partman.
  • Resource build (task #9) proceeds regardless — sqlc validates schema statically, no DB.
  • When the finalizer lands: connect to the real cabrain DB, run the §3 extension checks, then migrate.

D4 — Redis L1 working-memory cache (NEW tier; extends SPEC §2/N1)

Add a Redis fast get/set tier in front of the PG hot tier — the "working-memory cache" in the brain map, below the context window and above the hippocampal hot tier. Redis is already live (host.docker.internal:6379).

  • What it caches (recall N1 path): (a) recent recall query→result sets (short TTL), (b) hot memory rows by id, (c) content→embedding for write-time dedup. Never the source of truth.
  • PG remains authoritative. Redis is cache-aside / write-through; a cold Redis only costs latency, never correctness. Invalidate on retain/reconsolidate/forget of touched keys.
  • How — two options:
    1. App-level cache-aside via togo-framework/cache + cache-redis (RECOMMENDED for Phase 1): idiomatic, portable, no PG extension. The brain service checks Redis, falls back to PG, populates Redis. Ships as the brain using togo's cache abstraction.
    2. redis_fdw / PG↔Redis connector (the "pg_redis" idea): query/sync Redis from PG via a foreign data wrapper. More coupling, needs the extension in togo-postgres. Revisit if the app-level cache proves insufficient or a SQL-side join to cached data is needed.
  • Packaging: either reuse togo-framework/cache-redis, or a thin brain-redis provider plugin wrapping it with brain's key schema + invalidation. Decide when wiring recall.

D3 — Provider decomposition: one plugin per provider

Everything ships as a togo plugin (OSS). CaBrain = the cabrain project composed of plugins:

  • brain (github.com/togo-framework/brain) — the memory organ: schema, retain/recall, MCP tools, capture. Providers behind interfaces.
  • brain-tei — TEI embeddings + rerank driver (Qwen3-Embedding-0.6B / bge-reranker-v2-m3).
  • brain-cognee — Cognee cognify-engine driver (graph+vector extraction).
  • brain-cold-* — cold-tier driver (Iceberg/Parquet on MinIO/S3), Phase 2.
  • (optional) brain-redis — L1 cache driver (D4). Design brain with provider seams now; build each provider plugin as its consumer (retain/recall) lands. Mirrors togo's own driver-plugin pattern (ai-openai, storage-s3, cache-redis, …).

D2 — Repo shape: monorepo project + split plugin (2 repos)

  • togo-framework/cabrain — the project/dev-harness (togo app, module github.com/togo-framework/cabrain); hosts plugins/brain (+ future plugins), SPEC/PLAN/docs.
  • togo-framework/brain — the publishable plugin, split from plugins/brain.
  • Wired locally via require github.com/togo-framework/brain v0.0.0 + replace … => ./plugins/brain (works with all go tooling incl. togo generate); blank-imported in internal/plugins/local.go (out of the DO-NOT-EDIT plugins.gen.go).

D1 — Engine-agnostic contracts first (Track 0)

db/schema.sql, contracts/tools.md, docs/capture-mode.md are the source of truth and the direct-on-Postgres fallback (SPEC §8), independent of ToGO and any live infra.