kioku

Docs an LLM assistant follows to edit the user's Trilium notes (via ETAPI) and Anki flashcards (via AnkiConnect) from a plain-language prompt.

Architecture

flowchart TD
    subgraph localhost [User machine]
        U[User prompt] --> L[LLM assistant]
        L -->|reads| D[Docs in this repo]
        L -->|reads| S[secrets.toml]
        L -->|HTTP :8765| A[AnkiConnect]
        A --> AN[Anki desktop app]
    end
    subgraph remote [Server: 10.100.0.1]
        T[Trilium server :8067] --> FS[(/var/lib/trilium)]
        SYNC[Anki sync server :27701]
    end
    L -->|HTTPS + ETAPI token| T
    AN -.->|sync| SYNC

No daemon or sync loop: each prompt triggers one round of ETAPI/AnkiConnect calls, then the LLM is done until the next prompt.

1. The user asks for a change in plain language.
2. The LLM reads secrets.toml for credentials and the relevant doc below for conventions — it doesn't invent formatting or structure.
3. Trilium edits go through ETAPI (search, read, create, patch, PUT content).
4. Anki edits go through AnkiConnect; if Anki isn't running, the LLM launches it.
5. Bulk/destructive edits trigger an ETAPI backup first, retrieved over SSH.

Why not RAG

Source material is read in full per generation pass, not retrieved by chunk. RAG pays off when a corpus can't fit in context and only a few chunks matter per query; here the goal is full syllabus coverage, where a retriever's imperfect recall would silently leave gaps before an exam. A course's material is a few thousand to tens of thousands of tokens — well within context, and cheaper than a vector index. RAG would make sense if the corpus grew to every course's bibliography and the task became one-off Q&A instead of exhaustive note generation.

Repo contents

• CLAUDE.md — credentials layout, Trilium deployment, ETAPI endpoints and note type/mime scheme, backup procedure, AnkiConnect setup.
• NOTES.md — Trilium note style (headings, bold, lists, math, tables).
• BOOK-NOTES.md — procedure for generating notes from a book/bibliography source.
• CARDS.md — flashcard rules: formula cards, deck/subdeck organization, the "Programming" note type for exact-syntax recall.
• CONVERT.md — legacy HTML-to-Markdown note conversion procedure and gotchas.
• secrets.example.toml — tracked template for secrets.toml (gitignored).

Trilium

Self-hosted, exposed at https://notes.yhkze.net¹. The local desktop app is a sync client only, not the source of truth.

All edits go through ETAPI (<trilium.url>/etapi, Authorization: <trilium.token>). SSH access to the server is used only to retrieve backup files.

Note type/mime determines handling:

• code + text/x-markdown — plain Markdown, the standard format going forward.
• text + text/html — legacy CKEditor rich text; reference CONVERT.md to migrate.
• canvas + application/json — Excalidraw scenes, left untouched.
• doc and the root noteId — system notes, skipped.

Anki

Anki runs as a Flatpak (net.ankiweb.Anki) with AnkiConnect exposing http://localhost:8765. All flashcard reads/writes go through AnkiConnect.

If AnkiConnect is unreachable, the LLM launches Anki into a silent Hyprland special workspace²:

hyprctl dispatch exec "[workspace special silent] flatpak run net.ankiweb.Anki"

A self-hosted sync server³ syncs collections between devices. It's unrelated to AnkiConnect: AnkiConnect talks to the local collection regardless of how it's synced elsewhere.

Credentials

secrets.toml (gitignored) holds trilium.url, trilium.token (an ETAPI token from Trilium's Options → ETAPI menu), and anki.url. secrets.example.toml is the tracked template.

---

1. Deployed via git.yhkze.net/yuuhikaze/nixos/modules/features/trilium-server.nix on 10.100.0.1, port 8067 behind traefik, data in /var/lib/trilium. ↩︎

2. Workspace mechanism configured in git.yhkze.net/yuuhikaze/nixos/modules/features/hyprland.nix. ↩︎

3. git.yhkze.net/yuuhikaze/nixos/modules/features/anki-sync-server.nix. ↩︎