new_header

SurfSense

While tools like NotebookLM and Perplexity are impressive and highly effective for conducting research on any topic/query, SurfSense elevates this capability by integrating with your personal knowledge base. It is a highly customizable AI research agent, connected to external sources such as Search Engines (SearxNG, Tavily, LinkUp), Slack, Linear, Jira, ClickUp, Confluence, BookStack, Gmail, Notion, YouTube, GitHub, Discord, Airtable, Google Calendar, Luma, Elasticsearch and more to come.

Video

https://github.com/user-attachments/assets/42a29ea1-d4d8-4213-9c69-972b5b806d58

Podcast Sample

https://github.com/user-attachments/assets/a0a16566-6967-4374-ac51-9b3e07fbecd7

Key Features

💡 Idea:

Have your own highly customizable private NotebookLM and Perplexity integrated with external sources.
📁 Multiple File Format Uploading Support
Save content from your own personal files (Documents, images, videos and supports 50+ file extensions) to your own personal knowledge base .
🔍 Powerful Search
Quickly research or find anything in your saved content .
💬 Chat with your Saved Content
Interact in Natural Language and get cited answers.
📄 Cited Answers
Get Cited answers just like Perplexity.
🔔 Privacy & Local LLM Support
Works Flawlessly with Ollama local LLMs.
🏠 Self Hostable
Open source and easy to deploy locally.
👥 Team Collaboration with RBAC
Role-Based Access Control for Search Spaces
Invite team members with customizable roles (Owner, Admin, Editor, Viewer)
Granular permissions for documents, chats, connectors, and settings
Share knowledge bases securely within your organization
🎙️ Podcasts
Blazingly fast podcast generation agent. (Creates a 3-minute podcast in under 20 seconds.)
Convert your chat conversations into engaging audio content
Support for local TTS providers (Kokoro TTS)
Support for multiple TTS providers (OpenAI, Azure, Google Vertex AI)

🤖 Deep Agent Architecture

Built-in Agent Tools

Tool	Description
search_knowledge_base	Search your personal knowledge base with semantic + full-text hybrid search, date filtering, and connector-specific queries
generate_podcast	Generate audio podcasts from chat conversations or knowledge base content
link_preview	Fetch rich Open Graph metadata for URLs to display preview cards
display_image	Display images in chat with metadata and source attribution
scrape_webpage	Extract full content from webpages for analysis and summarization (supports Firecrawl or local Chromium/Trafilatura)

Extensible Tools Registry

Contributors can easily add new tools via the registry pattern:

Create a tool factory function in surfsense_backend/app/agents/new_chat/tools/
Register it in the BUILTIN_TOOLS list in registry.py

Configurable System Prompts

Custom system instructions via LLM configuration
Toggle citations on/off per configuration
Supports 100+ LLMs via LiteLLM integration

📊 Advanced RAG Techniques

Supports 100+ LLM’s
Supports 6000+ Embedding Models.
Supports all major Rerankers (Pinecone, Cohere, Flashrank etc)
Uses Hierarchical Indices (2 tiered RAG setup).
Utilizes Hybrid Search (Semantic + Full Text Search combined with Reciprocal Rank Fusion).

ℹ️ External Sources

Search Engines (Tavily, LinkUp)
SearxNG (self-hosted instances)
Slack
Linear
Jira
ClickUp
Confluence
BookStack
Notion
Gmail
Youtube Videos
GitHub
Discord
Airtable
Google Calendar
Luma
Elasticsearch
and more to come…..

📄 Supported File Extensions

ETL Service	Formats	Notes
LlamaCloud	50+ formats	Documents, presentations, spreadsheets, images
Unstructured	34+ formats	Core formats + email support
Docling	Core formats	Local processing, no API key required

Audio/Video (via STT Service): .mp3, .wav, .mp4, .webm, etc.

🔖 Cross Browser Extension

The SurfSense extension can be used to save any webpage you like.
Its main usecase is to save any webpages protected beyond authentication.

FEATURE REQUESTS AND FUTURE

SurfSense is actively being developed. While it’s not yet production-ready, you can help us speed up the process.

Join the SurfSense Discord and help shape the future of SurfSense!

🚀 Roadmap

Stay up to date with our development progress and upcoming features!
Check out our public roadmap and contribute your ideas or feedback:

📋 Roadmap Discussion: SurfSense 2025-2026 Roadmap: Deep Agents, Real-Time Collaboration & MCP Servers

📊 Kanban Board: SurfSense Project Board

How to get started?

Quick Start with Docker 🐳

[!TIP] For production deployments, use the full Docker Compose setup which offers more control and scalability.

Linux/macOS:

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest

Windows (PowerShell):

