Vault Configuration Guide

Kioku reads an optional configuration file at {KIOKU_VAULT_PATH}/.kioku/config.yml. Every section is optional — if the file or a section is missing, Kioku uses the defaults described below. Keys use snake_case (parsed with underscore naming convention).

A complete annotated example lives at vault-config.example.yml.

vault — Identity

vault:
  name: "My Vault"

Informational only; shown in logs and status tools.

folders — Where notes are created

Maps a folder role to a vault-relative path. Tools like create_zettel, create_literature_note, start_work_session, generate_digest and the template tools consult this map when the caller does not pass an explicit folder.

folders:
  inbox: "Inbox"
  zettel: "Zettelkasten"
  daily: "Daily"
  literature: "Literature"
  sessions: "Sessions"
  templates: "System/Templates"
  assets: "System/Attachments"
  projects: "Projects"     # engineering tool group: per-project workspaces
  knowledge: "Knowledge"   # engineering tool group: general knowledge notes

domains — Frontmatter domain by folder

Assigns the domain: frontmatter field to notes created inside a folder (or subfolder). Precedence: exact folder → longest folder prefix → defaults.{type}.domain.

domains:
  "Projects": "work/projects"
  "Research": "academic/research"

defaults — Frontmatter defaults per note type

Values merged into the frontmatter of new notes according to their type key. Explicit values passed in the tool call always win.

defaults:
  note:
    type: capture
    status: inbox
  zettel:
    type: concept
    status: active
    domain: tech/general
  literature:
    type: source
    status: draft
    tags: [source]

Each entry accepts type, status, domain and tags.

exclude — Folders excluded from the index

Dot-folders (.obsidian, .trash, .kioku, …) are always excluded. Add extra folders to keep them out of search, indexing and embeddings:

exclude:
  - "Archive"

auto_tags — Tag inheritance by folder

Notes created under a folder inherit its tags (longest prefix wins). exclude_from_tags lists frontmatter fields that must never be turned into tags (default: domain, type, status).

auto_tags:
  inherit:
    "Research": [research]
    "Research/Papers": [research, paper]
  exclude_from_tags: [domain, type, status]

template_folders — Templates by target folder, not by note type

Overrides the built-in body used by create_zettel, create_moc, and create_literature_note (and the general, non-project branch of start_work_session) when creating a note in a particular folder. Keyed by folder prefix (longest prefix wins, same precedence rule as domains), not by an internal note-type name — this matches how real vaults work: you might have several templates in play across different folders, or none at all for folders where the default body is fine.

template_folders:
  "Journal/Daily": "Templates/Daily Note.md"
  "Areas/Work/Meetings": "Templates/Meeting.md"

