- CSS 25.3%
- HTML 20.8%
- Python 20%
- JavaScript 19.6%
- Nix 8%
- Other 6.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| .tern | ||
| docs | ||
| docs-html | ||
| nix | ||
| openwebui | ||
| skills | ||
| src/kioku_mcp | ||
| .gitignore | ||
| CLAUDE.md | ||
| flake.lock | ||
| flake.nix | ||
| pyproject.toml | ||
| README.md | ||
| secrets.example.toml | ||
| skills.toml | ||
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.
- The user asks for a change in plain language, in Open WebUI or a coding agent.
- The agent follows the convention docs in
skills/, which reach Open WebUI as skills. - Every change is a
kiokuMCP tool call:anki_*for flashcards,trilium_*for notes. - Anki writes sync before and after, with a backup first; Trilium overwrites save a native revision first. Both are restorable through tools.
- 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.
-
https://git.yhkze.net/yuuhikaze/nixos:
modules/features/kioku-mcp.nix,modules/features/kioku-client.nix,docs/server/kioku-mcp.md. ↩︎