mosaic/openbrain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
openbrain/docs/PRD.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

2.7 KiB
Raw Permalink Blame History

OpenBrain — Product Requirements Document

Version: 0.0.1 Status: Active Owner: Jason Woltje

Problem

AI agents and tools have no shared persistent memory. Every session starts from zero. Platform memory (Claude, ChatGPT, etc.) is siloed — each tool can't see what the others know. This forces constant context re-injection, burns tokens, and prevents compounding knowledge.

Goal

A self-hosted, agent-readable semantic brain that any AI tool can plug into via MCP. One database. Standard protocol. Owned infrastructure. No SaaS middlemen.

Users

  1. Jason — primary human user, captures thoughts from any AI tool
  2. AI agents — Claude Code, Codex, Claude Desktop, any MCP-compatible client
  3. Future: Mosaic Stack integration as the knowledge layer for the agent fleet

Requirements

v0.0.1 (Alpha — Current)

ID Requirement Priority
R1 Capture a thought with content, source, and metadata Must
R2 Generate vector embedding via Ollama (bge-m3) Must
R3 Semantic search by meaning (cosine similarity) Must
R4 List recent thoughts Must
R5 Usage stats (total, embedded, by source) Must
R6 REST API with Bearer token auth Must
R7 MCP server (streamable HTTP) exposing all 4 tools Must
R8 Deployable as Portainer/Swarm stack Must
R9 CI/CD via Woodpecker (lint + build + push) Must
R10 Graceful embedding fallback (store without vector if Ollama down) Must
R11 Public repo — zero secrets in code Must

v0.1.0 (Future)

  • Thought tagging and tag-based filtering
  • Batch import (ingest jarvis-brain data, Claude memory, etc.)
  • Scheduled re-embedding for thoughts stored without vectors
  • Webhook capture endpoint (ingest from any tool without MCP)
  • Usage dashboard (thoughts/day, source breakdown)
  • Mosaic Stack integration (knowledge module backend)

Acceptance Criteria (v0.0.1)

  1. POST /v1/thoughts stores a thought and returns it with embedded=true when Ollama is reachable
  2. POST /v1/search with a natural-language query returns semantically relevant results
  3. GET /v1/thoughts/recent returns the last N thoughts in reverse chronological order
  4. GET /v1/stats returns total count, embedded count, and source breakdown
  5. MCP server at /mcp exposes all 4 tools (capture, search, recent, stats)
  6. Claude Code can connect to the MCP server and execute all 4 tools
  7. Portainer stack deploys both brain-db and brain-api successfully
  8. CI pipeline runs on push to main and produces a tagged image

Out of Scope (v0.0.1)

  • User accounts / multi-user
  • Workspace isolation
  • Web UI
  • Rate limiting
  • Mosaic Stack integration
Reference in New Issue View Git Blame Copy Permalink