OneBrain

License: AGPL-3.0 CI npm TypeScript Docker GDPR

Your AI Memory Layer. OneBrain stores your identity, preferences, knowledge, decisions, and projects in a structured system — and delivers optimized context to any AI assistant via REST API or MCP protocol.

Available as hosted SaaS (zero setup) or self-hosted on your own infrastructure. Both modes are 100% GDPR/DSGVO-compliant with EU data residency.

Try it now — no installation required

onebrain.rocks is a free, live instance you can use immediately:

  • Sign up with a magic link (no password needed)
  • Create memories, connect your AI tools, explore the API
  • Invite AI agents via invite links
  • Full API documentation at onebrain.rocks/api/eu/v1/openapi

Register your AI agent

Use these public invite links to connect your AI agent to OneBrain:

Access Level Invite Link
Read-Only (context, brain, entities) onebrain.rocks/invite/MgjYQqncucDU
Read + Write (full access) onebrain.rocks/invite/PfmfKDMdxkCs

Or register via API:

curl -X POST https://onebrain.rocks/api/eu/v1/invite/register \
  -H "Content-Type: application/json" \
  -d '{"code": "MgjYQqncucDU", "name": "MyAgent", "description": "My AI agent"}'

Want to self-host instead? See Quick Start below.

What is OneBrain?

OneBrain is a persistent, structured memory for humans and AI agents alike. Instead of repeating yourself in every conversation, OneBrain maintains a living profile of who you are, what you know, and what you're working on. Any AI tool — or any AI agent — can query OneBrain to get personalized, relevant context.

For humans: Sync all your AI tools so you never have to explain yourself from scratch again. Tell Claude once, and ChatGPT, Gemini, and every other tool already knows.

For agents: AI agents use OneBrain the same way. An agent stores its knowledge once, and it's available everywhere — across sessions, tools, and platforms.

Key principles:

  • For humans & agents — both store and share knowledge through the same system
  • Privacy-first — your data stays yours. EU/GLOBAL region isolation, httpOnly cookies, encrypted at rest
  • Deterministic — no ML, no embeddings, fully explainable merge logic
  • Multi-language — DE/EN/ES out of the box, extensible to any language
  • AI-agnostic — works with any LLM via REST API or MCP protocol
  • GDPR-compliant — privacy by design, data minimization, consent management, full data portability
  • SaaS or Self-Hosted — DEPLOYMENT_MODE=saas|selfhosted controls features

Architecture

                    ┌──────────────────────────────────────────┐
                    │              Control Plane                │
                    │  ┌────────┐    ┌────────────────────┐    │
                    │  │ Caddy  │───▶│  Web App (Next.js) │    │
                    │  │ :443   │    │  28 pages, PWA     │    │
                    │  └───┬────┘    └────────────────────┘    │
                    └──────┼───────────────────────────────────┘
                           │
              ┌────────────┼────────────────┐
              │ /api/eu    │                │ /api/global
              ▼            │                ▼
  ┌───────────────────┐    │    ┌───────────────────┐
  │    EU Region      │    │    │   GLOBAL Region   │
  │                   │    │    │                   │
  │  ┌─────────────┐  │    │    │  ┌─────────────┐  │
  │  │ Fastify API │  │    │    │  │ Fastify API │  │
  │  │   :3001     │  │    │    │  │   :3001     │  │
  │  └──┬──────┬───┘  │    │    │  └──┬──────┬───┘  │
  │     │      │      │    │    │     │      │      │
  │  ┌──▼──┐ ┌─▼───┐  │    │    │  ┌──▼──┐ ┌─▼───┐  │
  │  │ PG  │ │Redis│  │    │    │  │ PG  │ │Redis│  │
  │  │ 16  │ │  7  │  │    │    │  │ 16  │ │  7  │  │
  │  └─────┘ └─────┘  │    │    │  └─────┘ └─────┘  │
  │                   │    │    │                   │
  │  ┌─────────────┐  │    │    │  ┌─────────────┐  │
  │  │ MCP Server  │  │    │    │  │ MCP Server  │  │
  │  │  (stdio)    │  │    │    │  │  (stdio)    │  │
  │  └─────────────┘  │    │    │  └─────────────┘  │
  └───────────────────┘    │    └───────────────────┘
                           │
              Strict network isolation
              No shared DB between regions

