Content
# OpenBrain
Fully local AI memory for Apple Silicon. Gives any MCP client persistent semantic memory with vector search — no cloud APIs required.
Everything runs on your Mac: embeddings via MLX on Metal GPU, enrichment via a local LLM, storage in PostgreSQL with pgvector.
Built on the [OB1](https://github.com/NateBJones-Projects/OB1) architecture by [@NateBJones-Projects](https://github.com/NateBJones-Projects).
## Architecture
A Bun MCP server brokers requests from any MCP client to PostgreSQL+pgvector for storage, a local MLX embedding service for vectorization, and a local mlx-lm server for enrichment. Redis caches embeddings and search results. A separate Bun web UI reads directly from PostgreSQL. Everything runs on-device — no cloud APIs in the data path.
## Requirements
- **Apple Silicon Mac** (M1/M2/M3/M4) — required for MLX GPU inference
- **16 GB RAM minimum** for the default model (`Qwen3-8B-4bit`, ~4.5 GB); 32 GB+ lets you run larger enrichment models
- macOS 14+
- [Node.js](https://nodejs.org) 22+ (LTS v24 recommended) and [pnpm](https://pnpm.io) 11+
- [Bun](https://bun.sh) 1.1+ as the runtime (we use `pnpm` to install deps; `bun` to run them)
- Python 3.13+ with [uv](https://docs.astral.sh/uv/)
- [PostgreSQL 17](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension
- [Redis](https://redis.io/) (optional but recommended)
- [Firecrawl](https://firecrawl.dev) API key — used for all web page scraping
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) (optional — YouTube transcript extraction)
### Firecrawl
[Firecrawl](https://firecrawl.dev) handles all web-page scraping (markdown extraction, JS rendering, etc.). It's a cloud service; set your key in `.env`:
```
FIRECRAWL_API_KEY=fc-...
```
Without a key, `POST /api/ingest` for web URLs will return an error.
### Quick install (recommended)
```bash
bash installer/bootstrap.sh
```
This runs the full chain: prerequisites (Homebrew packages, Bun, Python venv with `mlx-lm`), database setup, schema, and launchd services. Idempotent — safe to re-run.
### Manual install
If you'd rather install the prerequisites yourself:
```bash
# Homebrew packages
brew install postgresql@17 pgvector redis uv yt-dlp pnpm
brew services start postgresql@17
brew services start redis
# Node 22+ via nvm (skip if you already have one)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
. ~/.nvm/nvm.sh && nvm install --lts && nvm alias default 'lts/*'
# Optional, for Gmail integration via the agents/ subsystem
brew install gogcli
# Bun via its official installer (no Homebrew formula). We use Bun as the
# runtime (Bun.serve, Bun.spawn) but never `bun install` — that hits a
# macOS SIP/provenance issue. pnpm handles deps.
curl -fsSL https://bun.sh/install | bash
```
After installing Bun, restart your shell (or `source ~/.zshrc`) so the `bun` binary is on your `PATH`.
## Quick Start
```bash
# 1. Clone and enter the repo
git clone https://github.com/sajennings79/apple-silicon-openbrain.git
cd apple-silicon-openbrain
# 2. Configure environment
cp .env.example .env
# Edit .env if needed (defaults work for local setup)
# 3. Run setup (creates database, installs Bun + Python deps)
bash scripts/setup.sh
# 4. Create a Python venv for the LLM enrichment server
python3 -m venv ~/.mlx-venv
~/.mlx-venv/bin/pip install mlx-lm
# 5. Start all services (installs as launchd daemons)
bash scripts/install-services.sh
# 6. Verify everything is running
bun run health
```
Or start services manually:
```bash
bun run dev # MCP server (port 6277)
cd embed-service && uv run server.py # Embedding service (port 6278)
~/.mlx-venv/bin/python -m mlx_lm.server \
--model mlx-community/Qwen3-8B-4bit \
--port 8000 --max-tokens 4096 # LLM enrichment (port 8000)
bun run ui # Web UI (port 6279)
```
## First Run: Model Downloads
Models are pulled from Hugging Face Hub the first time each service starts — there's no separate download step. Both services block on startup until the download completes, then come online.
| Model | Size | Used by | Triggered by |
|-------|------|---------|--------------|
| `mlx-community/Qwen3-Embedding-0.6B-4bit-DWQ` | ~400 MB | Embedding service (`:6278`) | FastAPI startup |
| `mlx-community/Qwen3-8B-4bit` (default) | ~4.5 GB | LLM enrichment (`:8000`) | `mlx_lm.server` startup |
The default LLM is sized for 16 GB RAM systems. To trade RAM for quality, override `LLM_MODEL` in `.env` (and the matching `--model` arg in `~/Library/LaunchAgents/com.openbrain.llm.plist`):
| RAM | Suggested model | Disk |
|-----|-----------------|------|
| 16 GB (default) | `mlx-community/Qwen3-8B-4bit` | ~4.5 GB |
| 32 GB | `mlx-community/Qwen3.6-27B-4bit` (dense) or `mlx-community/Qwen3.6-35B-A3B-4bit` (MoE) | ~17 GB |
| 64 GB+ | `mlx-community/Qwen3.5-122B-A10B-4bit` | ~60 GB |
All models are public repos — no Hugging Face token required. Files cache to `~/.cache/huggingface/hub/` and subsequent starts run fully offline.
If you installed the launchd services, the first-run download happens silently in the background. Watch progress with:
```bash
tail -f logs/embed.log # embedding model (~30s on fast connection)
tail -f logs/llm.log # ~2 min for the default 8B model on a fast connection
```
`bun run health` will report the LLM service as down until its download finishes. Interrupted downloads resume on the next start.
## MCP Client Configuration
OpenBrain exposes both HTTP and stdio MCP transports. Configure your client to point at whichever it supports.
**HTTP transport** (recommended — one shared server for all clients):
```json
{
"mcpServers": {
"openbrain": {
"type": "http",
"url": "http://localhost:6277/mcp"
}
}
}
```
**stdio transport** (for clients that spawn the server as a subprocess):
```json
{
"mcpServers": {
"openbrain": {
"type": "stdio",
"command": "bun",
"args": ["run", "/path/to/openbrain/src/stdio.ts"]
}
}
}
```
The exact config-file location depends on your client (e.g. `.mcp.json` in a project root, or a global config under your home directory).
## MCP Tools
| Tool | Description |
|------|-------------|
| **StoreMemory** | Store text with automatic embedding, LLM enrichment (summary, tags, entities), and cross-memory linking |
| **SearchMemory** | Semantic vector search with optional filters (type, source, tags, date range) |
| **RecallMemory** | Retrieve a specific memory by UUID |
| **ListMemories** | Paginated list with filters |
| **UpdateMemory** | Update content or metadata; re-embeds and re-enriches on content changes |
| **DeleteMemory** | Soft-delete a memory by UUID |
## Services
| Service | Port | Purpose |
|---------|------|---------|
| MCP Server | 6277 | MCP protocol + URL ingestion API |
| Embedding Service | 6278 | Local MLX embeddings (Qwen3-Embedding-0.6B, 1024-dim) |
| LLM Server | 8000 | Local MLX enrichment (Qwen3-8B by default) |
| Web UI | 6279 | Dashboard for browsing and searching memories |
| PostgreSQL | 5432 | Memory storage with pgvector |
| Redis | 6379 | Embedding + search result caching |
## Web UI
The web UI at `http://localhost:6279` provides:
- Memory search and browsing with tag/source/type filters
- Dashboard with statistics (total memories, per source, per type)
- Monthly histogram and 30-day sparkline
- New memory creation form
- Tag management
## URL Ingestion
Save web pages and YouTube transcripts directly to memory using the bookmarklet.
1. Open `scripts/bookmarklet.html` in your browser
2. Drag the bookmarklet link to your bookmarks bar
3. Click it on any page to save the content to OpenBrain
**Web pages** are scraped via [Firecrawl](https://firecrawl.dev) (markdown extraction, JS rendering). Set `FIRECRAWL_API_KEY` in `.env` — without it, web ingestion will error.
**YouTube URLs** are handled locally via `yt-dlp` (install: `brew install yt-dlp`). Transcripts are extracted and stored with video metadata.
## Gradual Setup
You don't need all services running to get started:
1. **Minimum**: PostgreSQL + Embedding Service + MCP Server — gives you store and search
2. **Add enrichment**: Start the mlx-lm server — memories get auto-enriched with summaries and tags
3. **Add caching**: Start Redis — faster repeated searches and embedding lookups
4. **Add UI**: Start the web UI — browse and manage memories visually
5. **Add ingestion**: Set `FIRECRAWL_API_KEY` in `.env` and install the bookmarklet — save web content from your browser.
To skip enrichment entirely (e.g., while setting up), set `DISABLE_ENRICHMENT=true` in `.env`.
## Sources (recurring ingestion)
OpenBrain pulls content into memory on a schedule. Each **source** is a row in the `sources` table with a kind (`rss`, `mail`, or `webpage`), config, and an interval.
```bash
# Create an RSS source via the REST API:
echo '{"kind":"rss","name":"HN","config":{"feedUrl":"https://news.ycombinator.com/rss"},"intervalSeconds":3600}' \
| curl -X POST http://localhost:6277/api/sources -H 'content-type: application/json' --data @-
# Sync now:
curl -X POST http://localhost:6277/api/sources/<id>/sync
# Sync everything that's due:
curl -X POST http://localhost:6277/api/sources/poll-due
```
The Mac app (Phase 3+) drives `poll-due` from an hourly timer and exposes a UI for source CRUD. Until then, talk to the REST API directly. (The timer is just a heartbeat — each source's own `intervalSeconds` decides when it's actually due.)
### Mail sources via `gog`
To pull Gmail into memory, install [gogcli](https://github.com/steipete/gogcli) and authenticate:
```bash
brew install gogcli
gog auth add you@gmail.com
```
Then create a `mail` source:
```json
{
"kind": "mail",
"name": "Personal Gmail (last day)",
"config": {
"account": "you@gmail.com",
"query": "newer_than:1d -in:promotions -in:spam -in:trash",
"maxMessages": 25
},
"intervalSeconds": 900
}
```
**Important**: launchd-managed services have no TTY for `gog`'s keyring password prompt. Set `GOG_KEYRING_PASSWORD` in `.env` (gitignored) to your gog keyring password, then restart the MCP service. Without this, mail syncs will fail with `"no TTY available for keyring file backend password prompt"`.
## Recurring agents
OpenBrain ships with a small **starter pack** of prompt-driven agents that run on a schedule, query the memory store, call the local LLM, and write the result back as a new memory. All of this happens locally — no API keys.
```bash
# Run a shipped agent once, see the output:
bun run agents/run-agent.ts agents/prompts/newsletter-digest.md
# Or via the wrapper:
agents/run-agent.sh newsletter-digest.md
```
Shipped prompts live in `agents/prompts/`. Bring your own by dropping additional `.md` files into a directory of your choice (the [Mac app](apps/mac/) defaults to `~/Developer/claude-cron/prompts/`). See `agents/prompts/README.md` for the format.
## Remote Access via Tailscale
To access OpenBrain from other devices on your network:
```bash
# Expose MCP server over Tailscale HTTPS
tailscale serve --bg --https=6443 http://localhost:6277
```
Then update your bookmarklet URL to use `https://your-machine.tail-xxxxx.ts.net:6443` and set `AUTH_TOKEN` in `.env` to protect the endpoint.
## Development
```bash
bun run dev # MCP server with auto-reload
bun run ui # Web UI
bun run health # Check all service health
bun run db:generate # Generate Drizzle migration from schema changes
bun run db:migrate # Apply pending migrations
# Re-enrich memories missing summaries
bun run scripts/enrich-backlog.ts
```
## Managing Services
```bash
# Install as launchd daemons (auto-start on boot)
bash scripts/install-services.sh
# Uninstall all services
bash scripts/uninstall-services.sh
# Restart a single service
kill $(lsof -ti :6277) # KeepAlive restarts it automatically
# View logs
tail -f logs/mcp.log
tail -f logs/embed.log
tail -f logs/llm.log
```
## License
MIT
