kioku

Conventions an LLM agent follows to edit the user’s Trilium notes and Anki flashcards from a plain-language prompt, and kioku-mcp, the MCP server that gives agents typed tools over both.

Architecture

flowchart LR
    subgraph server [Server]
        OWUI[Open WebUI] -->|MCP, loopback| K[kioku-mcp :8099]
        TR[Reverse proxy, WireGuard only] --> K
        K -->|sync protocol| SYNC[Anki sync server]
        K -->|ETAPI| TRI[Trilium]
        K --> REP[(Collection replica + backups)]
    end
    CC[Claude Code / OpenCode on desktop, laptop] -->|MCP over WireGuard| TR
    ANKI[Anki desktop] -.->|sync| SYNC
    DROID[AnkiDroid] -.->|sync| SYNC

The server keeps its own replica of the Anki collection and syncs it as one more device of the user’s account, so agents edit flashcards without the desktop app running. The desktop app and AnkiDroid stay as they were: review there, sync, and agent changes show up.

  1. The user asks for a change in plain language, in Open WebUI or a coding agent.
  2. The agent follows the convention docs in skills/, which reach Open WebUI as skills.
  3. Every change is a kioku MCP tool call: anki_* for flashcards, trilium_* for notes.
  4. Anki writes sync before and after, with a backup first; Trilium overwrites save a native revision first. Both are restorable through tools.
  5. Images reach the server by reference, not through the model: a path in Open WebUI’s sandbox or the id kioku-upload <file> prints.

Documentation

The documentation index links every page:

Quick start

Publish the skills and the Kioku model to Open WebUI, after filling in secrets.toml (reference Open WebUI):

cp secrets.example.toml secrets.toml
nix run path:.#publish-skills

Forgejo Actions runs the VM test on every push and pull request.

Send an image from a workstation, then pass the printed source to anki_add_media or trilium_add_attachment:

kioku-upload circuit.png

Compile the docs into docs-html/:

nix develop path:.#docs --command tern

Repository layout

CLAUDE.md             How agents use the tools (read by Claude Code and OpenCode)
skills/kioku/         Conventions for the user's notes and cards (NOTES, BOOK-NOTES, CARDS, CONVERT, MEDIA, REPORTS)
skills/diagrams/      Drawing figures, stored in kioku or not (DIAGRAMS, MERMAID, CIRCUITS)
skills.toml           Docs published as Open WebUI skills, and the models created with them (Jinja template)
secrets.example.toml  Template for secrets.toml (gitignored): Open WebUI URL, API key, template variables
openwebui/            Open WebUI filter that attaches Open Terminal to those models
src/kioku_mcp/        The MCP server and publish-skills
nix/                  Package, NixOS module (services.kioku-mcp) and VM test
.forgejo/workflows/   CI: the VM test on every push and pull request
docs/                 Documentation source (Markdown)
docs-html/            Compiled HTML (generated by tern)

Deployment

The nixos repo1 imports nixosModules.default from this flake and pins its nixpkgs to the same anki-suite input as the Anki sync server, so the server’s Anki library and the sync protocol never drift apart. kioku-mcp.nix runs the server; kioku-client.nix points Claude Code and OpenCode at it and installs kioku-upload. Reference Development for the update flow.


  1. https://git.yhkze.net/yuuhikaze/nixos: modules/features/kioku-mcp.nix, modules/features/kioku-client.nix, docs/server/kioku-mcp.md.↩︎