Region isolation ensures EU and GLOBAL data never mix — separate PostgreSQL databases, Redis instances, Docker networks, and compose stacks.

Tech Stack

Layer Technology Version
API Server Fastify 5.2
Frontend Next.js + React 15.1 / 19.0
Database PostgreSQL + Prisma 16 / 6.x
Cache Redis 7
Auth Magic Link + JWT + OAuth + TOTP jose 6.0
Payments Stripe (built-in, not active) 20.4
MCP Model Context Protocol SDK 1.27
Validation Zod 3.23
i18n JSON-based (DE/EN/ES) —
Security Helmet, HSTS, CSP, CSRF —
Reverse Proxy Caddy (auto-HTTPS) 2
Containers Docker (multi-stage, non-root) —
Build Turborepo + pnpm 2.3 / 9.15
Testing Vitest 3.0
CI/CD GitHub Actions —

Monorepo Structure

onebrain/
├── apps/
│   ├── api/                  # REST API (Fastify 5.2, port 3001)
│   │   ├── src/
│   │   │   ├── routes/       # 26 route modules (~150 endpoints)
│   │   │   ├── services/     # 27 business logic services
│   │   │   ├── middleware/    # 3 middleware (auth, limits, email verify)
│   │   │   ├── lib/          # 18 utilities (audit, cache, tokens, PII mask...)
│   │   │   │   └── context-engine/  # Relevance scoring + token compression
│   │   │   └── __tests__/    # 23 test files (365 tests)
│   │   └── package.json
│   ├── web/                  # Web UI (Next.js 15, port 3000)
│   │   ├── src/
│   │   │   ├── app/          # 28 pages (App Router)
│   │   │   └── components/   # 27 components (CSS Modules)
│   │   ├── public/           # PWA manifest, service worker, icons
│   │   └── package.json
│   └── mcp/                  # MCP server for AI tools (stdio)
│       └── package.json
├── packages/
│   ├── db/                   # Prisma schema (31 models, 8 enums)
│   │   └── prisma/
│   │       ├── schema.prisma
│   │       └── migrations/   # 5 migrations
│   ├── shared/               # TypeScript types
│   ├── schemas/              # 14 Zod validation schemas
│   └── i18n/                 # Translations (DE/EN/ES)
├── infra/
│   ├── control-plane/        # Caddy + Web (docker-compose)
│   ├── region-eu/            # EU-isolated stack (docker-compose)
│   ├── region-global/        # Global-isolated stack (docker-compose)
│   └── docker/               # Multi-stage Dockerfiles (API, Web, MCP)
├── .github/workflows/        # CI/CD (ci.yml, deploy.yml)
├── .env.example              # Environment template
├── CHANGELOG.md              # Version history
├── FEATURELIST.md            # 455 features (20 categories)
└── DSGVO-REPORT.md           # GDPR compliance report

🧩 Integrations & SDKs

OneBrain works with your favorite tools and frameworks out of the box:

Integration Language Install
MCP Server (Claude, Cursor, Windsurf) TypeScript npx onebrain-mcp
Python SDK Python pip install onebrain-sdk
LangChain Python pip install onebrain-langchain
LlamaIndex Python pip install onebrain-llama-index
Vercel AI SDK TypeScript npm install onebrain-ai-sdk
OpenClaw TypeScript onebrain-openclaw
Node.js SDK TypeScript npm install onebrain
Laravel SDK PHP composer require onebrain/laravel

All integrations are open-source (AGPL-3.0) and self-hosted compatible.

Quick Start

Prerequisites

  • Node.js >= 20
  • pnpm >= 9
  • PostgreSQL 16
  • Redis 7 (optional for dev, required for production)

Installation

# Clone and install
git clone <repo-url> onebrain
cd onebrain
pnpm install

# Create database
createdb onebrain

# Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL, JWT_SECRET (min 32 chars)

# Run migrations & generate Prisma client
DATABASE_URL="postgresql://user@localhost:5432/onebrain" \
  pnpm --filter @onebrain/db exec prisma migrate deploy

