Merge pull request #304 from dhanjit/contrib/dhanjit/local-brain-no-mcp

[recipes] Add local-brain-no-mcp recipe + ob1-local-http skill

Author: justfinethanku

recipes/local-brain-no-mcp/.env.example

@@ -0,0 +1,38 @@
+# local-brain-no-mcp -- environment overlay
+#
+# This file is the source of truth for the brain stack. After running setup.sh,
+# a fully-populated .env (with generated secrets) is written to
+# supabase-docker/docker/.env -- that's where docker compose reads from.
+#
+# Edit the values below BEFORE running setup.sh if you want non-defaults.
+# Once the stack has booted with a given EMBED_DIM, the value is baked into
+# the thoughts table and cannot be changed without wiping the Postgres volume.
+
+# ---------- embedding ----------
+# The Ollama model used to embed thought text. Server-side only -- dev hosts
+# never need Ollama. See README "Embedding model is a one-way door" for the
+# rules around switching models later.
+EMBED_MODEL=nomic-embed-text
+EMBED_DIM=768
+
+# Where the capture / search Edge Functions reach Ollama from inside the
+# Docker network. Don't change unless you also change the Ollama service name
+# in docker-compose.yml.
+OLLAMA_URL=http://ollama:11434
+
+# Host port to expose Ollama on (handy for `ollama pull` from the brain host
+# shell). The Edge Functions reach Ollama over the internal Docker network,
+# not this port.
+OLLAMA_PORT=11434
+
+# ---------- networking ----------
+# Hostname or IP that dev hosts use to reach the brain. Used only by
+# setup.sh when it prints the "skill install" snippet at the end. The
+# Supabase Kong gateway listens on KONG_HTTP_PORT (default 8000).
+BRAIN_HOST=brain.local
+KONG_HTTP_PORT=8000
+
+# Everything else (POSTGRES_PASSWORD, JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY,
+# DASHBOARD_USERNAME, DASHBOARD_PASSWORD, etc.) is generated for you by
+# setup.sh into supabase-docker/docker/.env -- do NOT put real secrets in
+# THIS file.

recipes/local-brain-no-mcp/README.md

