SecondBrain

A persistent MCP memory layer for AI agents. Store knowledge across sessions, retrieve it semantically, and connect any MCP-compatible agent — claude.ai, OpenClaw, or your own.

What is SecondBrain?

AI agents are stateless by default — they forget everything when a session ends. SecondBrain solves this by providing a persistent memory server that any MCP-compatible agent can use to store and retrieve knowledge.

When an agent calls remember("I just learned that..."), SecondBrain:

1. Splits the input into independent topics
2. Searches existing knowledge for related pages
3. Uses an LLM planning agent (Wikipedia-style) to decide what to update or create
4. Writes free-form Markdown wiki pages to a Git-synced vault
5. Updates a knowledge graph (Neo4j) and semantic index (Qdrant)

When an agent calls recall("what do I know about X?"), SecondBrain runs HybridRAG — combining vector search, graph traversal, and LLM synthesis to return a contextual answer from the wiki.

Features

• MCP-native — plug into claude.ai, OpenClaw, or any MCP client
• Wikipedia-agent model — planning + update agents write and revise wiki pages intelligently
• HybridRAG — vector search (Qdrant) + graph traversal (Neo4j) + Markdown vault
• Markdown vault — Obsidian-compatible, optionally Git-synced to any GitHub/GitLab/Gitea repo
• Hourly review agent — automatically cross-links related pages and resolves contradictions
• Web UI — knowledge graph visualizer + remember/recall interface
• Self-hosted — runs entirely on your own infrastructure

Architecture

Agent (claude.ai / OpenClaw / custom)
  │  MCP protocol (port 3000)
  ▼
MCP Server ──remember──▶ Celery Worker ──▶ LLM planning agent
                                      ──▶ Wiki pages (Markdown vault)
                                      ──▶ Knowledge graph (Neo4j)
                                      ──▶ Semantic index (Qdrant)

MCP Server ──recall───▶ HybridRAG ──▶ Qdrant (vector search)
                                  ──▶ Neo4j (graph traversal)
                                  ──▶ Vault (Markdown load)
                                  ──▶ LLM synthesis ──▶ Answer

Storage:

Quick Start

Prerequisites

• Docker + Docker Compose
• An OpenRouter API key (supports Claude, GPT-4, etc.)
• Optional: a private GitHub repo for vault sync

1 — Clone and configure

git clone https://github.com/JonasKruegerCode/SecondBrain.git
cd SecondBrain
cp .env.example .env

Edit .env — at minimum set your OPENROUTER_API_KEY and a MCP_API_KEY (any secret string).

2 — Start

docker compose up -d

That's it. Services:

• Web UI: http://localhost (via frontend container)
• REST API: http://localhost:8000
• MCP endpoint: http://localhost:3000/mcp

3 — Connect your agent

claude.ai

Go to Settings → Integrations → Add MCP server:

URL:     https://mcp.your-domain.com/mcp
API Key: your-secret-key   (set as Bearer token / MCP_API_KEY)

For local testing without a public URL, use ngrok or Cloudflare Tunnel to expose port 3000.

OpenClaw / custom MCP client

{
  "mcpServers": {
    "secondbrain": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

MCP Tools

Configuration

All configuration is via environment variables. Copy .env.example to .env and adjust.

Localhost vs. Docker: Use localhost:* for local dev. On a server with Docker Compose, use service names (redis, neo4j, qdrant) — they resolve inside the Docker network.

Switching providers: Set LLM_PROVIDER=gcp, GCP_API_KEY=..., and update DEFAULT_MODEL / EMBEDDING_MODEL to model names your provider understands (e.g. gemini-3.5-flash / -gemini-embedding-2 for Google AI).

Deployment (Self-Hosted Server)

You can deploy using the pre-built images — no fork or build step required. Just copy two files to your server.

Server setup

# Copy only these two files to the server
scp docker-compose.yml .env user@your-server:/opt/secondbrain/

# On the server
cd /opt/secondbrain
docker compose pull
docker compose up -d

Pre-built images are published automatically from this repository:

• ghcr.io/jonaskruegercode/secondbrain-frontend:latest
• ghcr.io/jonaskruegercode/secondbrain-backend:latest

Build locally instead

If you prefer to build from source (e.g. after making changes):

docker compose up -d --build

The docker-compose.yml includes build: directives pointing to ./frontend and ./backend, so this works out of the box.

Updates

docker compose pull && docker compose up -d

Nginx Proxy Manager (recommended reverse proxy)

Nginx Proxy Manager uses a shared Docker network to reach containers. Create a docker-compose.override.yml next to your docker-compose.yml on the server — Docker Compose picks it up automatically on every up:

services:
  frontend:
    networks:
      - proxy-network
  backend:
    networks:
      - proxy-network

networks:
  proxy-network:
    external: true

Create the network once if it doesn't exist yet:

docker network create proxy-network

Local Development

See documentation/local_developement.md for the full local dev setup with hot reload, test instructions, and quality checks.

Contributing

Contributions are welcome. Here's what would make this project more production-ready as open source:

• Additional LLM providers — OpenAI/Anthropic direct keys, Azure OpenAI, Ollama (local)
• Documentation — usage examples, cookbook for common agent patterns
• Git sync: any host — currently only GitHub PAT auth is tested. Supporting GitLab, Gitea, and self-hosted instances would make the feature genuinely host-agnostic
• Tests — expand integration test coverage (backend/tests/)
• CI — add GitHub Actions workflow for pytest and ruff/mypy on PRs
• Vault templates — starter vault structures for different use cases

To contribute:

1. Fork the repo
2. Create a feature branch
3. Run bash check.sh to verify lint, types, and tests pass
4. Open a pull request

Please open an issue before starting work on a significant change.

License

MIT — see LICENSE.