Intelligent knowledge management with multi-provider AI chat, smart notes, AI agents, and advanced RAG.
git clone https://github.com/ananyateklu/second-brain.git && cd second-brain
cp .env.example .env # Add your AI provider API keys
docker-compose up -d # Access at http://localhost:3000 Dashboard |
 AI Chat |
 AI Settings |
 RAG Indexing |
| Feature | Description |
|---|---|
| Multi-Provider Chat | OpenAI, Claude, Gemini, Grok, Ollama, Cohere with streaming responses |
| AI Agents | Tool execution with real-time reasoning display and thinking steps |
| Image Generation | DALL-E, Gemini Imagen, Grok Aurora with size/quality options |
| Vision Models | Attach images to messages (GPT-4o, Claude 3.5, Gemini) |
| Code Execution | Python sandbox via Gemini with output display |
| Web Search | Live search (Grok), Google grounding (Gemini) |
| Extended Thinking | Claude reasoning chains, Grok think mode |
| Voice Agent | Real-time voice interface with transcription and tool execution |
| Feature | Description |
|---|---|
| Smart Notes | Rich text editor, tags, folders, archive |
| Version History | Point-in-time restore via PostgreSQL 18 temporal tables |
| AI Summaries | Auto-generated note summaries for quick scanning |
| Image Attachments | Multimodal notes with AI-extracted descriptions |
| Bulk Operations | Multi-select delete, archive, tag |
| iOS Sync | Bidirectional sync via iOS Shortcuts |
| Feature | Description |
|---|---|
| Focus Dashboard | Current focus with live timer, today's plan, backlog management |
| AI Suggestions | Generate task suggestions from notes using RAG pipeline |
| Time Tracking | Accumulated time tracking across sessions with live display |
| Priority System | P1 (High), P2 (Medium), P3 (Low) with visual indicators |
| Progress Summaries | AI-generated daily/weekly productivity insights |
| Quick Capture | Modal for fast task creation (Cmd+Enter shortcuts) |
| Note Linking | Link focus items to existing notes for context |
| Stage | Features |
|---|---|
| Query Expansion | HyDE (hypothetical documents), multi-query generation |
| Hybrid Search | Vector (pgvector) + BM25 full-text with RRF fusion |
| Reranking | LLM-based relevance scoring (Cohere, OpenAI) |
| Analytics | Query logs, user feedback, topic clustering |
| Vector Stores | PostgreSQL pgvector (default), Pinecone (cloud) |
| Feature | Description |
|---|---|
| Git Integration | Branch management, commits, diff viewer |
| GitHub Integration | PRs, issues, workflows, check runs |
| Analytics Dashboard | Token usage, provider stats, session tracking |
| Desktop App | Native macOS via Tauri 2.0 with embedded database |
| Layer | Technology |
|---|---|
| Backend | ASP.NET Core 10, PostgreSQL 18 + pgvector, Entity Framework Core, MediatR (CQRS) |
| Frontend | React 19, TypeScript 5.9, Vite 7, Tailwind CSS v4, Zustand, TanStack Query v5 |
| Desktop | Tauri 2.0 (Rust), embedded PostgreSQL on port 5433 |
| AI Providers | OpenAI, Anthropic Claude, Google Gemini, X.AI Grok, Ollama, Cohere |
| Vector Search | PostgreSQL pgvector (HNSW), Pinecone |
| Image Generation | DALL-E, Gemini Imagen, Grok Aurora |
| Resilience | Polly circuit breaker, exponential backoff |
second-brain/
├── backend/src/
│ ├── SecondBrain.API/ # Controllers, middleware
│ ├── SecondBrain.Application/ # Services, CQRS, DTOs
│ ├── SecondBrain.Core/ # Entities, interfaces
│ └── SecondBrain.Infrastructure/ # EF Core, repositories
├── frontend/src/
│ ├── features/ # 12 domain modules
│ ├── services/ # API service layer
│ ├── store/ # Zustand (14 slices)
│ └── components/ # Shared UI
├── frontend/src-tauri/ # Desktop app (Rust)
├── database/ # 62 SQL migration scripts
└── docs/ # ADRs, guides
- Docker & Docker Compose (recommended)
- .NET 10 SDK (local development)
- Node.js 20+ and pnpm (local development)
- At least one AI provider API key (OpenAI, Anthropic, Gemini, X.AI, or Ollama)
# 1. Clone and configure
git clone https://github.com/ananyateklu/second-brain.git
cd second-brain
cp .env.example .env
# 2. Edit .env with your settings
# Required: At least one AI provider API key
# Required: JWT_SECRET_KEY (32+ characters)
# 3. Start services
docker-compose up -d
# Access: http://localhost:3000
# API: http://localhost:3000/api# Terminal 1: Database
docker-compose up -d postgres
# Terminal 2: Backend
cd backend/src/SecondBrain.API
cp .env.example .env # Configure API keys
dotnet watch run # http://localhost:5001
# Terminal 3: Frontend
cd frontend
cp .env.example .env # Set VITE_API_URL=http://localhost:5001/api
pnpm install && pnpm dev # http://localhost:3000# Prerequisites
brew install postgresql@18 pgvector
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build and run
./backend/publish-mac.sh
cd frontend && pnpm tauri devData stored in ~/Library/Application Support/com.secondbrain.desktop/
# Database
POSTGRES_PASSWORD=your-secure-password
# JWT (required, 32+ characters)
JWT_SECRET_KEY=YourSuperSecretKeyAtLeast32Characters
# AI Providers (at least one required)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
XAI_API_KEY=...
# Vector Store (default: PostgreSQL)
VECTOR_STORE_PROVIDER=PostgreSQL
# Optional: Pinecone for cloud vector search
PINECONE_API_KEY=...Configure in appsettings.json or environment variables:
| Provider | Default Model | Key Features |
|---|---|---|
| OpenAI | gpt-4o-mini | Function calling, vision, structured output |
| Anthropic | claude-3-5-haiku-latest | Extended thinking, prompt caching |
| Gemini | gemini-2.0-flash | Code execution, grounding, context caching |
| X.AI | grok-3-mini | Live search, deep search, think mode |
| Ollama | qwen3:4b | Local models, no API key needed |
| Cohere | command-r-plus | Native reranking for RAG |
See backend/src/SecondBrain.API/appsettings.json for full configuration options.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ React │────▶│ nginx │────▶│ ASP.NET │
│ Frontend │ │ :3000 │ │ Core │
└─────────────┘ └─────────────┘ └──────┬──────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ PostgreSQL │ │ AI Providers│ │ Pinecone │
│ + pgvector │ │ (6 total) │ │ (optional) │
└─────────────┘ └─────────────┘ └─────────────┘
┌────────────────────────────────────────────────────────┐
│ Second Brain.app │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Tauri Shell (Rust) │ │
│ └──────────────────────────────────────────────────┘ │
│ │ IPC │
│ ┌──────────────────────────────────────────────────┐ │
│ │ React Frontend (WebView) │ │
│ └──────────────────────────────────────────────────┘ │
│ │ localhost:5001 │
│ ┌──────────────────────────────────────────────────┐ │
│ │ .NET Backend (Sidecar) │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ PostgreSQL (port 5433) + pgvector │ │
│ └──────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────┘
Full API documentation available at /swagger when running the backend.
| Group | Base Path | Description |
|---|---|---|
| Auth | /api/auth |
Login, register, API keys |
| Notes | /api/notes |
CRUD, versions, summaries, images |
| Chat | /api/chat |
Conversations, streaming (SSE), image generation |
| Agents | /api/agent |
Agent streaming with tool execution |
| Focus | /api/focus |
Tasks, AI suggestions, progress summaries |
| RAG | /api/rag/analytics |
Query logs, feedback, topic clustering |
| Indexing | /api/indexing |
Vector indexing jobs and stats |
| Git | /api/git |
Repository operations, branches |
| GitHub | /api/github |
PRs, issues, workflows |
| Issue | Solution |
|---|---|
| Database connection fails | Verify PostgreSQL is running: docker-compose ps |
| AI provider errors | Check API key is set and provider is enabled in settings |
| Vector search not working | Run indexing: POST /api/indexing/start |
| JWT authentication fails | Ensure JWT_SECRET_KEY is 32+ characters |
| CORS errors | Add frontend URL to CORS_ALLOWED_ORIGINS |
| Desktop app won't start | Check PostgreSQL 18 is installed: brew info postgresql@18 |
| Service | Port |
|---|---|
| Frontend | 3000 |
| Backend (local) | 5001 |
| PostgreSQL (Docker) | 5432 |
| PostgreSQL (Desktop) | 5433 |
| Ollama | 11434 |
| Document | Description |
|---|---|
| CLAUDE.md | Developer documentation and patterns |
| RAG Tuning Guide | Optimize RAG performance |
| iOS Sync Guide | Set up iPhone/iPad sync |
| Database README | Schema documentation |
| ADRs | Architecture decision records |
- ADR 001 - Zustand for state management
- ADR 006 - CQRS with MediatR
- ADR 007 - Tauri desktop app
- ADR 014 - Agent streaming strategies
# Backend
cd backend && dotnet test
# Frontend
cd frontend && pnpm test# EF Core migration
cd backend/src/SecondBrain.API
dotnet ef migrations add MigrationName
# Check migration status
./database/migrate.sh statusThis project is licensed under the MIT License - see the LICENSE file for details.