mybrain-overview

name	mybrain-overview
description	Use when users ask about MyBrain, what it does, how it works, what tools are available, or how to use the personal knowledge base. Covers architecture, tools, deployment modes, and usage.

MyBrain -- Overview

MyBrain is a personal knowledge base with semantic search. It stores thoughts, ideas, notes, and context in PostgreSQL with vector embeddings, making everything searchable by meaning -- not just keywords.

It works as an MCP (Model Context Protocol) server, accessible from Claude Code CLI and Claude Desktop.

Deployment Modes

Mode	Database	Best For
Docker	Local PostgreSQL + pgvector in containers	Self-contained, no external dependencies
RDS	Shared AWS RDS with ltree scoping	Teams, multi-project, persistent cloud storage

Run /mybrain-setup to install either mode.

How It Works

Storing a thought

1. You say "remember this: ..." to Claude
2. Claude calls capture_thought with your text
3. The server sends text to OpenRouter (text-embedding-3-small) for a 1536-dim vector
4. Text, vector, metadata, and scope are stored in PostgreSQL
5. HNSW index on the embedding column enables fast search

Searching

1. You ask "what do I know about X?"
2. Claude calls search_thoughts with your query
3. Query is embedded via OpenRouter, then matched using match_thoughts_scored()
4. Three-axis scoring: (3.0 * relevance) + (2.0 * importance) + (0.5 * recency)
5. Results return sorted by combined score

ltree Scoping

When BRAIN_SCOPE is set (e.g. personal, myproject.app), all queries filter by scope. This lets multiple users or projects share one database without interference.

• Docker mode: scope is optional (single-user, single database)
• RDS mode: scope is required (shared database, multi-tenant)

Tools

Tool	Description	Uses OpenRouter	Cost
capture_thought	Save a thought with metadata	Yes	~$0.0001
search_thoughts	Semantic search with scored ranking	Yes	~$0.0001
browse_thoughts	List recent thoughts, filter by metadata	No	Free
brain_stats	Total count, date range, top metadata	No	Free

Usage Examples

• "Remember this: Sarah mentioned she wants to start a consulting business"
• "What do I know about Sarah?"
• "Show me my recent thoughts"
• "How many thoughts do I have?"
• "Search for anything about project architecture"
• "Capture thought: The deploy pipeline needs a staging gate before prod"

Architecture

Docker mode:
Claude Code --HTTP--> mybrain_mcp (port 8787) --> mybrain_postgres
                                              --> OpenRouter (embeddings)

RDS mode:
Claude Code --stdio--> server.mjs --> AWS RDS (projects_brain)
                                  --> OpenRouter (embeddings)

Claude Desktop (either mode):
Claude Desktop --HTTPS--> Cloudflare Tunnel --> server.mjs (HTTP :8787)

Schema

The database uses the full atelier brain schema:

• thoughts table with ltree scope, thought_type, importance, status
• thought_relations for typed edges between thoughts
• match_thoughts_scored() -- three-axis scoring function
• HNSW index on embeddings, GiST index on scope, GIN index on metadata

State

All data lives in PostgreSQL. OpenRouter is only used for generating embeddings -- no thought content leaves your database.