2Brain

Facts

Fact	Value
Status	active
Hosting platform	cloudflare
Repository	https://github.com/meta4m/2Brain
Tech stack	language: typescript, language: python, framework: astro-starlight, ui: svelte, database: cloudflare-d1, vector_database: cloudflare-vectorize, runtime: cloudflare-workers, ai_gateway: cloudflare-ai-gateway, auth: cloudflare-zero-trust, search: pagefind, graph: graphify
Tags	second-brain, knowledge-base, cloudflare, mcp-server
Last audited	2026-09-15
Upstream dependencies	None declared
Downstream dependencies	None declared

Secrets manifest

Key names and metadata only. Encrypted records are available in this project’s vault below.

Key	Description	Environments	Required
`CLOUDFLARE_API_TOKEN`	Cloudflare API token with D1, Vectorize, and Pages deployment permissions (CI)	production, development	Yes
`AI_GATEWAY_TOKEN`	AI Gateway invoke token (Run permission) — runtime chat auth via the 2brain-gateway	production, development	Yes
`GOOGLE_AI_STUDIO_KEY`	Gemini provider key stored gateway-side via BYOK (Secrets Store), not in app runtime	production	No
`GROQ_API_KEY`	Groq provider key stored gateway-side via BYOK (Secrets Store), not in app runtime	production	No

Overview

Project Overview: 2Brain

Mission: A resilient, perpetual knowledge storage and retrieval system — projects, notes, captures, and secrets in one place — eliminating context fragmentation and cognitive rot.
Target Audience: The operator (software engineer) and autonomous AI coding agents (Claude Code, Cursor, Antigravity).
Lifecycle State: active — retrieval infrastructure complete and production-verified; product focus is shifting to capture and interactive editing (see SSOT §8 roadmap).

Core Capabilities

Plaintext Source of Truth: Git-backed Markdown catalogs + standard SQLite (D1).
Zero-Knowledge Secret Vault: Browser Web Crypto AES-256-GCM; D1 stores only ciphertext.
Static Knowledge Graph: Graphify-compiled, embedded in the portal at /graph.
Tri-Layer Retrieval: Pagefind, D1 FTS5, Cloudflare Vectorize.
Agent-Native MCP Server: /api/mcp, protocol 2024-11-05.
RAG Q&A: /api/ask over retrieved documentation context.

Key References

Master Architecture (SSOT): ARCHITECTURE_AND_ROADMAP.md
Agent Directives: AGENTS.md
Work Tracking: GitHub issues
Architecture: architecture.md · Deployment: deployment.md

Architecture

Architecture & System Design: 2Brain

The authoritative architecture for 2Brain — ADRs, cryptographic contracts, database schemas, MCP interface, and operational runbooks — is maintained in a single place:

ARCHITECTURE_AND_ROADMAP.md (SSOT)

This stub exists so the project catalog remains self-describing without duplicating (and drifting from) the master specification. 2Brain is one cataloged project among the others — altbrain is merely the subdomain the portal happens to run on.

Key facts at a glance:

Platform: Cloudflare Pages + D1 + Vectorize + Workers AI + AI Gateway ($0.00/month)
Portal: Astro Starlight + Svelte at altbrain.pages.dev
Retrieval: Pagefind (client) / FTS5 (exact) / Vectorize (semantic)
Agents: MCP server at /api/mcp (protocol 2024-11-05)
Secrets: client-side AES-256-GCM vault in D1, Access-gated, fails closed

Deployment

Deployment & Operational Runbook: 2Brain

Deployment and operations are fully specified in the SSOT:

CI/CD & credentials: ARCHITECTURE_AND_ROADMAP.md §5 Operations — workflow steps, token scopes, verification
Access provisioning: ARCHITECTURE_AND_ROADMAP.md §6 — Cloudflare Access runbook

Key facts at a glance:

Production: https://altbrain.pages.dev — auto-deploy on push to main via GitHub Actions
Pipeline: spec validation → project-page generation → graph compile → D1 sync → tests → typecheck → build → page verification → Pages deploy
Embedding ingestion: excluded from deployment. Reindexing and its triggers are parked pending a clear knowledge-ingestion direction.
Verification: ./scripts/verify-production.sh must pass before any production claim
Vault status: fails closed (HTTP 503) until the Access application is provisioned (issue #1)
Local dev: cp portal/.dev.vars.example portal/.dev.vars, then pnpm --dir portal dev

Project vault

Cloudflare Access authorization and your passphrase are required to retrieve and decrypt stored values.

Client-Side Encrypted Secret Vault

Zero-knowledge architecture. Secrets are encrypted client-side using Web Crypto AES-256-GCM before leaving this browser tab. Edge databases store only ciphertext, IV, and salt.

Vault Passphrase (PBKDF2-SHA256, 100,000 iterations):

Encrypted Records for `2brain` (0)

Encrypted records have not been loaded.