second-brain

Docker container for brain management: zk, semantic search, and Model Context Protocol (MCP) server for Claude Code and Claude Desktop.

The second-brain provides a set of tools and skills to manage a brain of markdown notes using semantic search, structured metadata, and AI capabilities.

Quick start

No repository clone is required to run the second-brain — the Docker image includes everything needed.

# 1. Create a directory for your brain (or use an existing notes folder)
mkdir -p ~/Documents/brain

# 2. Run the setup wizard (choose model provider, create folders, generate .env)
docker run --rm -it \
  -v ~/Documents/brain:/brain \
  kitchencoder/second-brain:latest \
  brain-init

# 3. Start the container
docker run -d --name second-brain --restart unless-stopped \
  -v ~/Documents/brain:/brain \
  -v second-brain-claude:/home/coder/.claude \
  -v second-brain-zsh:/home/coder/.zsh-data \
  -p 7779:7779 -p 7780:7780 \
  kitchencoder/second-brain:latest

The brain-init wizard will guide you through picking your model provider and embedding model (presets for Docker Model Runner, Ollama, LM Studio, and Anthropic API).

Tiers: the quickstart above is the core image (MCP + brain tools only). Want a browser IDE on top? See the code-server recipe. Want vectors in Postgres instead of the embedded SQLite index? See the full-stack compose recipe.

Documentation Index

For Users

• User Guide: Installation, Host configuration, and how to use the brain.
• Brain Guide: Philosophy and structure of your brain (folders, frontmatter, tags).
• MCP Server: How to connect your brain to AI clients (Claude Code, Claude Desktop, Open WebUI, etc).
• Brain Skills: Detailed list of all AI skills available for managing your brain.
• Authentication: Gate the REST API and MCP HTTP transport behind static tokens or OAuth 2.1 (profile.auth.mode, default off).
• Recipes: Browser IDE (code-server) and full-stack (Postgres/pgvector) layers on top of the core image.

For Developers

• Development Guide: How to build the image, run in development mode, and create new skills or tools.
• CHANGELOG: What has landed in each release.

---

At a glance

• Semantic Search: Find notes by meaning, not just keywords.
• MCP Server: Expose your brain tools to any Model Context Protocol client.
• Claude Code Integration: Custom skills for note capture, triage, and management.
• Profiles: One engine runs many brains — the default ace profile is cloned on first init; flavours like obsidian and custom forks (folders, skills, templates, queryable fields) are one env var away.
• Multi-platform: Runs anywhere Docker does; works with Obsidian and VS Code on the host.
• Privacy First: Designed to run with local models via Docker Model Runner or Ollama.

Roadmap

The profile refactor shipped in 2.0.0: the engine (this Docker image: search, MCP, editing, auth) is fully separated from the profile (a brain's folders, templates, skills, identity, and queryable fields) — one engine, many brains, no fork.

Landed:

• Profile-driven engine — a brain self-describes via <brain>/.brain/
• Profiles live in their own public repos (ace, obsidian); the default is cloned from brain-profile-ace on first init, with profile.toml schema versioning
• Profile-driven queries — metadata filters adapt to each profile's fields
• Auth — static per-principal bearer tokens and an OAuth 2.1 authorization server behind profile.auth.mode (default none). See the Authentication guide.
• Content visibility / RBAC — role-based read/write layers, oracle-safe. See docs/rbac.md.
• Full-stack tier — Postgres/pgvector index store, admin plane + agent credentials, per-principal retrieval log
• Per-brain host identity (brain-init --brain-name) and a configurable MCP endpoint for tunnel/reverse-proxy deployments

Planned:

• Admin UI for the RBAC tier
• Community profiles

Custom profiles are covered in the User Guide; the running record is in the CHANGELOG.