Kioku Assistant — AI skill for Claude Code

Kioku (記憶)

**A private, self-hosted agentic personal assistant — a cloud brain with local hands.** *Kioku* (記憶, "memory") is a second brain that never sleeps: it owns a markdown knowledge vault, reasons over it with the Claude Agent SDK, works autonomously under a strict budget and approval model, and reaches you through Telegram, a web command center, or an API.

[](LICENSE)  


This is a portfolio/reference implementation of a single-user assistant. The design, architecture, and full build log live in [`docs/`](docs/INDEX.md). The owner's private knowledge vault is **not** part of this repository — the code runs against your own.

---

Why it's interesting

Most "AI assistant" projects are a thin wrapper around a chat endpoint. Kioku is the opposite: a small but complete **agentic system** engineered around three hard constraints — *cost*, *trust*, and *durable memory*.

• Files are truth, the database is an index. All knowledge is plain markdown in a git-backed vault. Postgres + pgvector is a rebuildable cache — drop it and lose nothing.
• It runs on a subscription, not a metered API. The whole cost architecture (Haiku triage → Sonnet work → Opus orchestration, prompt-cache-friendly prefixes, deterministic Python for anything that doesn't need a model, and a hard budget guard on every run) is designed to keep a genuinely useful always-on assistant inside a personal plan's monthly agent credit.
• Autonomy with a human gate. It works end-to-end up to any irreversible or outbound action — sending a message, spending money, deleting outside the vault — which it stages for one-tap approval instead of executing.
• It learns you over time. A derived model of you