natebjones-projects/ob1

1. What this repo is

Open Brain is a multi-surface “personal memory” platform, not a single app. The core idea is one shared database-backed brain that multiple AI clients, capture sources, dashboards, and workflows can all read from and write to.

2. Canonical data layer

The architectural center is PostgreSQL/Supabase with vector search support. The schemas/ directory defines the durable storage model, with thoughts as the base concept and additional sidecar schemas such as agent memory, provenance, audit, search, deduplication, and workflow status.

3. Data lifecycle

The main flow is: capture/import → enrich/embed/classify → store in the database → search/retrieve → review/update/delete. Many recipes and integrations exist to move data into that loop, while dashboards and agent tools sit on top of it for human and AI interaction.

4. Agent and protocol boundary

MCP is the primary access boundary for AI clients. The repo includes a standalone server/ MCP server, a primitives/remote-mcp/ concept, and several integrations that expose memory actions like recall, writeback, update, delete, and inspection through standardized tool interfaces.

5. User-facing dashboards

The dashboards/ folder contains deployable frontends. The main ones are a Next.js dashboard and a SvelteKit dashboard, both centered on browsing thoughts, search, ingest, audit, and memory operations. The Next.js version is more feature-rich and includes API routes, middleware/auth, kanban, settings, and agent-memory views.

6. Backend surface in the dashboards

The dashboard apps are not just static UIs; they also host server routes for operations like ingest, search, audit, duplicates resolution, restricted toggles, logout, and thought connections. That makes each dashboard a thin app shell plus a server-side API layer that talks to the core brain.

7. Ingestion and capture integrations

integrations/ holds runtime adapters that push external signals into Open Brain. These include Slack/Discord capture, agent-memory APIs, entity extraction, consolidation workers, and deployment-specific adapters like Kubernetes and OpenClaw plugin support. These are the main entry points for live data.

8. Recipes as operational workflows

recipes/ contains one-off or repeatable pipelines for importing and transforming external data: Gmail, ChatGPT, Obsidian, X/Twitter, Instagram, Google Activity, Grok, Readwise, Blogger, and more. Many recipes also include SQL migrations, backfills, or smoke tests, so they represent full data-engineering workflows rather than just docs.

9. Extensions as productized brain modules

extensions/ are the curated, user-facing “learning path” modules such as household knowledge, home maintenance, family calendar, meal planning, professional CRM, and job hunt. These are larger app-level subsystems intended to compound on the shared brain data model.

10. Skills and prompts as non-runtime assets

skills/ is a library of reusable agent instructions, and resources/ and docs/ contain companion content, walkthroughs, diagrams, and setup material. These are not runtime services; they are part of the product architecture because they shape how agents and humans use the system.

11. Primitives as cross-cutting patterns

primitives/ collects reusable architectural patterns such as deployment, remote MCP connectivity, RLS, troubleshooting, and shared MCP access. In the repo structure, primitives sit below extensions and recipes as shared building blocks used across multiple workflows.

12. Governance and automation

GitHub workflows handle review automation, triage, labeling, announcements, README updates, and contributor onboarding. This means repository governance is part of the architecture: contributions are machine-checked before human review, which matters because the repo contains many independently maintained modules.

13. Technology mix matters

The repo is intentionally polyglot: Next.js/TypeScript, SvelteKit, Deno edge functions, SQL migrations, shell scripts, Python utilities, and some Python plugin code. The stack varies by subsystem, but the boundary is consistent: all roads lead back to the shared brain database and its MCP-accessible tools.

14. How to draw it

A good diagram would show a central database brain, surrounded by:

- AI clients connected through MCP/server tools

- capture/import integrations feeding the brain

- dashboards reading and modifying the same data

- recipes/skills/docs as operational and instructional layers

- GitHub automation governing changes and publishing