mybrain-overview

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.