Each value is a vault-relative path to a markdown file (not inline body text). The file is read fresh on every note creation — edit it in Obsidian and the next note picks up the change immediately, no restart needed. It’s rendered with substitution first (built-ins , ,, ``, … plus tool-specific ones: create_zettel gets `<h2 id="common-issues">Common Issues</h2>

Server Won’t Start

Error: “KIOKU_VAULT_PATH environment variable is not configured”

Cause: The vault path environment variable is not set.

Solution:

export KIOKU_VAULT_PATH=/path/to/your/vault
# Or set it permanently in your shell profile (~/.bashrc, ~/.zshrc, etc.)

Error: “Vault path does not exist”

Cause: The specified vault path doesn’t exist or is not accessible.

Solution:

# Verify the path exists
ls -la /path/to/your/vault

# Check permissions
chmod 755 /path/to/your/vault

Plugin Issues

Bridge Not Starting

Symptoms: No bridge listening message in console, plugin shows as enabled but not working.

Possible Causes:

1. Port 7765 already in use
2. Plugin not properly installed
3. Obsidian needs restart

Solutions:

# Check if port is in use
lsof -i :7765

# Kill the process
kill -9 <PID>

# Or change the port in plugin settings

“Could not start the bridge” Notice

Cause: Port conflict or permission issue.

Solution:

1. Open plugin settings
2. Change bridge port to a different value (e.g., 7766)
3. Restart Obsidian
4. Update your MCP client config to use the new port

Bridge tools return “[error] [UNAUTHORIZED] …”

Cause: The plugin’s “Auth token” setting is configured but the server’s KIOKU_BRIDGE_TOKEN is missing, empty, or doesn’t match — or vice versa.

Solution:

1. Open the Kioku plugin settings in Obsidian and copy the “Auth token” value (or click “Generate” if none is set and you want to enable auth).
2. Set KIOKU_BRIDGE_TOKEN in the server’s environment to the exact same value.
3. Restart both the bridge (plugin command “Restart Kioku MCP Bridge”) and the MCP server.
4. To disable auth again, clear the “Auth token” field in the plugin and unset KIOKU_BRIDGE_TOKEN on the server — an empty token on either side falls back to the pre-auth, unauthenticated behavior.

Connection Issues

MCP Client Can’t Connect

Symptoms: “Connection refused” or timeout errors.

Checklist:

1. ✅ Server is running
2. ✅ Vault path is correct
3. ✅ Port matches between server and client config
4. ✅ No firewall blocking the connection
5. ✅ Plugin is enabled in Obsidian

Debug Steps:

# Test server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | kioku

# Test HTTP endpoint
curl http://localhost:5173/health

# Check plugin console
# Open DevTools in Obsidian (Ctrl+Shift+I) and look for errors

Semantic Search Issues

“Ollama not reachable” Warning

Cause: Ollama service is not running or not accessible.

Solution:

# Start Ollama
ollama serve

# Verify it's running
curl http://localhost:11434/api/tags

# Pull embedding model
ollama pull nomic-embed-text

Semantic Search Returns No Results

Possible Causes:

1. Embedding model not pulled
2. Vault not indexed yet
3. Index corrupted

Solutions:

# Ensure model is available
ollama list | grep nomic-embed-text

# Force re-index
# Restart the server or call rebuild_index tool

# Check logs for errors
# Look for "Embedding index ready" message

Performance Issues

Slow Startup

Cause: Large vault with many files to index, or a large embedding backlog (first run, or after a cache invalidation from an embedding model change).

Keyword indexing itself is fast and never blocked by embeddings — the server reports Status: [ok] Ready and answers search_notes/list_notes/etc. as soon as the vault’s file index is built. Semantic search (search_notes_semantic) is what’s degraded while a re-embedding backlog is being processed: it silently returns fewer or no semantic results until the backlog clears (keyword-only tools are unaffected).

Re-embedding runs in the background with limited concurrency (2 requests to Ollama at a time, to avoid saturating a CPU-only machine) and never blocks the server from starting or serving keyword search. A note whose content hasn’t changed since the last run is never re-embedded — only new or edited notes enter the backlog.

Check progress with get_index_status:

Embedding backlog: 42
Embedded this session: 158
Embedding rate: 24.3 notes/min
Estimated remaining: 1.7m

Solutions:

1. Exclude large folders in .kioku/config.yml: ```yaml exclude:
   • .obsidian
   • .trash
   • Attachments ```
2. Let the backlog drain in the background (subsequent starts are faster since unchanged notes are skipped — see get_index_status)
3. Consider splitting into multiple vaults

High Memory Usage

Cause: Large vault with many embeddings.

Solutions:

1. Reduce KIOKU_MAX_RESULTS (default: 20)
2. Exclude unnecessary folders
3. Restart server periodically to clear cache

File Operation Errors

“Path escapes the vault” Error

Cause: Attempting to access files outside the vault (security feature).

Solution:

• This is intentional security protection
• Ensure all file paths are within the vault
• Don’t use absolute paths or ../ in tool calls

“Note not found” Error

Possible Causes:

1. Note doesn’t exist
2. Note path is incorrect
3. Index is outdated

Solutions:

# Verify note exists
ls /path/to/vault/note.md

# Rebuild index
# Call rebuild_index tool or restart server

# Use exact path or note name
# Try: "Projects/My Note" instead of just "My Note"

Docker-Specific Issues

Container Won’t Start

# Check logs
docker logs kioku-server

# Common issues:
# 1. Vault path not mounted correctly
# 2. Port already in use
# 3. Ollama not ready

Ollama Connection Failed

# Ensure Ollama container is running
docker ps | grep ollama

# Check network connectivity
docker exec kioku-server curl http://ollama:11434/api/tags

# Restart Ollama container
docker restart kioku-ollama

Getting Help

Logs

Server logs:

# stdio transport - check your MCP client logs
# HTTP transport
docker logs kioku-server
# Or check systemd journal if running as service
journalctl -u kioku-server

Plugin logs:

• Open Obsidian Developer Console (Ctrl+Shift+I)
• Filter by “[Kioku]”

Diagnostic Information

Collect this information when reporting issues:

1. Server version: kioku --version or check release tag
2. Plugin version: Check in Obsidian Community Plugins settings
3. OS: uname -a or Windows version
4. Node.js version: node --version (if building from source)
5. .NET version: dotnet --version
6. Ollama version: ollama --version
7. Error messages: Full error text from logs
8. Configuration: Environment variables (redact sensitive values)

Report Issues

• GitHub Issues: https://github.com/sandovaldavid/kioku/issues
• Security Issues: See SECURITY.md

Include:

• Steps to reproduce
• Expected behavior
• Actual behavior
• Logs and diagnostic info
• Your configuration (redact secrets)

/; create_moc gets / — the generated notes list, so a template only replaces the *wrapper*, never the scan itself; create_literature_note gets ///). If the rendered result still contains [Templater](https://github.com/SilentVoid13/Templater) syntax (<% %>), it's evaluated the same way as the engineering group's templates (see below) — best-effort via the Obsidian bridge, with a [warning] and the literal <% %>` left in place if Templater/Obsidian aren’t reachable.

You usually don’t need to configure this at all. If you already use Templater’s own Settings → Folder Templates, Kioku reads and respects that configuration automatically — zero Kioku-specific setup required. template_folders here only adds mappings Templater doesn’t have (or an outright override, which always wins over Templater’s own setting for that folder), for vaults without Templater or that want a Kioku-specific mapping.

create_note (the fully generic creation tool) is deliberately not wired into this — it takes explicit content from the caller, and forcing a template there would silently override what was just asked to be written. Use create_note_from_template for “instantiate this exact template file” instead.

engineering — Per-project workspace subfolders

The engineering tool group (record_adr, log_bug, create_plan, add_knowledge, add_backlog_item, get_project_context, list_projects, setup_agent_workflow, list_engineering_templates, get_engineering_template, set_engineering_template) stores documents in per-project workspaces under folders.projects:

Projects/{project}/
  {project}.md   # project MOC note
  decisions/     # ADR-0001-{title}.md
  bugs/          # BUG-{date}-{title}.md
  plans/         # PLAN-{date}-{title}.md
  knowledge/     # project-specific knowledge
  sessions/      # {date-time}-{agent}.md work sessions
  daily/         # daily notes
  tickets/       # human-written tickets the agent structures
  backlog/       # future improvement ideas

Grouping projects. A project identifier can use / to nest projects under shared folders, e.g. record_adr(project: "Atena/api.core", ...) and ..."Atena/api.common" scaffold:

Projects/Atena/
  api.core/
    api.core.md   # MOC named after the leaf segment, not the full identifier
    decisions/ bugs/ plans/ ...
  api.common/
    api.common.md
    decisions/ bugs/ plans/ ...

A folder counts as a project once it has its own {leaf}.md MOC note (type: moc) or at least one of the standard subfolders; Atena/ itself has neither, so it’s a pure grouping folder — list_projects recurses through it but never lists it as a project itself. Pass the full identifier shown by list_projects ("Atena/api.core") to every other engineering tool. Nesting can be arbitrarily deep; only / is a group separator — backslashes, .., and empty segments (leading/trailing/double slashes) are rejected.

The subfolder names are configurable (values below are the defaults):

engineering:
  subfolders:
    decisions: "decisions"
    bugs: "bugs"
    plans: "plans"
    knowledge: "knowledge"
    sessions: "sessions"
    daily: "daily"
    tickets: "tickets"
    backlog: "backlog"

Document bodies come from templates. setup_agent_workflow copies the built-in defaults to {folders.templates}/kioku/{adr,bug,plan,knowledge,idea,session,daily,ticket,project-moc}.md; edit them in Obsidian and they override the embedded versions.

Template syntax. These templates use placeholders, evaluated by the server so they work headless (no Obsidian required). Besides the built-ins (, ,, , ...), each type receives its own variables: (the full identifier, e.g. Atena/api.core) and (a `[[wikilink]]` to the project's *leaf* name — `[[api.core]]` — that actually resolves in Obsidian even for grouped/nested projects; use this instead of `[[]]` in your own overrides) everywhere;, ,, , (adr); ,, , (bug); ,, `` (plan); `<h2 id="common-issues">Common Issues</h2>

Server Won’t Start

Error: “KIOKU_VAULT_PATH environment variable is not configured”

Cause: The vault path environment variable is not set.

Solution:

export KIOKU_VAULT_PATH=/path/to/your/vault
# Or set it permanently in your shell profile (~/.bashrc, ~/.zshrc, etc.)

Error: “Vault path does not exist”

Cause: The specified vault path doesn’t exist or is not accessible.

Solution:

# Verify the path exists
ls -la /path/to/your/vault

# Check permissions
chmod 755 /path/to/your/vault

Plugin Issues

Bridge Not Starting

Symptoms: No bridge listening message in console, plugin shows as enabled but not working.

Possible Causes:

1. Port 7765 already in use
2. Plugin not properly installed
3. Obsidian needs restart

Solutions:

# Check if port is in use
lsof -i :7765

# Kill the process
kill -9 <PID>

# Or change the port in plugin settings

“Could not start the bridge” Notice

Cause: Port conflict or permission issue.

Solution:

1. Open plugin settings
2. Change bridge port to a different value (e.g., 7766)
3. Restart Obsidian
4. Update your MCP client config to use the new port

Bridge tools return “[error] [UNAUTHORIZED] …”

Cause: The plugin’s “Auth token” setting is configured but the server’s KIOKU_BRIDGE_TOKEN is missing, empty, or doesn’t match — or vice versa.

Solution:

1. Open the Kioku plugin settings in Obsidian and copy the “Auth token” value (or click “Generate” if none is set and you want to enable auth).
2. Set KIOKU_BRIDGE_TOKEN in the server’s environment to the exact same value.
3. Restart both the bridge (plugin command “Restart Kioku MCP Bridge”) and the MCP server.
4. To disable auth again, clear the “Auth token” field in the plugin and unset KIOKU_BRIDGE_TOKEN on the server — an empty token on either side falls back to the pre-auth, unauthenticated behavior.

Connection Issues

MCP Client Can’t Connect

Symptoms: “Connection refused” or timeout errors.

Checklist:

1. ✅ Server is running
2. ✅ Vault path is correct
3. ✅ Port matches between server and client config
4. ✅ No firewall blocking the connection
5. ✅ Plugin is enabled in Obsidian

Debug Steps:

# Test server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | kioku

# Test HTTP endpoint
curl http://localhost:5173/health

# Check plugin console
# Open DevTools in Obsidian (Ctrl+Shift+I) and look for errors

Semantic Search Issues

“Ollama not reachable” Warning

Cause: Ollama service is not running or not accessible.

Solution:

# Start Ollama
ollama serve

# Verify it's running
curl http://localhost:11434/api/tags

# Pull embedding model
ollama pull nomic-embed-text

Semantic Search Returns No Results

Possible Causes:

1. Embedding model not pulled
2. Vault not indexed yet
3. Index corrupted

Solutions:

# Ensure model is available
ollama list | grep nomic-embed-text

# Force re-index
# Restart the server or call rebuild_index tool

# Check logs for errors
# Look for "Embedding index ready" message

Performance Issues

Slow Startup

Cause: Large vault with many files to index, or a large embedding backlog (first run, or after a cache invalidation from an embedding model change).

Keyword indexing itself is fast and never blocked by embeddings — the server reports Status: [ok] Ready and answers search_notes/list_notes/etc. as soon as the vault’s file index is built. Semantic search (search_notes_semantic) is what’s degraded while a re-embedding backlog is being processed: it silently returns fewer or no semantic results until the backlog clears (keyword-only tools are unaffected).

Re-embedding runs in the background with limited concurrency (2 requests to Ollama at a time, to avoid saturating a CPU-only machine) and never blocks the server from starting or serving keyword search. A note whose content hasn’t changed since the last run is never re-embedded — only new or edited notes enter the backlog.

Check progress with get_index_status:

Embedding backlog: 42
Embedded this session: 158
Embedding rate: 24.3 notes/min
Estimated remaining: 1.7m

Solutions:

1. Exclude large folders in .kioku/config.yml: ```yaml exclude:
   • .obsidian
   • .trash
   • Attachments ```
2. Let the backlog drain in the background (subsequent starts are faster since unchanged notes are skipped — see get_index_status)
3. Consider splitting into multiple vaults

High Memory Usage

Cause: Large vault with many embeddings.

Solutions:

1. Reduce KIOKU_MAX_RESULTS (default: 20)
2. Exclude unnecessary folders
3. Restart server periodically to clear cache

File Operation Errors

“Path escapes the vault” Error

Cause: Attempting to access files outside the vault (security feature).

Solution:

• This is intentional security protection
• Ensure all file paths are within the vault
• Don’t use absolute paths or ../ in tool calls

“Note not found” Error

Possible Causes:

1. Note doesn’t exist
2. Note path is incorrect
3. Index is outdated

Solutions:

# Verify note exists
ls /path/to/vault/note.md

# Rebuild index
# Call rebuild_index tool or restart server

# Use exact path or note name
# Try: "Projects/My Note" instead of just "My Note"

Docker-Specific Issues

Container Won’t Start

# Check logs
docker logs kioku-server

# Common issues:
# 1. Vault path not mounted correctly
# 2. Port already in use
# 3. Ollama not ready

Ollama Connection Failed

# Ensure Ollama container is running
docker ps | grep ollama

# Check network connectivity
docker exec kioku-server curl http://ollama:11434/api/tags

# Restart Ollama container
docker restart kioku-ollama

Getting Help

Logs

Server logs:

# stdio transport - check your MCP client logs
# HTTP transport
docker logs kioku-server
# Or check systemd journal if running as service
journalctl -u kioku-server

Plugin logs:

• Open Obsidian Developer Console (Ctrl+Shift+I)
• Filter by “[Kioku]”

Diagnostic Information

Collect this information when reporting issues:

1. Server version: kioku --version or check release tag
2. Plugin version: Check in Obsidian Community Plugins settings
3. OS: uname -a or Windows version
4. Node.js version: node --version (if building from source)
5. .NET version: dotnet --version
6. Ollama version: ollama --version
7. Error messages: Full error text from logs
8. Configuration: Environment variables (redact sensitive values)

Report Issues

• GitHub Issues: https://github.com/sandovaldavid/kioku/issues
• Security Issues: See SECURITY.md

Include:

• Steps to reproduce
• Expected behavior
• Actual behavior
• Logs and diagnostic info
• Your configuration (redact secrets)

` (knowledge); (idea);, (session); and the project MOC gets , ,, , for its Dataview blocks. Unknown placeholders are left as-is.

Templater interop. Templater is JavaScript that only runs inside Obsidian, while these documents are created by agents that may run headless — so the embedded default templates shipped by the server stay -only, guaranteeing the tool group works with Obsidian closed and Templater not installed. Your own vault override (in `{templates}/kioku/{typeKey}.md`, or a template passed to `create_note_from_template`) can mix in Templater syntax (`<% tp.* %>`) on top of the placeholders the agent fills with data: the server substitutes `` first, writes the note, then — if the resulting content still contains <% %> and Obsidian is open with the Kioku MCP plugin and Templater installed — asks the real Templater plugin to evaluate the file in place via the bridge. This applies to record_adr, log_bug, create_plan, add_backlog_item, add_knowledge, setup_agent_workflow (the project MOC), start_work_session, and the generic create_note_from_template. When Templater can’t be reached (Obsidian closed, plugin missing, bridge unreachable), note creation still succeeds and the response includes a [warning] template contains Templater syntax; left unevaluated (open Obsidian or use ) line — the <% %> snippet is left untouched in the file rather than silently dropped or corrupted. For human-triggered, on-demand evaluation of an arbitrary template file, use the apply_template tool instead.

Manual note creation from Obsidian. The above only covers notes created by the agent (via record_adr and friends). If you create a note by hand inside Projects/{project}/decisions/ (or any other engineering subfolder) directly from Obsidian, Templater applying the right template depends on you having that folder mapped in Templater’s own settings. To close that gap, scaffolding a project (setup_agent_workflow, or lazily on first record_adr/log_bug/…) also registers each of the project’s 8 subfolders in Templater’s Settings → Folder Templates — pointing to the same {templates}/kioku/{type}.md files the agent itself uses — so manual creation gets the right template too. The project root folder itself is never registered (that would apply the MOC template to any unrelated note created there). Existing mappings you already configured for a folder are never overwritten, even if they point somewhere else. This only runs once per project (first-time scaffold) and only if Templater is already installed — Kioku never creates Templater’s settings file from scratch. Obsidian loads Templater’s settings once at startup, so a session already open may need Templater reloaded (or the vault reopened) to pick up newly registered folders.

The default project MOC uses Dataview code blocks to auto-list ADRs, active plans, open bugs, and backlog ideas. Without the Dataview plugin they render as plain code blocks — replace them with manual lists if you prefer.

Managing engineering templates. Three tools manage the {templates}/kioku/*.md overrides directly, so you can ask an agent to create or tweak them without hand-editing files: list_engineering_templates (which doc types have an override vs. the embedded default, and which `` each supports), get_engineering_template(type_key) (read the current effective body before proposing an edit), and set_engineering_template(type_key, content, reset_to_default) (write or overwrite the override; reset_to_default=true deletes it, reverting to the embedded default). Supported variables per type:

These tools only write the template; they never trigger Templater evaluation — a template’s <% %> syntax is only evaluated later, when a note is generated from it.

Frontmatter properties. Notes created by the engineering tools get, beyond tags/type/status/domain/date/project, three native Obsidian properties: project_link — a quoted "[[LeafName]]" wikilink to the project’s MOC that resolves correctly even for grouped/nested projects (present on every doc type except the project MOC itself, which would just be a self-link); aliases — only ADRs get one (ADR-0001, so [[ADR-0001]] works as a short link); and cssclasses, a kioku-{type} class on every doc type (kioku-adr, kioku-bug, kioku-plan, kioku-idea, kioku-knowledge, kioku-session, kioku-project-moc) so a CSS snippet (css tool group: list_css_snippets/apply_css_snippet) can style each document type differently in Obsidian.

capabilities — Enable/disable tool groups

Kioku ships 128 tools across 19 groups. Every connected MCP client loads the full list of enabled tools (name, description, parameter schema) into its context at session start — with everything enabled that is roughly 19,000 tokens per session before the first question is asked. If you only use a handful of these groups, disabling the rest is the single biggest lever for cutting how many tokens Kioku costs per session — with no loss of functionality for the groups you keep. The core groups (NoteQueryTools, NoteCommandTools, UtilityTools, 26 tools ≈ 4,000 tokens) are always registered. The 16 optional groups can be gated; the token column is the approximate schema cost each group adds to every session:

Semantics:

• No capabilities section → all groups enabled (default).
• disabled — list of groups to turn off. "*" disables every optional group.
• require_explicit: true — only groups listed in enabled are registered.

# Example 1: everything except git and css
capabilities:
  disabled: [git, css]

# Example 2: allowlist mode — only tasks and zettelkasten
capabilities:
  require_explicit: true
  enabled: [tasks, zettelkasten]

# Example 3: recommended profile for coding-agent use (Claude Code, OpenCode, Antigravity).
# Drops ~4,500 tokens per session. git/restore are shell-native for these agents,
# css/assets/generation/research are niche unless you actively use them.
capabilities:
  disabled: [git, restore, css, assets, generation, research]

Changes require a server restart (tool groups are registered at startup).

Related docs

• Installation Guide
• Commands Reference — every tool with parameters
• Troubleshooting