pnpm --filter @onebrain/db exec prisma generate

Start Development

# All apps at once (via Turborepo)
pnpm dev

# Or individually:

# Terminal 1: API (port 4002)
DATABASE_URL="postgresql://user@localhost:5432/onebrain" \
  API_PORT=4002 \
  pnpm --filter @onebrain/api exec tsx src/index.ts

# Terminal 2: Web (port 3000)
NEXT_PUBLIC_API_URL=http://localhost:4002 \
  pnpm --filter @onebrain/web exec next dev

Demo Login

In development mode (NODE_ENV !== 'production'), demo logins are available:

  1. Open http://localhost:3000/login
  2. Click "Demo Login (Development)" for admin access
  3. Or use "Demo User Login" for regular user access

Demo admin: [email protected] — Demo user: [email protected]

SDK — npm install onebrain

The official OneBrain SDK gives you typed access to the entire API from Node.js, Deno, or any JavaScript/TypeScript runtime.

npm install onebrain

Quick Example

import { OneBrain } from 'onebrain';

const brain = new OneBrain({
  apiKey: 'ob_your_key_here',
  baseUrl: 'https://onebrain.rocks/api/eu', // default
});

// Read your brain context
const context = await brain.context.get('assistant');
console.log(context.text);

// Write a memory
await brain.memory.create({
  type: 'fact',
  title: 'Likes TypeScript',
  body: 'Prefers TS over JS for all projects',
});

// Search memories
const results = await brain.memory.search({ query: 'TypeScript' });

// Agent Sync — read full context
const sync = await brain.connect.read();

// Agent Sync — write batch memories
await brain.connect.writeMemories([
  { type: 'preference', title: 'Dark mode', body: 'Prefers dark themes' },
  { type: 'skill', title: 'React', body: 'Advanced React developer' },
]);

SDK Features

Module Methods
brain.memory create, get, update, delete, list, search, extract, import, consolidate
brain.entity create, get, update, delete, list, addLink, graph, merge, autoExtract
brain.project create, get, update, delete, list, addMemoryLink
brain.brain profile, updateProfile, context
brain.context get (scopes: brief, assistant, project, deep)
brain.connect read, writeMemory, writeMemories (Agent Sync Protocol)
brain.billing usage, plan
brain.apiKeys list, create, updateTrustLevel, revoke

Configuration

const brain = new OneBrain({
  apiKey: 'ob_your_key', // Required — get from dashboard
  baseUrl: 'https://...', // Default: https://onebrain.rocks/api/eu
  timeout: 10000, // Default: 10s
  headers: { 'X-Custom': 'val' }, // Optional extra headers
});

Error Handling

import { OneBrainError, OneBrainTimeoutError } from 'onebrain';

try {
  await brain.memory.create({ type: 'fact', title: 'Test', body: 'test' });
} catch (err) {
  if (err instanceof OneBrainTimeoutError) {
    console.error('Request timed out');
  } else if (err instanceof OneBrainError) {
    console.error(err.code, err.message, err.requestId);
  }
}
  • Zero runtime dependencies
  • Dual ESM/CJS builds
  • Full TypeScript types
  • Node.js >= 18
  • AGPL-3.0 License

Links:

Authentication

OneBrain supports multiple authentication methods:

Method Use Case Flow
Magic Link Primary login Email → verify token → JWT
Password Optional Email + password → JWT
OAuth 2.0 Google (Apple planned) ID token → JWT
TOTP Two-factor auth Password/magic link + 6-digit code
API Key External tools, MCP Authorization: ApiKey ob_xxx

Token Strategy

  • Access token: 15min, httpOnly cookie (accessToken, secure, sameSite strict)
  • Refresh token: 7d, httpOnly cookie (path-scoped to /v1/auth)
  • CSRF protection: X-Requested-With header required for cookie-based auth
  • API keys: SHA-256 hashed, prefix-based (ob_), scoped permissions

Available API Key Scopes

Scope Access
brain.read Read brain profile, context, and memory
brain.write Update brain profile
memory.extract.write Create memories via text extraction
entity.read Read entities and entity links
entity.write Create, update, and delete entities
connect.read Read brain context via Connect protocol
connect.write Write memories via Connect protocol