@@ -0,0 +1,147 @@
+# Local Brain (No MCP)
+
+Self-hosted Open Brain on a single LAN host: the official Supabase docker-compose stack plus an Ollama sidecar for local embeddings and two Edge Functions (`capture`, `search`) wired up for OB1's `thoughts` schema. Reached from each dev host through `curl`, via the companion [`ob1-local-http`](../../skills/ob1-local-http/) skill -- no MCP transport involved.
+
+## Why this exists (deliberate exception to canonical OB1)
+
+The canonical OB1 architecture assumes (a) Claude Code can call a remote Supabase MCP server and (b) Supabase Cloud is reachable. This recipe is intentionally for environments where neither is true:
+
+- **No third-party cloud reachable** -- the host can only talk to other LAN hosts. Supabase Cloud is off the table; everything runs on a single Linux box in the office.
+- **MCP feature disabled in Claude Code** -- corporate policy or a locked-down build blocks Claude Code from speaking MCP at all (stdio or remote). The canonical capture/search tools therefore can't run.
+
+So this recipe diverges from `CLAUDE.md`'s rule "MCP servers must be remote Supabase Edge Functions." It still uses Edge Functions, but exposes them as plain HTTPS endpoints -- not as MCP -- because the network won't let MCP through. The skill on each dev host calls those endpoints with `curl`. Cloud-shaped OB1 recipes that target PostgREST/Edge Functions still work locally with a base-URL swap; only the MCP transport is gone.
+
+If your environment does NOT have these constraints, use the canonical cloud OB1 instead -- this recipe trades roughly 30 minutes of setup, ~3 GB RAM, and operational complexity for the air-gapped/no-MCP property.
+
+## What you get
+
+After setup, on one office Linux host:
+
+- Postgres 15 with `pgvector` (HNSW index on a configurable embedding dim, default 768)
+- The full Supabase stack (Kong gateway, PostgREST, GoTrue, Realtime, Storage, Studio, Edge Functions runtime, Logflare) -- canonical, unmodified, just self-hosted
+- An `ollama` sidecar that the Edge Functions call for embedding generation -- dev hosts never need Ollama
+- A `thoughts` table that mirrors the canonical OB1 schema exactly, plus `match_thoughts(...)` and `upsert_thought(...)` RPCs with the same signatures as cloud
+- Three Edge Functions reachable through Kong:
+  - `POST /functions/v1/capture` -- embed and store
+  - `POST /functions/v1/search` -- embed query and run match_thoughts
+  - `GET  /functions/v1/list` -- recent thoughts for browsing or downstream digest skills
+- Supabase Studio at `http://<brain-host>:3000` -- your day-one read-only dashboard, free
+- A `BRAIN_URL` + `BRAIN_ANON_KEY` pair that you paste into each dev host's environment for the [`ob1-local-http`](../../skills/ob1-local-http/) skill
+
+## Prerequisites
+
+On the **brain host** (one Linux box on the office network):
+
+- Docker 24+ with Compose v2.20+ (`include:` directive required)
+- `git`, `openssl`, `python3` (stdlib only -- no `pip install`)
+- ~8 GB RAM available, ~5 GB disk for images and the embedding model
+- Outbound HTTPS to GitHub and to the configured Docker registry, *one-time*, for the clone and image pulls
+- A stable hostname or IP reachable from every dev host (e.g., `brain.local`)
+
+On each **dev host**:
+
+- `curl`
+- Claude Code (or any skill-aware AI tool that reads `~/.claude/skills/`)
+
+## Setup
+
+> Run all of these on the **brain host**, from this directory (`recipes/local-brain-no-mcp/`).
+
+1. Copy `.env.example` to `.env` and edit the overlay values if you want non-defaults. The important one is `EMBED_DIM` -- see the one-way door warning below before you change it.
+
+   ```sh
+   cp .env.example .env
+   $EDITOR .env
+   ```
+
+2. Run the one-time setup. It clones `supabase/supabase`, generates secrets (POSTGRES_PASSWORD, JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY, dashboard password, vault key, logflare tokens), writes them to `supabase-docker/docker/.env`, symlinks the Edge Functions into the supabase volume, and installs the SQL init scripts.
+
+   ```sh
+   ./setup.sh
+   ```
+
+   `setup.sh` is idempotent. Re-running preserves an existing `.env` so already-captured data stays accessible.
+
+3. Bring up the stack.
+
+   ```sh
+   docker compose up -d
+   docker compose ps
+   ```
+
+   First boot pulls ~3 GB of images and runs the Postgres init scripts (creating the `thoughts` table, indexes, RPCs).
+
+4. Pull the embedding model into Ollama (one-time, model size depends on choice):
+
+   ```sh
+   docker compose exec ollama ollama pull "$(grep ^EMBED_MODEL supabase-docker/docker/.env | cut -d= -f2-)"
+   ```
+
+5. Verify reachability from the brain host itself:
+
+   ```sh
+   ANON_KEY="$(grep ^ANON_KEY supabase-docker/docker/.env | cut -d= -f2-)"
+   curl -fsS -X POST "http://localhost:8000/functions/v1/capture" \
+     -H "apikey: $ANON_KEY" \
+     -H "Authorization: Bearer $ANON_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"content":"first thought from setup.sh smoke test","metadata":{"source":"smoke-test"}}'
+   ```
+
+   Expected: HTTP 200 with `{"ok":true,"id":"...","fingerprint":"..."}`.
+
+6. On each dev host, install [`ob1-local-http`](../../skills/ob1-local-http/) and export the two env vars `setup.sh` printed at the end. The skill takes over from there.
+
+## Expected outcome
+
+- Claude Code on any dev host can capture and search thoughts by asking in natural language ("remember X", "what did I note about Y") and the skill translates that into `curl` against the brain.
+- The brain accumulates thoughts in `public.thoughts`, vector-indexed for similarity search.
+- Supabase Studio at `http://<brain-host>:3000` lets you browse, edit, or delete rows manually.
+- Nothing leaves the LAN.
+
+## The embedding model is a one-way door
+
+The `EMBED_DIM` env var is baked into the `embedding vector(N)` column when the Postgres volume is initialized. pgvector enforces this at insert time -- once the volume exists, **you cannot change `EMBED_DIM` without wiping the volume and losing all captured thoughts.**
+
+What this means in practice:
+
+- Pick `EMBED_MODEL` / `EMBED_DIM` once before first boot.
+- If you must change them later:
+  1. `docker compose down`
+  2. Back up first (see below) if you want to migrate data
+  3. `docker volume rm` the Postgres data volume (find it with `docker volume ls | grep db`)
+  4. Edit `supabase-docker/docker/.env` to the new dim
+  5. `docker compose up -d` -- Postgres re-runs the init scripts with the new dim
+  6. Re-embed your backed-up content via the new model
+
+The `embed.ts` helper does a dim check on every call and returns a clear error (`embedding-dim mismatch...`) if the model and the column disagree.
+
+## Backup and restore
+
+Stop the stack first, then snapshot the data volumes:
+
+```sh
+docker compose stop db
+docker run --rm \
+  -v "$(docker volume ls -q | grep _db-config):/from" \
+  -v "$(pwd)/backups:/to" \
+  alpine tar czf "/to/db-$(date +%F).tar.gz" -C /from .
+docker compose start db
+```
+
+To restore: `docker compose down`, `docker volume rm` the db volume, recreate empty, untar into it, `docker compose up -d`.
+
+## Troubleshooting
+
+- **`docker compose` fails with `unknown field "include"`**: you're on Compose < 2.20. Upgrade Docker Desktop or install a current `docker compose` plugin.
+- **`functions` service exits with module-resolution errors against `_shared/*.ts`**: the symlinks didn't take. Check `ls -la supabase-docker/docker/volumes/functions/` -- you should see `capture`, `search`, `list`, `_shared` as symlinks pointing back at this recipe. Re-run `./setup.sh`.
+- **`embed.ts: did you 'ollama pull <model>'?`**: you skipped step 4. Run the `ollama pull` line.
+- **`embed.ts: embedding-dim mismatch`**: someone changed `EMBED_DIM` in `.env` after the volume was initialized. Either revert the env or follow the one-way-door procedure above.
+- **HTTP 401 from Kong**: `ANON_KEY` in `.env` and the one your dev host is using are out of sync. Re-export from `supabase-docker/docker/.env`.
+- **Dev host can't reach `http://<brain-host>:8000`**: confirm the brain host's firewall allows `KONG_HTTP_PORT` inbound on the office network and that the hostname resolves.
+
+## Related
+
+- [`skills/ob1-local-http`](../../skills/ob1-local-http/) -- the companion skill pack that runs on each dev host
+- [`docs/drafts/agent-memory-staging-base.sql`](../../docs/drafts/agent-memory-staging-base.sql) -- the canonical thoughts schema this recipe mirrors
+- [`server/index.ts`](../../server/index.ts) -- the canonical MCP server this recipe deliberately does NOT use as a transport