docker run -d -p 3000:3000 -p 8000:8000 `
  -v surfsense-data:/data `
  --name surfsense `
  --restart unless-stopped `
  ghcr.io/modsetter/surfsense:latest

With Custom Configuration (e.g., OpenAI Embeddings):

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  -e EMBEDDING_MODEL=openai://text-embedding-ada-002 \
  -e OPENAI_API_KEY=your_openai_api_key \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest

After starting, access SurfSense at:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Docs: http://localhost:8000/docs

Useful Commands:

docker logs -f surfsense      # View logs
docker stop surfsense         # Stop
docker start surfsense        # Start
docker rm surfsense           # Remove (data preserved in volume)

Installation Options

SurfSense provides multiple options to get started:

SurfSense Cloud - The easiest way to try SurfSense without any setup.
- No installation required
- Instant access to all features
- Perfect for getting started quickly
Quick Start Docker (Above) - Single command to get SurfSense running locally.
- All-in-one image with PostgreSQL, Redis, and all services bundled
- Perfect for evaluation, development, and small deployments
- Data persisted via Docker volume
Docker Compose (Production) - Full stack deployment with separate services.
- Includes pgAdmin for database management through a web UI
- Supports environment variable customization via .env file
- Flexible deployment options (full stack or core services only)
- Better for production with separate scaling of services
Manual Installation - For users who prefer more control over their setup or need to customize their deployment.

Docker and manual installation guides include detailed OS-specific instructions for Windows, macOS, and Linux.

Before self-hosting installation, make sure to complete the prerequisite setup steps including:

Auth setup (optional - defaults to LOCAL auth)
File Processing ETL Service (optional - defaults to Docling):
- Docling (default, local processing, no API key required, supports PDF, Office docs, images, HTML, CSV)
- Unstructured.io API key (supports 34+ formats)
- LlamaIndex API key (enhanced parsing, supports 50+ formats)
Other API keys as needed for your use case

Tech Stack

BackEnd

FastAPI: Modern, fast web framework for building APIs with Python
PostgreSQL with pgvector: Database with vector search capabilities for similarity searches
SQLAlchemy: SQL toolkit and ORM (Object-Relational Mapping) for database interactions
Alembic: A database migrations tool for SQLAlchemy.
FastAPI Users: Authentication and user management with JWT and OAuth support
Deep Agents: Custom agent framework built on LangGraph for reasoning and acting AI agents with configurable tools
LangGraph: Framework for developing stateful AI agents with conversation persistence
LangChain: Framework for developing AI-powered applications.
LiteLLM: Universal LLM integration supporting 100+ models (OpenAI, Anthropic, Ollama, etc.)
Rerankers: Advanced result ranking for improved search relevance
Hybrid Search: Combines vector similarity and full-text search for optimal results using Reciprocal Rank Fusion (RRF)
Vector Embeddings: Document and text embeddings for semantic search
pgvector: PostgreSQL extension for efficient vector similarity operations
Redis: In-memory data structure store used as message broker and result backend for Celery
Celery: Distributed task queue for handling asynchronous background jobs (document processing, podcast generation, etc.)
Flower: Real-time monitoring and administration tool for Celery task queues
Chonkie: Advanced document chunking and embedding library
Uses AutoEmbeddings for flexible embedding model selection
LateChunker for optimized document chunking based on embedding model’s max sequence length

FrontEnd

Next.js: React framework featuring App Router, server components, automatic code-splitting, and optimized rendering.
React: JavaScript library for building user interfaces.
TypeScript: Static type-checking for JavaScript, enhancing code quality and developer experience.
Vercel AI SDK Kit UI Stream Protocol: To create scalable chat UI.
Tailwind CSS: Utility-first CSS framework for building custom UI designs.
Shadcn: Headless components library.
Motion (Framer Motion): Animation library for React.

DevOps

Docker: Container platform for consistent deployment across environments
Docker Compose: Tool for defining and running multi-container Docker applications
pgAdmin: Web-based PostgreSQL administration tool included in Docker setup

Extension

Manifest v3 on Plasmo

Contribute

Contributions are very welcome! A contribution can be as small as a ⭐ or even finding and creating issues. Fine-tuning the Backend is always desired.

Adding New Agent Tools

Want to add a new tool to the SurfSense agent? It’s easy:

Create your tool file in surfsense_backend/app/agents/new_chat/tools/my_tool.py
Register it in registry.py:

ToolDefinition(
    name="my_tool",
    description="What my tool does",
    factory=lambda deps: create_my_tool(
        search_space_id=deps["search_space_id"],
        db_session=deps["db_session"],
    ),
    requires=["search_space_id", "db_session"],
),

For detailed contribution guidelines, please see our CONTRIBUTING.md file.

Star History

Catalyst Project