API Keys and 2FA

API keys are machine-to-machine credentials. They bypass 2FA/TOTP completely — this is by design. Two-factor authentication is only enforced for interactive human login (password, magic link, OAuth). API keys authenticate via timing-safe hash comparison and are scoped to specific permissions, making them safe for automated agents and CI/CD pipelines.

Admin routes always require an interactive session and reject API key auth.

Privacy by Design — Zero-Knowledge Identity

OneBrain's authentication system is intentionally built to decouple your identity from your knowledge.

What we store: Your email address and your 2FA secret — nothing else. No name, no phone number, no profile picture, no billing address. Your email is the key to the door, and your authenticator app is the lock.

What this means: The memories, skills, entities, and projects inside your OneBrain are never tied to a real-world identity. There is no username, no display name, no social profile linking back to you. Your knowledge exists in OneBrain — but OneBrain doesn't know who you are.

This is by design, not by accident:

Principle Implementation
Minimal identity Only email + TOTP secret stored — no name, phone, or address
No profile linking No social graphs, no friend lists, no public profiles
Pseudonymous usage API keys and sessions reference a UUID, never a person
Knowledge ≠ Identity Your brain's content cannot be traced back to you without your email
2FA as gatekeeper Mandatory TOTP ensures that even email access alone isn't enough

The result: even if someone accessed the database directly, they would find encrypted memories linked to anonymous UUIDs — with no way to connect them to a real person without the corresponding email and 2FA credentials.

API Reference

Base URL: /v1 — All endpoints return { data, error, meta } envelope.

Auth (7 endpoints)

Method Endpoint Auth Description
POST /v1/auth/magic-link — Request magic link email
POST /v1/auth/verify — Verify token, set JWT cookies
POST /v1/auth/refresh Cookie Refresh access token
POST /v1/auth/logout JWT End current session
POST /v1/auth/logout-all JWT End all sessions
POST /v1/auth/region JWT Set data region (EU/GLOBAL)
GET /v1/auth/me JWT Current user profile

Password Auth (2 endpoints)

Method Endpoint Auth Description
POST /v1/auth/register — Register with email + password
POST /v1/auth/login — Login with email + password

OAuth (3 endpoints)

Method Endpoint Auth Description
POST /v1/auth/oauth/google — Google OAuth login (ID token)
POST /v1/auth/oauth/apple — Apple OAuth login (ID token)
POST /v1/auth/oauth/github — GitHub OAuth login (code exchange)

TOTP (3 endpoints)

Method Endpoint Auth Description
POST /v1/auth/totp/setup JWT Generate TOTP secret + QR URI
POST /v1/auth/totp/verify JWT Verify and enable TOTP
POST /v1/auth/totp/disable JWT Disable TOTP

Sessions (2 endpoints)

Method Endpoint Auth Description
GET /v1/sessions JWT List active sessions
DELETE /v1/sessions/:id JWT Revoke specific session

Brain & Memory (8 endpoints)

Method Endpoint Auth Description
GET /v1/brain/profile JWT/Key User identity profile
PUT /v1/brain/profile JWT/Key Update identity profile
GET /v1/brain/context JWT/Key Full brain projection
GET /v1/memory JWT/Key List memories (paginated)
POST /v1/memory JWT/Key Create memory
GET /v1/memory/:id JWT/Key Single memory
PATCH /v1/memory/:id JWT/Key Update memory
DELETE /v1/memory/:id JWT/Key Delete memory

Memory Extraction & Ingestion (3 endpoints)

Method Endpoint Auth Description
POST /v1/memory/extract JWT/Key AI memory extraction from text
POST /v1/ingest/url JWT Ingest content from URL (SSRF-protected)
POST /v1/ingest/file JWT Ingest uploaded file (PDF, text)

Context Engine (1 endpoint)

Method Endpoint Auth Description
GET /v1/context/:scope JWT/Key Optimized LLM context

Scopes: brief (500 tokens), assistant (2K), project (3K), deep (8K)

Content negotiation: Accept: text/plain returns formatted text for direct LLM injection.