recipes/local-brain-no-mcp/docker-compose.yml

@@ -0,0 +1,49 @@
+# local-brain-no-mcp -- docker compose overlay
+#
+# This file merges the official supabase/supabase docker-compose stack with
+# our additions (Ollama + EMBED_* env vars). Run from this directory:
+#
+#     ./setup.sh             # one-time
+#     docker compose up -d   # bring up the brain
+#
+# `include:` resolves paths relative to the parent compose file, so
+# supabase-docker/ must be a sibling directory (setup.sh handles this).
+# Requires Docker Compose v2.20 or newer.
+
+include:
+  - path: supabase-docker/docker/docker-compose.yml
+    env_file: supabase-docker/docker/.env
+
+services:
+  ollama:
+    image: ollama/ollama:0.6.5
+    container_name: ob1-ollama
+    restart: unless-stopped
+    networks:
+      - default
+    ports:
+      - "${OLLAMA_PORT:-11434}:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    healthcheck:
+      test: ["CMD-SHELL", "ollama list >/dev/null 2>&1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 60s
+
+  # Extend supabase's Edge Functions service so our handlers can find Ollama
+  # and know which model/dim to use. The functions volume mount comes from
+  # supabase's compose (./volumes/functions) -- setup.sh symlinks our handler
+  # dirs into there.
+  functions:
+    environment:
+      OLLAMA_URL: ${OLLAMA_URL:-http://ollama:11434}
+      EMBED_MODEL: ${EMBED_MODEL:-nomic-embed-text}
+      EMBED_DIM: ${EMBED_DIM:-768}
+    depends_on:
+      ollama:
+        condition: service_healthy
+
+volumes:
+  ollama_data:

recipes/local-brain-no-mcp/functions/_shared/cors.ts

@@ -0,0 +1,21 @@
+export const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Headers":
+    "authorization, x-client-info, apikey, content-type",
+  "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+};
+
+export function jsonResponse(
+  body: unknown,
+  status = 200,
+  extraHeaders: Record<string, string> = {},
+): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      ...corsHeaders,
+      ...extraHeaders,
+    },
+  });
+}

recipes/local-brain-no-mcp/functions/_shared/db.ts

@@ -0,0 +1,14 @@
+import { createClient, type SupabaseClient } from "jsr:@supabase/supabase-js@2";
+
+const SUPABASE_URL = Deno.env.get("SUPABASE_URL");
+const SERVICE_ROLE_KEY = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY");
+
+if (!SUPABASE_URL || !SERVICE_ROLE_KEY) {
+  throw new Error(
+    "SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set by the Edge Functions runtime",
+  );
+}
+
+export const db: SupabaseClient = createClient(SUPABASE_URL, SERVICE_ROLE_KEY, {
+  auth: { autoRefreshToken: false, persistSession: false },
+});

