No description https://yhkze.net/kioku
  • CSS 25.3%
  • HTML 20.8%
  • Python 20%
  • JavaScript 19.6%
  • Nix 8%
  • Other 6.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
yuuhikaze 4ca0f64f2b
All checks were successful
CI / check (pull_request) Successful in 3m53s
CI / check (push) Successful in 4m14s
docs: the VM test runs in CI, not locally
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 11:48:05 -05:00
.forgejo/workflows ci: skip the VM test for docs, chore and style pushes 2026-11-05 13:18:36 -05:00
.tern docs: canonical URL and link previews for the published docs 2026-11-05 15:41:03 -05:00
docs docs: the VM test runs in CI, not locally 2026-11-20 11:48:05 -05:00
docs-html docs: the VM test runs in CI, not locally 2026-11-20 11:48:05 -05:00
nix test: English fixture names and comments on what each file is 2026-11-20 11:48:05 -05:00
openwebui feat: add diagram skills and attach Open Terminal to models 2026-11-03 19:03:36 -05:00
skills docs(skills): publishing a set of notes with a script over ETAPI 2026-11-19 13:43:56 -05:00
src/kioku_mcp feat(trilium): video embed and responsive images in add_attachment 2026-11-19 13:43:56 -05:00
.gitignore chore: separate docs devShell and untrack the tern store 2026-11-05 13:16:58 -05:00
CLAUDE.md docs: the VM test runs in CI, not locally 2026-11-20 11:48:05 -05:00
flake.lock chore: pin tern to the v2.1.0 release tag 2026-11-07 12:44:19 -05:00
flake.nix chore: pin tern to the v2.1.0 release tag 2026-11-07 12:44:19 -05:00
pyproject.toml refactor: take the sandbox path and Open WebUI URL from config 2026-11-03 19:20:19 -05:00
README.md docs: the VM test runs in CI, not locally 2026-11-20 11:48:05 -05:00
secrets.example.toml feat(publish): set kioku's compaction threshold from model spec params 2026-11-18 12:34:18 -05:00
skills.toml refactor(skills): English skill ids 2026-11-20 11:48:05 -05:00

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:

  • Server — Anki replica, Trilium, files by reference, access, NixOS module
  • Open WebUI — tool server, skills, the Kioku model, publishing
  • Operations — status, logs, recovery
  • Development — layout, skill templates, tests, CI, deployment, docs

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. ↩︎