Entities (5 endpoints)

Method Endpoint Auth Description
GET /v1/entities JWT/Key List entities (paginated)
POST /v1/entities JWT/Key Create entity
PATCH /v1/entities/:id JWT/Key Update entity
DELETE /v1/entities/:id JWT/Key Delete entity
POST /v1/entities/:id/links JWT/Key Create entity relationship

Projects (5 endpoints)

Method Endpoint Auth Description
GET /v1/projects JWT List projects (paginated)
POST /v1/projects JWT Create project
PATCH /v1/projects/:id JWT Update project
DELETE /v1/projects/:id JWT Delete project
POST /v1/projects/:id/memory-links JWT Link memory to project

Tags (4 endpoints)

Method Endpoint Auth Description
GET /v1/tags JWT List tags
POST /v1/tags JWT Create tag
POST /v1/memory/:id/tags JWT Tag a memory
DELETE /v1/memory/:id/tags/:tagId JWT Remove tag from memory

Merge Engine (2 endpoints)

Method Endpoint Auth Description
POST /v1/merge/run JWT Run deterministic merge cycle
GET /v1/merge/history JWT View merge logs

Daily Learning (3 endpoints)

Method Endpoint Auth Description
GET /v1/daily-question/today JWT Today's learning question
POST /v1/daily-question/:id/answer JWT Submit answer
GET /v1/daily-question JWT Question history (paginated)

API Keys (4 endpoints)

Method Endpoint Auth Description
GET /v1/api-keys JWT List API keys
POST /v1/api-keys JWT Create API key
DELETE /v1/api-keys/:id JWT Revoke API key
PATCH /v1/api-keys/:id JWT Update agent config (name, trust, scopes, rate limit)

Connected Agents (7 endpoints)

Method Endpoint Auth Description
GET /v1/agents JWT List agents with sync stats
GET /v1/agents/summary JWT Cross-agent summary (calls, errors, candidates)
GET /v1/agents/activity JWT All-agent activity feed (paginated)
GET /v1/agents/:id/summary JWT Single-agent summary
GET /v1/agents/:id/activity JWT Single-agent activity feed
POST /v1/agents/:id/candidates JWT Bulk approve/dismiss candidates
GET /v1/connect/:key/delta ApiKey Delta sync — memories updated since last query

Sharing & Export (6 endpoints)

Method Endpoint Auth Description
POST /v1/shares JWT Create brain snapshot
GET /v1/shares/:token — View snapshot (public)
GET /v1/export/json JWT Full brain export (JSON)
GET /v1/export/markdown JWT Full brain export (Markdown)
GET /v1/export/ai-prompt JWT AI system prompt from brain
POST /v1/referrals JWT Create referral code

User & GDPR (5 endpoints)

Method Endpoint Auth Description
GET /v1/user/profile JWT User profile
PATCH /v1/user/profile JWT Update profile
GET /v1/user/export JWT GDPR data export (14 categories)
DELETE /v1/user JWT Account deletion (soft delete, 30d grace)
GET /v1/user/usage-summary JWT Current usage stats

Billing (4 endpoints, conditional)

Registered only when STRIPE_SECRET_KEY is set.

Method Endpoint Auth Description
POST /v1/billing/checkout JWT Create Stripe checkout session
GET /v1/billing/portal JWT Stripe customer portal URL
GET /v1/billing/subscription JWT Current subscription status
POST /v1/billing/change-plan JWT Upgrade/downgrade plan

Webhooks (1 endpoint, conditional)

Method Endpoint Auth Description
POST /v1/webhooks/stripe Stripe sig Stripe event handler

Admin (8+ endpoints)

All require admin role.

Method Endpoint Description
GET/POST/PATCH /v1/admin/plans Plan CRUD
GET/POST /v1/admin/plans/:id/limits Plan limits
GET/POST /v1/admin/plans/:id/features Plan features
GET/PATCH /v1/admin/users User management
GET /v1/admin/usage/:userId Usage statistics
GET /v1/admin/audit-logs Audit logs (paginated)

Legal & OpenAPI (4 endpoints)