recipes/local-brain-no-mcp/functions/_shared/embed.ts

@@ -0,0 +1,56 @@
+// Server-side embedding via a local Ollama sidecar. Dev hosts never need
+// Ollama -- the capture and search Edge Functions both call this helper.
+
+const OLLAMA_URL = Deno.env.get("OLLAMA_URL") ?? "http://ollama:11434";
+const EMBED_MODEL = Deno.env.get("EMBED_MODEL") ?? "nomic-embed-text";
+const EMBED_DIM = Number(Deno.env.get("EMBED_DIM") ?? "768");
+
+export class EmbedError extends Error {
+  constructor(message: string, public readonly cause?: unknown) {
+    super(message);
+    this.name = "EmbedError";
+  }
+}
+
+export async function embed(text: string): Promise<number[]> {
+  const trimmed = text?.trim();
+  if (!trimmed) throw new EmbedError("empty text");
+
+  let r: Response;
+  try {
+    r = await fetch(`${OLLAMA_URL}/api/embeddings`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: EMBED_MODEL, prompt: trimmed }),
+    });
+  } catch (e) {
+    throw new EmbedError(
+      `unable to reach Ollama at ${OLLAMA_URL} -- is the ollama container running?`,
+      e,
+    );
+  }
+
+  if (!r.ok) {
+    const body = await r.text().catch(() => "");
+    throw new EmbedError(
+      `Ollama embedding failed: HTTP ${r.status} ${r.statusText} -- ${body.slice(0, 200)}`,
+    );
+  }
+
+  const data = await r.json();
+  const v = data?.embedding;
+  if (!Array.isArray(v) || v.length === 0) {
+    throw new EmbedError(
+      `Ollama returned no embedding -- did you 'ollama pull ${EMBED_MODEL}'?`,
+    );
+  }
+  if (v.length !== EMBED_DIM) {
+    throw new EmbedError(
+      `embedding-dim mismatch: env EMBED_DIM=${EMBED_DIM} but Ollama returned ${v.length}. ` +
+        `Either change EMBED_MODEL to one that produces ${EMBED_DIM} dims, or wipe the Postgres volume and re-bootstrap with the new dim.`,
+    );
+  }
+  return v;
+}
+
+export const config = { EMBED_MODEL, EMBED_DIM, OLLAMA_URL };

recipes/local-brain-no-mcp/functions/capture/index.ts

@@ -0,0 +1,67 @@
+// POST /functions/v1/capture
+//
+// Body:
+//   { content: string, metadata?: object }
+//
+// Embeds `content` via the local Ollama sidecar and INSERTs via the
+// upsert_thought() RPC (which dedupes by sha256(normalized content)).
+//
+// Auth: Kong gateway verifies the anon-or-service-role JWT before this
+// function runs. We do not re-check.
+
+import { corsHeaders, jsonResponse } from "../_shared/cors.ts";
+import { embed, EmbedError } from "../_shared/embed.ts";
+import { db } from "../_shared/db.ts";
+
+interface CaptureBody {
+  content?: unknown;
+  metadata?: unknown;
+}
+
+Deno.serve(async (req: Request) => {
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: corsHeaders });
+  }
+  if (req.method !== "POST") {
+    return jsonResponse({ error: "method not allowed" }, 405);
+  }
+
+  let body: CaptureBody;
+  try {
+    body = await req.json();
+  } catch {
+    return jsonResponse({ error: "body must be valid JSON" }, 400);
+  }
+
+  const content = typeof body.content === "string" ? body.content.trim() : "";
+  if (!content) {
+    return jsonResponse({ error: "content is required (non-empty string)" }, 400);
+  }
+  const metadata =
+    body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata)
+      ? body.metadata
+      : {};
+
+  let vec: number[];
+  try {
+    vec = await embed(content);
+  } catch (e) {
+    if (e instanceof EmbedError) return jsonResponse({ error: e.message }, 502);
+    throw e;
+  }
+
+  const { data, error } = await db.rpc("upsert_thought", {
+    p_content: content,
+    p_embedding: vec,
+    p_metadata: metadata,
+  });
+
+  if (error) {
+    return jsonResponse(
+      { error: `upsert_thought failed: ${error.message}`, details: error.details ?? null },
+      500,
+    );
+  }
+
+  return jsonResponse({ ok: true, ...data }, 200);
+});