mosaic/openbrain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
openbrain/docs/scratchpads/v001-build.md
Jason Woltje 5771ec5260 feat: initial alpha scaffold — FastAPI + MCP + pgvector 
Implements v0.0.1 of OpenBrain:

- FastAPI REST API (capture, search, recent, stats) with Bearer auth
- MCP server (streamable HTTP at /mcp) exposing all 4 tools
- pgvector schema (vector(1024) for bge-m3)
- asyncpg connection pool with lazy init + graceful close
- Ollama embedding client with fallback (stores thought without vector if Ollama unreachable)
- Woodpecker CI pipeline (lint + kaniko build + push to Gitea registry)
- Portainer/Swarm deployment compose
- Mosaic framework files: AGENTS.md, PRD.md, TASKS.md, scratchpad

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-02 18:25:07 -06:00

1.5 KiB
Raw Permalink Blame History

Scratchpad: v0.0.1 Build

Date: 2026-03-02 Objective: Build and deploy alpha OpenBrain service

Plan

  1. Scaffold project structure
  2. Core brain operations (capture, search, recent, stats)
  3. FastAPI REST + MCP server (single process)
  4. pgvector schema
  5. Dockerfile
  6. Portainer compose
  7. Woodpecker CI pipeline
  8. Mosaic framework files (AGENTS.md, PRD.md, TASKS.md)
  9. Initial commit + push
  10. Woodpecker secrets verified
  11. DNS + Traefik config for brain.woltje.com
  12. Host init.sql copy + Portainer stack deploy
  13. Smoke test via MCP

Decisions

  • Single Python process for REST + MCP (avoids 2-container overhead for alpha)
  • Streamable HTTP MCP transport (not stdio — deployed service, needs HTTP)
  • bge-m3 via existing Ollama at 10.1.1.42 (verified live)
  • vector(1024) — bge-m3 native, no padding
  • Graceful fallback: thoughts stored without embedding if Ollama unreachable
  • pgvector/pgvector:pg17 official image — no custom build needed

Blockers / Notes

  • Woodpecker CI secrets (GITEA_USERNAME, GITEA_TOKEN) must be set for build pipeline
  • DNS record for brain.woltje.com needs to be created
  • Init SQL must be on host at /opt/openbrain/init.sql before first Portainer deploy
  • MCP auth: headers passed via Claude Code settings — confirm MCP SDK accepts headers on streamable HTTP

Risks

  • MCP streamable HTTP transport is newer spec — need to verify Claude Code supports it
    • Fallback: switch to SSE transport (mcp.server.sse.SseServerTransport)
Reference in New Issue View Git Blame Copy Permalink