Method Endpoint Auth Description
GET /v1/legal/impressum — Legal notice (JSON)
GET /v1/legal/datenschutz — Privacy policy (JSON)
GET /v1/legal/agb — Terms of service (JSON)
GET /v1/openapi.json — OpenAPI specification

Health (1 endpoint)

Method Endpoint Description
GET /health DB connectivity check, system status

MCP Server

Connect OneBrain to any MCP-compatible AI tool (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "onebrain": {
      "command": "node",
      "args": ["apps/mcp/dist/index.js"],
      "env": {
        "ONEBRAIN_API_URL": "http://localhost:4002",
        "ONEBRAIN_API_KEY": "ob_your_api_key_here"
      }
    }
  }
}

6 MCP tools available:

Tool Description
get_user_context Full brain context for AI personalization
search_memory Filter memories by type, status, keyword
write_memory Extract and store new memories from text
upsert_entity Find or create people, places, concepts
get_project_context Project details with linked memories
get_daily_question Today's learning question

All MCP tools delegate to the REST API — no duplicated business logic.

Context Engine

The context engine delivers optimized, token-budgeted context to AI tools. It scores items by relevance (source priority 35% + confidence 35% + recency 30%), filters by scope, and compresses to fit the token budget.

Scope Token Budget Use Case
brief 500 Quick lookups, chat titles
assistant 2,000 Standard AI conversations
project 3,000 Project-focused work
deep 8,000 Comprehensive analysis 
# JSON response (default)
curl http://localhost:4002/v1/context/assistant \
  -H "Authorization: ApiKey ob_your_key"

# Plain text (for direct LLM system prompt injection)
curl http://localhost:4002/v1/context/assistant \
  -H "Authorization: ApiKey ob_your_key" \
  -H "Accept: text/plain"

Identity (user profile) is never dropped during compression — it is always included regardless of budget constraints.

AI Integration (Sync Protocol)

Overview

OneBrain keeps all your AI assistants in sync. Give any AI a single Connect URL once — it reads your context and writes back new learnings automatically. No plugins to install, no platform-specific configuration, no manual copy-pasting between tools.

The Sync Protocol v1 is a two-endpoint contract:

  1. Read — AI fetches a system prompt containing the user's full brain context
  2. Write-back — AI sends new learnings to OneBrain as structured memories

Any AI that can make HTTP requests can participate. The protocol is embedded directly in the system prompt, so the AI knows how and when to sync without additional instruction.

Sync Protocol v1

How It Works

  1. You generate a Connect URL in the OneBrain dashboard (Settings > Integrations)
  2. You give that URL to an AI assistant (paste it as a system prompt, add it as an MCP server, or configure it as a plugin)
  3. The AI reads your context via GET /v1/connect/:apiKey — it receives a system prompt containing your identity, preferences, knowledge, and active projects
  4. During conversation, the AI detects new information worth remembering
  5. The AI writes it back via POST /v1/connect/:apiKey/memory — silently, in the background
  6. All your other connected AIs pick up the new memory on their next read

User Commands

Command Behavior
OBIgnore Pauses write-back. The AI still uses existing context but stops saving new information until OBSync or a new conversation.
OBSync Resumes normal sync behavior after an OBIgnore.
OBStatus AI reports whether sync is active or paused, and how many items were synced in the current conversation.

What Gets Synced

  • New project decisions or status updates
  • Preferences the user expresses (tools, languages, workflows)
  • Facts about the user (role changes, new skills, expertise)
  • Goals the user mentions
  • Important experiences or lessons learned

What Does NOT Get Synced

  • Trivial conversation (greetings, small talk)
  • Information already present in the user's brain context
  • Temporary debugging sessions or one-off questions
  • Passwords, tokens, API keys, or secrets
  • Raw code snippets (the decision is synced, not the code)

Trust Levels

When an AI writes back a memory, its status depends on the API key's trust level:

Level Behavior Use Case
review Memories saved as candidate — user must approve in dashboard before they become active New or untested integrations (default)
trusted Memories saved as active — immediately available to all connected AIs Established, verified AI connections

Set trust level per API key:

curl -X PATCH https://api.onebrain.rocks/v1/api-keys/:id/trust \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "trustLevel": "trusted" }'

