A personal intelligence system that synthesizes your email, voice recordings, WhatsApp, and AI conversation history into actionable insight about your projects, relationships, and priorities.
Setup guides, agent configuration, and workflow playbooks for everyday users.
Relationships — Contact Intelligence Every contact profiled from your communications, tagged by relationship type, and ranked by recency.
Relationships — Communication Timeline Full history across Email, WhatsApp, and Limitless in one scrollable view per person.
Projects — Active Tracker AI-discovered projects with blockers, risks, next actions, and opportunities surfaced automatically.
Search — Semantic Search Natural language search across all indexed emails, messages, and lifelogs.
Agents — Control Panel Start, stop, and configure all background agents from one place. View live logs, set schedules, and manage API keys.
secondbrain is designed so you can get the whole application running with one command:
npm run uiThat starts:
- the Next.js UI on
http://localhost:4000 - the Express API / agent-control server on
http://localhost:4001
- Node.js 18+
- PostgreSQL 14+
- a database you can reach via
DATABASE_URL
git clone <repo>
cd secondbrain
npm installCreate .env.local in the repo root.
Minimum required:
DATABASE_URL=postgresql://user:pass@localhost:5432/secondbrainOptional values can be added now or later through the UI:
# Gmail (optional)
GMAIL_EMAIL_1=you@gmail.com
GMAIL_APP_PASSWORD_1=xxxx xxxx xxxx xxxx
# Limitless (optional)
LIMITLESS_API_KEY=...
# AI / search (optional)
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GEMINI_API_KEY=...
# UI/API port override (optional)
UI_PORT=4001npm run uiThen open:
http://localhost:4000
The UI, API, and WhatsApp admin listener bind to loopback by default. Do not expose ports 3000, 4000, or 4001 directly on the LAN or tailnet. Publish only the main UI through Tailscale Serve; Next.js forwards /api to the loopback API internally:
tailscale serve --bg --https=443 http://127.0.0.1:4000
tailscale serve statusIf another local HTTPS service already owns port 443, use Tailscale's supported 8443 port and include it in the printed URL/origin:
tailscale serve --bg --https=8443 http://127.0.0.1:4000Copy the printed HTTPS origin into .env.local, then restart npm run ui:
SECOND_BRAIN_ALLOWED_ORIGINS=https://your-mac.your-tailnet.ts.netFor the 8443 form, use https://your-mac.your-tailnet.ts.net:8443.
When running npm run ui:dev, also set SECOND_BRAIN_ALLOWED_DEV_ORIGINS to the hostname without https://. Use Tailscale ACLs to decide which tailnet users/devices may reach the machine. To remove the proxy, run tailscale serve reset.
The deploy/reload API is disabled unless SECOND_BRAIN_DEPLOY_TOKEN is configured. Generate a strong value with openssl rand -hex 32 and send it only in the x-deploy-token header.
On startup, the server automatically and idempotently:
- initializes all agent schemas
- initializes shared system tables
- attempts to initialize the optional search / pgvector schema
- seeds sensible default config values into the database when missing
- restores core agents whose durable desired state is
running
You do not need to run manual psql schema commands for normal setup.
If the PostgreSQL vector extension is not installed, semantic search is skipped and the rest of the app still works.
Once the app is open, go to /agents and do this:
- Add at least one
LLM Provider. - Configure
Emailif you want Gmail sync. - Configure
Limitlessif you use Limitless.ai. - Add
Embeddingsif you want semantic search. - Stop any core agent you do not want to run; that stopped state is remembered across UI restarts.
Recommended starting order:
1. Email / Limitless / WhatsApp
2. Relationships + Projects
3. Research (optional)
The UI lets you start and stop background agents from one place, so after npm run ui you usually do not need to manage separate terminal windows for day-to-day usage.
If you just want a useful system quickly:
1. Set DATABASE_URL
2. Run npm run ui
3. Open /agents
4. Add one LLM provider
5. Configure Gmail
6. Start Email, Relationships, and Projects
7. Check Dashboard, Relationships, and Projects
secondbrain turns fragmented communication into working intelligence.
It helps you answer questions like:
- Who matters right now?
- Which projects are drifting?
- What follow-up did I forget?
- Which groups are signaling opportunity or risk?
- What do I need to know before this meeting?
Instead of manually stitching together inboxes, chats, transcripts, and notes, secondbrain gives you one operating layer across all of them.
| URL | What it does |
|---|---|
/ |
Dashboard for open insights, recent activity, and daily triage |
/relationships |
Contact intelligence, communication history, research, and opportunities |
/groups |
WhatsApp group intelligence, key topics, roles, and opportunities |
/projects |
Project tracking, recent communications, blockers, risks, and next actions |
/agents |
Agent control, configuration, logs, LLM providers, and embeddings |
/search |
Semantic search across indexed content |
- Background agents ingest and analyze your data over time.
- Manual edits are sticky: if you correct a contact or project in the UI, later agent runs respect those overrides.
- Search is optional and depends on embeddings plus PostgreSQL
vector.
Syncs Gmail inboxes into Postgres using IMAP.
- polls every 15 minutes
- supports multiple Gmail accounts
- powers relationship and project discovery
Fetches Limitless.ai lifelogs as immutable source evidence.
- fetches every 5 minutes
- uses idempotent provider IDs and does not execute external actions
- feeds meeting and spoken-context evidence to the relationship and intelligence pipelines
Lives in this repo and is no longer external.
- bridges WhatsApp Web into Postgres
- stores messages, chat metadata, and media references
- powers the Groups page and strengthens Relationships / Projects
- performs a historical sync after connection
You can also run it directly with:
npm run whatsappBuilds contact profiles and relationship insights from your communications.
- links messages and people
- generates relationship summaries and follow-up insights
- analyzes WhatsApp groups
Discovers and tracks projects across email, WhatsApp, and lifelogs.
- groups communications into project threads
- generates blockers, risks, next actions, and opportunities
- updates projects incrementally over time
Enriches contact profiles using outside research providers.
- optional
- useful for important external stakeholders
- can be triggered per contact from the Relationships page
Import ChatGPT and Gemini conversation exports into the ai schema.
- useful for long-term memory and future workflows
- configured from the Agents page
Gmail Limitless WhatsApp AI Exports
| | | |
v v v v
+----------------------------------------------------------+
| Ingestion Agents |
| Email Limitless WhatsApp OpenAI/Gemini Importers |
+----------------------------------------------------------+
|
v
+----------------------------------------------------------+
| Postgres |
| email.* limitless.* relationships.* projects.* ai.* |
| system.* search.* public.messages telemetry.* |
+----------------------------------------------------------+
|
v
+----------------------------------------------------------+
| Analysis / Enrichment |
| Relationships Agent Projects Agent Research |
+----------------------------------------------------------+
|
v
+----------------------------------------------------------+
| UI |
| Dashboard | Relationships | Groups | Projects | Search |
| Agents (port 4000) |
+----------------------------------------------------------+
|
v
+----------------------------------------------------------+
| Observability |
| Telemetry SDK → Buffer → Collector → telemetry.* |
| Sampler (powermetrics, process stats, ollama ps) |
| Observe UI (/observe) + API (/api/observe/* via 4001) |
+----------------------------------------------------------+
All packages share a single Postgres database via packages/db.
The UI server manages:
- schema initialization
- config seeding
- agent start / stop / logs
- system configuration APIs
- semantic search indexing (batched, 200 items/source/run)
packages/
├── db/ Shared Postgres connection pool
├── agents/
│ ├── email/ Gmail IMAP sync -> email.*
│ ├── limitless/ Limitless raw evidence ingestion
│ ├── projects/ Project discovery and insights
│ ├── relationships/ Contact and group intelligence
│ ├── research/ External contact enrichment
│ ├── ai/ OpenAI / Gemini importers
│ └── whatsapp/ WhatsApp Web connector
├── telemetry/ Instrumentation SDK (startRun, startRequest, progress, quality)
├── telemetry-buffer/ In-memory + disk-spill queue (no silent drops)
├── collector/ Drains spill files to DB; computes ETAs and work efficiency
├── sampler/ macOS system sampler (powermetrics, process stats, ollama ps)
├── observe/ Observability routes + optional standalone server
└── ui/
├── app/ Next.js frontend (port 4000)
├── services/ Search / embeddings background services
├── sql/ Search schema
└── server.js Express API + agent process manager
npm run uiStarts the UI plus API / agent-control server, including /api/observe/*.
npm run ui:devRuns the same stack with Next.js dev mode, including /api/observe/*.
npm run email
npm run limitless
npm run relationships
npm run projects
npm run research
npm run whatsapp
npm run ai:openai
npm run ai:geminiIn normal usage, you can start and stop agents from /agents instead of using these commands directly.
npm run collector # replays spilled telemetry events; computes ETAs
sudo npm run sampler # system sampler — requires sudo for powermetrics (macOS)
npm run observe # optional standalone legacy observe API/dashboard on http://localhost:4002The primary observe dashboard is /observe in the main UI. Its API is mounted inside the main Express server at /api/observe/* (port 4001), so normal npm run ui / npm run ui:dev startup is enough. The observe dashboard shows live agent runs, LLM request traces, per-model token stats, quality scores, system health (CPU/GPU/power/thermals), and embedding indexer progress. All agents write telemetry through an in-memory buffer that drains to telemetry.* in Postgres every 5 seconds.
When you edit a project or contact in the UI, secondbrain stores that as a manual override and future agent runs try not to overwrite those fields.
Semantic search depends on the vector PostgreSQL extension (pgvector) and an embedding provider. Two providers are supported:
- Gemini (default) — uses
gemini-embedding-2-previewvia API; no local GPU required - Ollama — any locally-running embedding model (e.g.
bge-m3,nomic-embed-text); uses local GPU
Configure the provider and model from the Agents → Embeddings panel. The panel shows a per-source progress bar (email, WhatsApp, lifelogs, contacts, projects) with queue depth and estimated items remaining. The indexer runs every 10 minutes and processes up to 200 items per source per run to avoid saturating the GPU during backfill.
If neither provider is configured, semantic search falls back to full-text only and the rest of the system is unaffected.
The WhatsApp connector is included in this repo. It is not an external dependency anymore.
Historical sync skips broadcast lists, the status feed, and WhatsApp Channels — these chat types do not support message history retrieval and are silently excluded from sync counts.
MIT