Kioku

Connect your AI coding assistants directly to your Obsidian vault. A high-performance Model Context Protocol (MCP) server that lets agents read, write, search, and organize your knowledge base.

Get Started View on GitHub

Core Capabilities

🔎

Hybrid Search

Blends keyword search with local vector embeddings (via Ollama & nomic-embed-text) using Reciprocal Rank Fusion (RRF) for highly relevant context discovery.

📝

Read & Write Notes

Natively edit notes, inject content into notes, parse and update frontmatter, and maintain structural YAML tags directly from the agent's context.

✅

Task Management

Read, filter, complete, or reopen checkboxes across your entire vault. Supports filtering by due dates, tags, and overdue status.

🕸️

Zettelkasten & Graphs

Create MOCs (Maps of Content), link related notes, calculate graph islands, analyze orphan notes, and construct visual concept maps of your thinking.

🎨

Obsidian UI Bridge

Connects over WebSockets to open notes, trigger commands, insert snippets, or toggle reading mode directly inside the active Obsidian editor window.

🚀

On-Demand Daemon

Starts in milliseconds and shuts down when your agent session completes, keeping VRAM and CPU footprint near zero during ordinary usage.

System Architecture

Kioku decouples indexing and file modifications (C# Server) from editor interactions (TypeScript Plugin), communicating over WebSocket and standard MCP transports.

Quick Setup

Run the C# MCP server within a lightweight container. Ensure Docker and Docker Compose are installed.

# Clone the repository
git clone https://github.com/sandovaldavid/kioku.git
cd kioku

# Set your vault directory path
export KIOKU_VAULT_PATH=/path/to/your/vault

# Spin up the containers
docker-compose up -d

# Download embedding model for semantic search (first time only)
docker exec kioku-ollama ollama pull nomic-embed-text

Install the server directly on your host machine. Requires the ASP.NET Core 10 Runtime (contains Web Sdk dependencies for HTTP-SSE).

# Install global tool
dotnet tool install -g kioku-mcp-server

# Set your vault path
export KIOKU_VAULT_PATH=/path/to/your/vault

# Start the server (runs stdio listener by default)
kioku

Configure the server inside your AI environment in one command. Supports Claude Code, Codex, and Antigravity:

# Claude Code — registers Kioku and installs the kioku-vault skill
claude plugin marketplace add sandovaldavid/kioku && claude plugin install kioku@kioku

# Antigravity CLI & IDE (local workspace setup)
./scripts/add-to-client.sh antigravity --vault /path/to/your/vault

# Codex CLI
./scripts/add-to-client.sh codex --vault /path/to/your/vault

See the manual configuration files for VS Code, Cursor, and Zed in the Installation Guide.

Developer & User Manuals

Setup & Deployment

Full installation methods (Homebrew, WinGet, static binaries, Docker) and client configurations.

Read Guide

117 MCP Tools Reference

Complete documentation for all 18 capability groups, parameters, and return types.

View Reference

Vault Configuration

How to configure `.kioku/config.yml` in your vault to toggle capability groups and define folders.

View Layout

Authentication & Security

Secure the HTTP-SSE transport with API Keys, setup Sentry crash logs, and configure local bridge tokens.

View Security