Deduplication

The write-back endpoint runs dedup before saving. If a memory with the same type, similar title (Dice coefficient), and similar body already exists, the POST returns the existing memory with 200 OK instead of creating a duplicate. This prevents redundant entries when multiple AIs learn the same fact.

Integration Methods

Method Platforms Auto-Sync Setup
Connect URL Any AI with HTTP access Read + Write Give URL once as system prompt
MCP Server Claude Desktop, Cursor, Windsurf Read + Write Add to MCP config JSON
ChatGPT Actions ChatGPT Custom GPTs Read + Write Add plugin URL to GPT
REST API Any agent, script, or automation Read + Write Use API key with connect.* scopes
System Prompt Any AI (manual copy-paste) Read only Copy context output, paste as system prompt

Setup Guide

Claude Desktop / Cursor (MCP)

Add this to your MCP configuration file (claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "onebrain": {
      "command": "node",
      "args": ["apps/mcp/dist/index.js"],
      "env": {
        "ONEBRAIN_API_URL": "https://api.onebrain.rocks",
        "ONEBRAIN_API_KEY": "ob_your_api_key_here"
      }
    }
  }
}

The MCP server exposes 6 tools (get_user_context, search_memory, write_memory, upsert_entity, get_project_context, get_daily_question) that delegate to the REST API. See the MCP Server section above for the full tool list.

ChatGPT (Custom GPT)

  1. Create a Custom GPT in ChatGPT
  2. Go to Configure > Actions > Create new action
  3. Set the import URL to: https://api.onebrain.rocks/v1/openapi.json
  4. ChatGPT auto-discovers the Connect read/write endpoints
  5. In the GPT instructions, add your Connect URL: 
    https://api.onebrain.rocks/v1/connect/ob_your_api_key_here
  6. The GPT reads your brain context at conversation start and writes back new learnings automatically

Gemini (Gem)

  1. Go to Gemini > Gems > Create Gem
  2. In the system instruction field, paste your Connect URL output: 
    curl https://api.onebrain.rocks/v1/connect/ob_your_api_key_here
  3. Copy the full text output and paste it as the Gem's system instruction
  4. Gemini reads your context on every conversation
  5. For write-back, include the POST URL in the system instruction — Gemini will use it when it identifies new information

Agents (OpenClaw, CrewAI, LangChain, etc.)

Use the REST API directly in your agent's setup or tool configuration:

# Read brain context (returns system prompt as plain text)
curl https://api.onebrain.rocks/v1/connect/ob_your_api_key_here \
  -H "Accept: text/plain"

# Read with specific scope (brief, assistant, project, deep)
curl "https://api.onebrain.rocks/v1/connect/ob_your_api_key_here?scope=assistant" \
  -H "Accept: text/plain"

# Read as JSON (includes metadata and token estimate)
curl "https://api.onebrain.rocks/v1/connect/ob_your_api_key_here?scope=deep" \
  -H "Accept: application/json"

# Write back a new memory
curl -X POST https://api.onebrain.rocks/v1/connect/ob_your_api_key_here/memory \
  -H "Content-Type: application/json" \
  -d '{
    "type": "decision",
    "title": "Switched from REST to GraphQL for the mobile app",
    "body": "After evaluating both options, decided GraphQL reduces over-fetching on mobile and simplifies the data layer. REST remains for public API."
  }'

Connect API Reference

GET /v1/connect/:apiKey

Reads the user's brain context as an AI-ready system prompt.

Parameter Location Type Default Description
apiKey path string — Full API key (ob_prefix_secret)
scope query string deep Token budget: brief (500), assistant (2K), project (3K), deep (8K)
Accept header string text/plain text/plain for raw prompt, application/json for structured response

Scopes required: connect.read

Rate limit: 30 requests/minute per API key prefix

Response (plain text): Full system prompt with Sync Protocol v1 instructions, user context, and write-back URL.

Response (JSON):

{
  "data": {
    "systemPrompt": "# OneBrain Sync Protocol v1\n...",
    "meta": {
      "tokenEstimate": 4200,
      "scope": "deep",
      "writeBackEnabled": true,
      "generatedAt": "2026-03-21T10:3