This manual is available in multiple languages

[!NOTE] 🌐 Available in: 🇬🇧 English · 🇯🇵 日本語 · 🇹🇼 繁體中文 · 🇨🇳 简体中文 · 🇮🇳 हिन्दी · 🇪🇸 Español · 🇧🇷 Português · 🇰🇷 한국어 · 🇫🇷 Français · 🇷🇺 Русский

KIOKU

Memory for Claude Code

KIOKU means "memory" in Japanese

License: MIT Claude Code Platform Follow @megaphone_tokyo

Claude Code forgets knowledge from past sessions as they go. KIOKU automatically accumulates your conversations into a Wiki and recalls them in the next session.

No more repeating the same explanations over and over. A "second brain" that grows with every use — for your Claude.

What It Does

Automatically record Claude Code sessions and build a structured knowledge base on an Obsidian Vault.

Combines Andrej Karpathy's LLM Wiki pattern with auto-logging and Git sync across multiple machines.

🗣️  You chat with Claude Code as usual
         ↓  (everything is recorded automatically — you don't do anything)
📝  Session logs saved locally
         ↓  (a scheduled job asks AI to read the logs and extract knowledge)
📚  Wiki grows with each session — concepts, decisions, patterns
         ↓  (synced via Git)
☁️  GitHub keeps your Wiki backed up and shared across machines
  1. Auto-capture (L0): Captures Claude Code hook events (UserPromptSubmit / Stop / PostToolUse / SessionEnd) and writes Markdown to session-logs/
  2. Structuring (L1): Scheduled execution (macOS LaunchAgent / Linux cron) has the LLM read unprocessed logs and build concept pages, project pages, and design decisions in wiki/. Session insights are also saved to wiki/analyses/
  3. Integrity check (L2): Monthly wiki health check generates wiki/lint-report.md. Automatic secret leak detection included
  4. Sync (L3): The Vault itself is a Git repo. SessionStart runs git pull, SessionEnd runs git commit && git push, syncing across machines via a GitHub Private repository
  5. Wiki context injection: At SessionStart, wiki/index.md is injected into the system prompt so Claude can leverage past knowledge
  6. qmd full-text search: Search wiki via MCP with BM25 + semantic search
  7. Wiki Ingest skills: /wiki-ingest-all and /wiki-ingest slash commands import existing project knowledge into the Wiki
  8. Secret isolation: session-logs/ stays local per machine (.gitignore). Only wiki/ / raw-sources/ / templates/ / CLAUDE.md are Git-managed

Important Notes

[!CAUTION] KIOKU currently requires Claude Code (Max plan). The Hook system (L0) and Wiki context injection are Claude Code-specific features. The Ingest/Lint pipeline (L1/L2) can work with other LLM APIs by swapping the claude -p call — this is planned as a future enhancement.

[!IMPORTANT] This software is provided "as is", without warranty of any kind. The authors assume no responsibility for any data loss, security incidents, or damages arising from the use of this tool. Use at your own risk. See LICENSE for full terms.

Prerequisites

Version / Requirement
macOS 13+ recommended
Node.js 18+ (hook scripts are .mjs ES Modules, zero external dependencies)
Bash 3.2+ (macOS default)
Git 2.x+. Must support git pull --rebase / git push
GitHub CLI Optional (gh simplifies private repo creation)
Claude Code Max plan required (uses claude CLI and Hook system in ~/.claude/settings.json)
Obsidian One Vault created in any folder (iCloud Drive not required)
jq 1.6+ (used by install-hooks.sh --apply)
poppler Optional but recommended. Enables PDF ingestion via pdftotext / pdfinfo. Install with brew install poppler (macOS) or apt install poppler-utils (Debian/Ubuntu). Without poppler, PDFs in raw-sources/ are silently skipped.
Env var OBSIDIAN_VAULT pointing to the Vault root

Quick Start

[!WARNING] Understand before you install: KIOKU hooks into all Claude Code session I/O. This means:

  • Session logs may contain API keys, tokens, or personal information from your prompts and tool output. Masking covers major patterns but is not exhaustive — review SECURITY.md
  • If .gitignore is misconfigured, session logs could be accidentally pushed to GitHub
  • The auto-ingest pipeline sends session log content to Claude via claude -p for Wiki extraction

We recommend starting with KIOKU_DRY_RUN=1 to verify the pipeline before enabling full operation.

🚀 Interactive Setup (Recommended)

[!NOTE] Enter the following in Claude Code to start an interactive, guided setup. It explains each step's purpose and adapts to your environment.

Please read skills/setup-guide/SKILL.md and guide me through the KIOKU installation.

🛠️ Manual Setup

[!NOTE] For those who want to understand each step. Run the scripts directly.

1. Create a Vault and connect it to a Git repository (manual)

  1. Create a new Vault in Obsidian (e.g., ~/kioku-vault/main)
  2. Create a Private repository on GitHub (e.g., kioku-vault)
  3. In the Vault directory: git init && git remote add origin ... (or gh repo create --private --source=. --push)

This step is not automated by KIOKU scripts. GitHub authentication (gh CLI / SSH keys) depends on your environment.

2. Set the environment variable

# Add to ~/.zshrc or ~/.bashrc
export OBSIDIAN_VAULT="$HOME/kioku-vault/main"

3. Initialize the Vault

# Creates raw-sources/, session-logs/, wiki/, templates/ under the Vault,
# places CLAUDE.md / .gitignore / initial templates (never overwrites existing files)
bash scripts/setup-vault.sh

4. Install Hooks

# Option A: Auto-merge (recommended, requires jq)
bash scripts/install-hooks.sh --apply
# Creates backup → shows diff → confirmation prompt → adds hook entries preserving existing config

# Option B: Manual merge
bash scripts/install-hooks.sh
# Outputs JSON snippet to stdout for manual merge into ~/.claude/settings.json

5. Verify

Restart Claude Code, then have one conversation. $OBSIDIAN_VAULT/session-logs/YYYYMMDD-HHMMSS-<id>-<prompt>.md should appear.

Steps 1–5 are required. The following are optional but recommended for full functionality.

6. Set up scheduled execution (recommended)

Configure automatic Ingest (daily) and Lint (monthly).

# Auto-detects OS: macOS → LaunchAgent, Linux → cron
bash scripts/install-schedule.sh

# Test with DRY RUN first
KIOKU_DRY_RUN=1 bash scripts/auto-ingest.sh
KIOKU_DRY_RUN=1 bash scripts/auto-lint.sh

macOS note: Placing the repo under ~/Documents/ or ~/Desktop/ may cause TCC (Transparency, Consent, Control) to block background access with EPERM. Use a path outside protected directories (e.g., ~/_PROJECT/).

7. Set up qmd search engine (optional)

Enable MCP-powered full-text and semantic search for the Wiki.

bash scripts/setup-qmd.sh
bash scripts/install-qmd-daemon.sh

8. Install Wiki Ingest skills (optional)

bash scripts/install-skills.sh

9. Deploy to additional machines

git clone [email protected]:<USERNAME>/kioku-vault.git ~/kioku-vault/main
# Open ~/kioku-vault/main/ as a Vault in Obsidian
# Repeat steps 2–6

10. MCP server for Claude Desktop / Code (optional)

Claude Desktop has no Hook system, so it cannot record sessions automatically. The kioku-wiki MCP server lets both Claude Desktop and Claude Code search, read, and write the Wiki manually.

# 1. Install dependency (only inside mcp/, parent repo stays package.json-free)
bash scripts/setup-mcp.sh

# 2. Smoke test with the official Inspector
npx @modelcontextprotocol/inspector node mcp/server.mjs

# 3. Preview client-config changes
bash scripts/install-mcp-client.sh --dry-run

# 4. Apply (merges into ~/Library/Application Support/Claude/claude_desktop_config.json)
bash scripts/install-mcp-client.sh --apply

# 5. Register with Claude Code (CLI / VSCode) via the printed stdio command
claude mcp add --scope user --transport stdio kioku \
  "$(command -v node)" "$(pwd)/mcp/server.mjs"

Nine tools provided:

Tool Purpose
kioku_search Wiki search (delegates to qmd CLI; falls back to a simple Node grep when qmd is unavailable)
kioku_read Return the contents of wiki/<path>.md
kioku_list Walk the wiki/ directory tree
kioku_write_note (recommended) Append a memo to session-logs/; the next auto-ingest cycle structures it into wiki/
kioku_write_wiki (advanced) Write directly into wiki/ with template + frontmatter auto-injection
kioku_delete Move a page to wiki/.archive/ (recoverable; wiki/index.md cannot be deleted)
kioku_ingest_document (feature 2.4) Unified ingest router for local documents under raw-sources/. Dispatches by extension: .pdf / .md → PDF handler, .epub → EPUB handler (yauzl + 8-layer defense + readability → chapter Markdown chunks), .docx → DOCX handler (mammoth + yauzl + XXE pre-scan → single Markdown chunk). Image / OLE embedded content is skipped for safety (MVP)
kioku_ingest_pdf (feature 2.1, deprecated alias) Deprecated alias for kioku_ingest_document restricted to .pdf / .md. Retained through the v0.5 – v0.7 window, removal planned for v0.8. Prefer kioku_ingest_document for new integrations
kioku_ingest_url (feature 2.2) Fetch an HTTP/HTTPS URL, extract the article body with Mozilla Readability, save Markdown + images under raw-sources/<subdir>/fetched/, and queue a wiki summary. PDF URLs auto-dispatch to kioku_ingest_document

Notes:

  • Fully local (stdio transport, no network exposure, single dep @modelcontextprotocol/sdk)
  • For "save this to my wiki" prompts in Desktop, prefer kioku_write_note — it preserves wiki coherence
  • Use kioku_write_wiki only when the user explicitly wants the page to appear immediately
  • Coexists with the existing qmd MCP (HTTP :8181). Prefer the qmd MCP search tool when available; kioku_search is the fallback.
Persistence & when to re-run

Once installed, you do not need to restart or re-run anything on reboot. The MCP server is spawned on-demand by Claude Desktop / Claude Code when a new conversation opens, and terminates when the conversation ends — there's no daemon to manage. OS reboots, Desktop relaunches, and Claude Code restarts all "just work".

Re-run the steps only in these specific cases:

Trigger Re-run
Moved the repo to a different directory Steps 3 & 5 (they record absolute paths to mcp/server.mjs)
Switched Node version (mise / nvm / Volta) Step 3 (the script hardcodes command -v node)
Changed the OBSIDIAN_VAULT env var Step 3 (the value is baked into the config at apply time)
@modelcontextprotocol/sdk major version bump Step 1 (setup-mcp.sh to refresh node_modules)

Uninstall:

bash scripts/install-mcp-client.sh --uninstall
rm -rf mcp/node_modules

11. MCPB bundle for Claude Desktop (one-file install)

If you only use Claude Desktop and want the shortest install path, install the MCPB bundle with a single drag & drop. The bundle includes mcp/server.mjs and all production dependencies; Claude Desktop launches it with its built-in Node runtime, so end users do not need to install Node themselves.

Option A — Install a pre-built release (recommended for end users)
  1. Download the latest kioku-wiki-<version>.mcpb from github.com/megaphone-tokyo/kioku/releases
  2. Open Claude Desktop
  3. Either:
    • Double-click the .mcpb file in Finder (macOS associates .mcpb with Claude Desktop), or
    • Open Settings → Extensions / Connectors and drag the .mcpb onto that screen
    • (Don't drop it on the chat window — it'll be treated as a file attachment)
  4. In the install dialog, pick your Vault directory (the folder containing wiki/, session-logs/, raw-sources/) → Install
  5. Open Settings → Connectors and confirm KIOKU Wiki is enabled
  6. Start a new chat and try: kioku_read で wiki/index.md を読んで (existing chats won't see the new tools)

Note: Claude Desktop will warn that the extension has not been verified by Anthropic. This is expected — mcpb sign for code signing is a planned future enhancement.

Option B — Build from source (developers / contributors)
# 1. Build the .mcpb bundle (writes mcp/dist/kioku-wiki-<version>.mcpb, ~3.2 MB)
bash scripts/build-mcpb.sh

# 2. (Optional) validate manifest + inspect contents
bash scripts/build-mcpb.sh --validate
npx --yes @anthropic-ai/mcpb info mcp/dist/kioku-wiki-0.1.0.mcpb

# 3. Clean build artifacts
bash scripts/build-mcpb.sh --clean

The bundle is gitignored (mcp/build/, mcp/dist/). To publish a new release: run build-mcpb.sh, then attach the resulting .mcpb to a new GitHub Release of the megaphone-tokyo/kioku repo. End users will then download it via Option A.

The traditional install paths in step 10 still work — MCPB is purely an additional delivery channel for Desktop-first users.

Persistence & when to re-install

Once installed, the .mcpb persists through reboots and Desktop restarts. Claude Desktop auto-spawns the server when a new conversation opens — you don't need to relaunch anything manually.

Re-install only in these cases:

Trigger Action
Moved your Obsidian Vault directory Re-run the install (the dialog will re-ask for Vault directory) OR edit ~/Library/Application Support/Claude/claude_desktop_config.json manually
New .mcpb version released Download the new .mcpb and drag-install; Desktop replaces the existing extension in place
Uninstalled via Settings → Connectors by accident Drag the same .mcpb back in

Unlike § 10, MCPB is self-contained — moving this source repo, switching Node versions, or updating @modelcontextprotocol/sdk do NOT affect an already-installed .mcpb (the bundle ships its own dependencies and launches via Desktop's built-in Node runtime).

⚠️ After installing or updating a .mcpb, fully quit Claude Desktop (⌘Q, not just close the window) and relaunch. Otherwise the previously-spawned MCP server process keeps serving cached code in memory — your new tool definitions will appear, but behavioral changes inside the server (bug fixes, validation updates, etc.) won't take effect until the process is recreated.

Tips — using kioku on Claude Desktop

Unlike Claude Code (which auto-logs every session via the session-logger.mjs hook), Claude Desktop has no hook system — your conversations are NOT automatically captured into the Vault. You must explicitly ask Claude to save each thing you want to remember.

Phrases that trigger saves (Claude picks the right tool from the tool descriptions):

You say Tool invoked Destination
"save this to my wiki" / "remember this" / "メモして" kioku_write_note session-logs/ → structured into wiki/ by the next auto-ingest cycle
"create this wiki page now" / "immediately reflect this" / "すぐ Wiki に作って" kioku_write_wiki wiki/ directly (immediate, template applied, best-effort wikilink integrity)

Practical habit: at the end of a meaningful conversation segment, ask Claude something like "今の話をまとめてメモしておいて" or "この設計判断を記録して". Without this nudge, your Desktop conversation stays only in Claude's chat history — not in your Obsidian Vault.

If you also use Claude Code, its conversations are captured automatically without any manual request (via the hook system in step 4 above). The two clients write to the same Vault — your "second brain" accumulates knowledge from both.

Directory Structure

kioku/
├── README.md                        ← This file
├── context/                         ← Current implementation (INDEX + per-feature docs)
├── handoff/                         ← Handoff notes for next session
├── plan/
│   ├── user/                      ← User's design instructions
│   └── claude/                      ← Claude's implementation specs
├── hooks/
│   ├── session-logger.mjs           ← Hook entry point (UserPromptSubmit/Stop/PostToolUse/SessionEnd)
│   └── wiki-context-injector.mjs    ← SessionStart: inject wiki/index.md into system prompt
├── skills/
│   ├── wiki-ingest-all/SKILL.md     ← Bulk project-to-Wiki import slash command
│   └── wiki-ingest/SKILL.md         ← Targeted scan slash command
├── templates/
│   ├── vault/                       ← Vault root files (CLAUDE.md, .gitignore)
│   ├── notes/                       ← Note templates (concept, project, decision, source-summary)
│   ├── wiki/                        ← Initial wiki files (index.md, log.md)
│   └── launchd/*.plist.template     ← macOS LaunchAgent templates
├── scripts/
│   ├── setup-vault.sh               ← Vault initialization (idempotent)
│   ├── install-hooks.sh             ← Hook config snippet output / --apply for auto-merge
│   ├── auto-ingest.sh               ← Scheduled: ingest unprocessed logs into wiki
│   ├── auto-lint.sh                 ← Scheduled: wiki health report + secret scanning
│   ├── install-cron.sh              ← Output cron entries to stdout
│   ├── install-schedule.sh          ← OS-aware dispatcher (macOS → LaunchAgent / Linux → cron)
│   ├── install-launchagents.sh      ← macOS LaunchAgent installer
│   ├── setup-qmd.sh                 ← qmd collection registration + initial indexing
│   ├── install-qmd-daemon.sh        ← qmd MCP HTTP server as launchd daemon
│   ├── install-skills.sh            ← Symlink wiki-ingest skills to ~/.claude/skills/
│   └── scan-secrets.sh              ← Secret leak detection in session-logs/
└── tests/                           ← node --test and bash smoke tests

Environment Variables

Variable Default Purpose
OBSIDIAN_VAULT none (required) Vault root. auto-ingest/lint fall back to ${HOME}/kioku-vault/main
KIOKU_DRY_RUN 0 1 to skip claude -p calls (path verification only)
KIOKU_NO_LOG unset 1 to suppress session-logger.mjs (prevents recursive logging from cron subprocesses)
KIOKU_DEBUG unset 1 to emit debug info to stderr and session-logs/.claude-brain/errors.log
KIOKU_INGEST_LOG $HOME/kioku-ingest.log Ingest log output path (referenced by auto-lint self-diagnostics)

Node Version Manager PATH Setup

Scheduled scripts (auto-ingest.sh, auto-lint.sh) run from cron / LaunchAgent and don't inherit your interactive shell's PATH. They add Volta (~/.volta/bin) and mise (~/.local/share/mise/shims) to PATH. If you use nvm / fnm / asdf or another version manager, edit the export PATH=... line at the top of each script:

# nvm example
export PATH="${HOME}/.nvm/versions/node/v22.0.0/bin:${PATH}"

# fnm example
export PATH="${HOME}/.local/share/fnm/aliases/default/bin:${PATH}"

Design Notes

  • Session logs contain secrets: Prompts and tool output may include API keys, tokens, or PII. session-logger.mjs applies regex masking before writing
  • Write boundary: Hooks only write to $OBSIDIAN_VAULT/session-logs/. They never touch raw-sources/, wiki/, or templates/
  • session-logs never reach Git: Excluded by .gitignore, minimizing the risk of accidental pushes to GitHub
  • No network access: Hook scripts (session-logger.mjs) do not import http/https/net/dgram. Git sync is handled by shell one-liners in the Hook config
  • Idempotent: setup-vault.sh / install-hooks.sh can be run multiple times without destroying existing files
  • No git init: setup-vault.sh does not initialize a Git repo or add remotes. GitHub authentication is the user's responsibility

Multi-Machine Setup

KIOKU is designed to share a single Wiki across multiple machines via Git sync. The author runs a two-Mac setup: a MacBook (primary dev machine) and a Mac mini (for Claude Code bypass permission mode).

Key points for multi-machine operation:

  • session-logs/ stays local per machine (excluded by .gitignore). Each machine's session logs are independent and never pushed to Git
  • wiki/ is Git-synced. Ingest results from any machine accumulate in the same Wiki
  • Stagger Ingest/Lint execution times across machines to avoid git push conflicts
  • SessionEnd Hook auto commit/push is enabled on all machines, but normal coding sessions only write to session-logs/ — git operations only trigger when wiki/ is directly modified

Reference: author's two-Mac configuration

MacBook (primary) Mac mini (bypass)
Secrets Yes No
session-logs/ Local only Local only
wiki/ Git-synced Git-synced
Ingest schedule 7:00 / 13:00 / 19:00 7:30 / 13:30 / 19:30
Lint schedule 1st of month 8:00 2nd of month 8:00
Scheduler LaunchAgent LaunchAgent

If you're running on a single machine, you can ignore this section entirely. The Quick Start steps are all you need.

Security

KIOKU is a Hook system that accesses all Claude Code session I/O. See SECURITY.md for the full security design.

Defense Layers

Layer Description
Input validation OBSIDIAN_VAULT path checked for shell metacharacters and JSON/XML control characters
Masking API keys (Anthropic / OpenAI / GitHub / AWS / Slack / Vercel / npm / Stripe / Supabase / Firebase / Azure), Bearer/Basic auth, URL credentials, PEM private keys replaced with ***
Permissions session-logs/ created with 0o700, log files with 0o600. Hook scripts set to chmod 755
.gitignore guard Verifies .gitignore contains session-logs/ before every git commit
Recursion prevention KIOKU_NO_LOG=1 + cwd-in-vault check (double guard) prevents recursive logging from subprocesses
LLM permission restriction auto-ingest / auto-lint run claude -p with --allowedTools Write,Read,Edit (no Bash)
Periodic scanning scan-secrets.sh scans session-logs/ monthly for known token patterns to detect masking failures

Adding Token Patterns

When you start using a new cloud service, add its token pattern to both hooks/session-logger.mjs (MASK_RULES) and scripts/scan-secrets.sh (PATTERNS).

Reporting Vulnerabilities

If you find a security issue, please report it via SECURITY.md — not through public Issues.

Roadmap

Near-term

  • Ingest quality tuning — Review and adjust selection criteria in Vault CLAUDE.md after 2 weeks of real-world Ingest runs
  • qmd multilingual search — Verify semantic search accuracy for non-English content; swap embedding model if needed (e.g., multilingual-e5-small)
  • Safe auto-fix skill (/wiki-fix-safe) — Auto-fix trivial Lint issues (add missing cross-links, fill frontmatter gaps) with human approval
  • Git sync error visibility — Log git push failures to session-logs/.claude-brain/git-sync.log and surface warnings in auto-ingest

Mid-term

  • Multi-LLM support — Replace claude -p in auto-ingest/lint with a pluggable LLM backend (OpenAI API, local models via Ollama, etc.)
  • CI/CD — GitHub Actions for automated testing on push
  • Lint diff notifications — Show only newly detected issues by diffing against the previous lint report
  • Optimistic locking for index.json — Prevent lost updates when multiple Claude Code sessions run in parallel

Long-term

  • Morning Briefing — Auto-generate a daily summary (yesterday's sessions, open decisions, new insights) as wiki/daily/YYYY-MM-DD.md
  • Project-aware context injection — Filter wiki/index.md by the current project (based on cwd) to stay within the 10,000-char limit
  • Stack recommendation skill (/wiki-suggest-stack) — Suggest tech stacks for new projects based on accumulated Wiki knowledge
  • Team Wiki — Multi-person Wiki sharing (each member's session-logs stay local; only wiki/ is shared via Git)

Note: KIOKU currently requires Claude Code (Max plan). The Hook system (L0) and Wiki context injection are Claude Code-specific. The Ingest/Lint pipeline (L1/L2) can work with other LLM APIs by swapping the claude -p call — this is planned as a future enhancement.

Changelog

2026-07-09 — v0.11.0: "Your memory favors your newest interests, and the health check finishes in 0.1 seconds" — internal hardening 6 件 + recency decay

v0.11.0 ships recency decay (検索の時間減衰) + internal hardening 6 件 — v0.10.0 (Sprint 5.5) で入った「使うほど賢くなる検索」(session-logs 学習) が 新しい関心を優先 するようになり、「自分の KIOKU は健康?」が 0.1 秒 で分かり、hook の 静かな失敗に気づける ようになる。

v0.10.0 の reliability + intelligence 2 軸をそのまま深掘りする進化 — intelligence 側は時間減衰で「今の関心」に追従し、reliability 側は見えない失敗の可視化と SSOT 統合で土台を固める。

  • 検索の時間減衰 (recency decay) ("検索が古い関心に引きずられない"):
    • session-logs 学習 (v0.10.0 の Source 8) に 半減期 14 日の指数減衰 を追加 — 古い高頻度の関心より、新しい関心が上位に
    • KIOKU_DQ_HALFLIFE_DAYS 環境変数で半減期を調整可
    • opt-out (.kioku-discoverqueries-opt-out) とプライバシー契約は従来のまま不変
  • doctor --quick ("自分の KIOKU は健康? が 0.1 秒で分かる"):
    • bash scripts/doctor.sh --quick — 3 項目 (直近セッションログの有無 / wiki の中身 / MCP 登録) を 0.1 秒未満 で確認
    • フル診断 (38 項目) は従来どおり flag なし、--json 併用可
  • install script 階層化 — scripts/install/user/ (ユーザーが触る 3 本) と scripts/install/internal/ (内部用 7 本) に整理。旧 path は [DEPRECATED] 案内付きの互換 shim を 2 release 維持、ワンライナー install の公開 URL (scripts/install.sh) は不変
  • Mode gate — Claude Code 環境で手動 hook install しようとすると /plugin install を案内 (--force で override 可)
  • Hook silent failure の可視化 + 内部堅牢化:
    • hook の静かな失敗 (空の応答 / 変換拒否 / ファイル競合) を全てログ記録 (masking 経由) + doctor 診断 + セッション開始時の通知で可視化 — 秘匿情報がログに漏れない設計はここでも維持
    • masking ルール (21 パターン) と検証ロジックを共有リテラル構造に統合、drift を機械検出する parity test を新設
    • vault path 検証を 12 script の個別実装から 1 ライブラリに SSOT 統合
  • Tests — full test suite exit 0 (doctor 89 / install-hierarchy 58 / mask-parity 7 assertion 他)、8 PR + branch 横断の統合レビューで Critical 0
  • Release v0.11.0

2026-05-19 — v0.10.0: "Your auto-ingest never fails silently, and search learns from your own sessions" — Sprint 5 + 5.5 完走 (reliability + intelligence の 2 軸進化)

v0.10.0 ships Sprint 5 (axis A) + Sprint 5.5 (axis B) 全完走 — v0.9.0 (Sprint 4) で「使いたい時に使える体験」が 4 軸揃った上で、v0.10.0 は 基盤の信頼性と検索の知能を 2 軸 で底上げする。「自動取り込みが network 一時失敗で静かに止まらない」「検索 query が自分の過去 session から自動で学習して賢くなる」 — この 2 つを reliability + intelligence の bundle minor release として land。

KIOKU positioning に reliability (auto-ingest 自己回復) + intelligence (discoverQueries 自動学習) の 2 軸が加わる。Sprint 4 (v0.9.0) の 4 pillar narrative の上に、基盤を強くする 2 軸進化。

  • Sprint 5 axis A — auto-ingest pipeline reliability ("取り込みが静かに失敗しない"):
    • hooks/auto-ingest-retry.mjs — auto-ingest 失敗を retry queue で 3 回 exponential backoff + persistent queue、次回起動時 resume
    • classify — 失敗を category 分類 (network / transient / permanent) して recovery 戦略を分岐
    • manual review queue — 自動回復不能な item を user が後から確認できる queue へ退避
    • credential masking — retry log に token / password が残らないよう applyMasks SSOT で redact
    • scripts/doctor.sh check_auto_ingest_state — queue 残件 / 最終成功時刻 / 失敗 category を read-only diagnostic
    • LEARN#8b N=3 mandatory extract pattern 達成
  • Sprint 5.5 axis B — discoverQueries 自動学習 ("検索が自分の会話から自動で賢くなる"):
    • mcp/lib/discoverqueries-learning.mjs — discoverQueries に session-logs/ scan = 8th source (weight 2.8、既存 7 source 中最高) を additive 統合、過去 session から query を dynamic 学習
    • privacy contract 3 axis — (1) masking SSOT applyMasks で sensitive content を pin (2) .kioku-discoverqueries-opt-out で opt-out (3) .kioku-discoverqueries-usage.json 64KB FIFO rotate で usage log を bounded に
    • scripts/doctor.sh check_discoverqueries_state — 3 axis (learning 有効性 / opt-out / usage log) を read-only diagnostic
    • LEARN#8b N=4 reinforcement (mockSessionLogScan + readUsageLog)
  • Hardened 設計契約 2 axis 通底 — credential masking SSOT (applyMasks) を auto-ingest retry log と discoverQueries usage log の両方で再利用、秘密を共有しても漏れない契約を 2 軸横断で維持
  • Tests — Sprint 5 (auto-ingest-retry .mjs/.sh + auto-ingest-diagnostic + doctor) + Sprint 5.5 (discoverqueries-learning + discoverqueries-privacy + discoverqueries-diagnostic) 全 BLUE-* green、Sprint 4 累計 regression なし
  • subagent-driven N=29-34 cycle — Sprint 5 (N=29-31) + Sprint 5.5 (N=32-34)、axis A+B 各 PR A/B/C の N=3 cycle 簡略形 × 2
  • Release v0.10.0 — kioku-wiki-0.10.0.mcpb attached

2026-05-15 — v0.9.0: "Open your wiki in a browser, search with Claude, even from your phone" — Sprint 4 完走 (4 pillar: Shell + Search + Mobile + Sync polish)

v0.9.0 ships Sprint 4 全 phase 完走 — Sprint 3 (v0.8.0 Visualizer β) で「過去が見える」が揃った上で、Sprint 4 は 「使いたい時に使える体験」を 4 軸 で揃える。「Obsidian を起動せずブラウザで Wiki を一望」「ブラウザで keyword 検索 → Claude で深掘り」「スマホで Wiki を読める」「Git push が静かに失敗しない」 — この 4 つの疑問に 3 日間 (5/13–5/15) で 4 phase land。

KIOKU positioning が "Hardened LLM Wiki for Professionals + Claude-augmented Search + Mobile responsive + Sync polished" の 4 pillar narrative に確立。Path C+β progress 70% → 100% 達成、Sprint 4 全 cycle 完走 marker。

  • Phase 1 (5/13) — Web UI shell + Bases dashboard renderer ("Obsidian なしで Wiki を一望"):
    • kioku_generate_viz mode=shell で 8-tab self-contained HTML を出力 ([Dashboard] [Overview] [Timeline] [Diff] [Lineage] [Search] [Navigation] [Wikilink])
    • Bases dashboard renderer — wiki/meta/*.base を Node stdlib のみで parse、Obsidian Bases plugin の view を Obsidian なしで再現 (Hot Cache / Active Projects / Concepts / Decisions など)
    • Path C+β 設計境界: editor は作らない (Monaco / CodeMirror 全部 forbidden keyword)、新規ページ作成 UI なし、外部 CDN / fetch / WebSocket 0、Canvas alternative 外。Wiki を書くツールは Obsidian / VS Code に任せ、KIOKU は Markdown 解析プラットフォーム に徹する分業
    • 8 タブの placeholder で「Phase 2 で実装予定」label — 後から追加する shape を最初に固定して、ユーザーの URL #tab=... を将来 stable に
  • Phase 2 (5/14) — Claude-augmented Search ("ブラウザで keyword → Claude で深掘り"):
    • kioku_search に intent param + discoverQueries 3→7 source 拡張 (LLM が「何を探しているか」を伝えて snippet 精度向上)
    • shell Search tab UI — Tier 1 offline filter (precomputed JSON inline、HTTP サーバ不要、CSRF / port 衝突 / CORS 攻撃面 全 0)
    • Tier 2 deep-link "Claude で深掘り検索" — Tier 1 で足りない時 1 click で Claude session 起動、Claude が KIOKU MCP tool を叩いて深掘り回答
    • Visualizer β URL fragment #q=... → graph node highlight 連動 (shell Search tab から "view in graph" deep-link)
    • Option C 採用 meeting (6 role) で「localhost HTTP サーバ立てない」を意図的決定 — Hardened LLM Wiki positioning と整合、攻撃面追加なし
  • Phase 3 (5/14 夜) — Mobile responsive ("スマホで Wiki を読みたい"):
    • shell + viz responsive CSS + hamburger menu + tap target 44pt+ (iOS Safari + Android Chrome real device verified)
    • Tier 2 Mobile deep-link — claude:// URI scheme + 1.5s timeout + claude.ai web fallback (Claude モバイルアプリ未 install でも graceful degrade)
    • iOS auto-zoom 防止 16px font-size + virtual keyboard scroll 対応
    • Mobile simplified view (renderMobileFallback textContent only) + 300KB performance budget guard — 大きな graph は scroll listview に degrade
    • CSP navigate-to policy で claude:// URI scheme 許可、他 URI scheme は blocked
  • Phase 4 (5/15) — Sync polish ("Git push が静かに失敗しない"):
    • sync-vault.mjs Git push retry queue — network 一時失敗を 3 回 exponential backoff + persistent queue で次回起動時 resume
    • classifyGitError — push failure を 5 category 分類 (network / auth / conflict / quota / unknown)、user-facing message + recovery hint
    • maskCredentials — error message から token / password / SSH key path を redact、log を共有しても秘密が漏れない
    • doctor.sh sync state diagnostic (check_sync_state) — git status + git log @{u}.. を read-only audit、retry queue 残件を visualize
    • 44 件新規 BLUE-* test (Phase 4 累計、retry / classify / mask / doctor diagnostic + sync-diagnostic.test.sh)
  • Sprint 3 + Sprint 4 全 phase 累積 stats — Sprint 3 (4 phase) + Sprint 4 (4 phase × 15 sub-PR) = 8 phase / ~19 sub-PR を 4 月後半～5 月中旬の 3 週間 で land、Path C+β 70% → 100% completion
  • Hardened 設計契約 4 phase 通底 — offline-first / textContent only / 外部依存ゼロ / 攻撃面追加ゼロ、を 4 phase ずっと崩さない (Phase 2 Search の Option C / Phase 3 Mobile の textContent only / Phase 4 Sync の credential masking で連続して効いた)
  • subagent-driven N=28 of 28 cycle — Sprint 4 全 cycle で subagent-driven development pattern (LEARN#7 中規模 feature の 5 層 formula) を 4 phase × 4 cycle 連続適用、累計 N=28
  • Release v0.9.0 — kioku-wiki-0.9.0.mcpb attached

2026-05-13 — v0.8.0: "Open KIOKU and see what your memory looks like" — HTML Visualizer β (Sprint 3 完走)

v0.8.0 ships Sprint 3 (価値の可視化) completion — Sprint 1 (信頼性) と Sprint 2 (記憶品質) で 「自分の KIOKU は動いてる? Wiki は腐ってない?」 に答える土台ができた上で、Sprint 3 は 「自分の記憶がどう育っているか」 を 5 秒で見せる HTML Visualizer β を提供する。Obsidian なしで開ける self-contained HTML として、kioku_generate_viz MCP tool が 4 view (Overview / Timeline / Diff / Lineage) を 1 ファイルに包む。

This is the first release where KIOKU can show its value without Obsidian — drag-and-drop the generated HTML into any browser and see your second brain breathe.

  • Overview tab (Phase 1 + 2) — Open KIOKU and see 4 layers at a glance:
    • Vault overview — pages total, summaries growth (7d/30d), page type distribution
    • Health focus — broken wikilinks (cluster view with merge candidates) / source sha256 duplicates / warm zone (7-30 days, fresh→warm→stale gradient)
    • Graph preview — hot pages by inbound degree / active projects / recent decisions
    • Action queue — 3-5 actionable items with P0/P1/P2 priority + concrete next_action
  • Status banner + 5 visualizations (Phase 2) — All pure CSS + DOM, no external chart library:
    • bar chart for page type distribution
    • sparkline for summaries growth rate (7d/30d)
    • warm zone gradient (fresh/warm/stale 3-segment bar)
    • broken wikilink cluster (target で grouped, merge candidate view)
    • source_sha256 duplicate cluster (same-source 重複 page の merge surface)
  • Lineage tab (Phase 3) — KIOKU's distinctive view: raw-sources → summaries → wiki pages の 3 layer lineage graph with 5 edge types (sha256 / derived_from / filename / wikilink / time proximity). 300-node cap, best-effort hint, 1-2 hop subgraph helper. Real Vault dogfood: 184 nodes / 846 edges in 68ms.
  • Quality notes drawer (Phase 4) — wiki/lint-report.md (auto-lint output) を 5 枚目の Overview card として表示。Phase 2 で 2 重 negative assert していた契約を Phase 4 で flip (negative → positive) — auto-lint 4 観点 (concept contradiction / concept splinter / dedicated page candidate / semantic wikilink gap) が drawer に並ぶ。kioku_health の 11 machine-checkable metrics と auto-lint の LLM judgment が non-overlapping surface で共存する。
  • §46 N=3 mandatory refactor — mcp/lib/wiki-walker.mjs 抽出、3 caller (health-metrics / visualizer-data / lineage-graph) を walkPages() 共通 entry point に統一。LEARN#8b framework の好例。
  • Tests: 38 Phase 4 (visualizer-data 24 + visualizer 10 + screenshot 4) + 45 Phase 3 (wiki-walker 9 + lineage-graph 7+補強 + visualizer-data 15 + mcp/visualizer 9) + 全 Node + Bash regression 全 pass。CI screenshot regression (tests/mcp/tools-visualizer-screenshot.test.mjs) で empty / small Vault fixture を deterministic に走らせる。
  • Real-world dogfood (PM Vault, 162 pages) — Overview tab で broken=23 / sha256_dup=2 / warm=99、Lineage tab で 184 nodes / 846 edges、auto-lint drawer で 4 categories surface。HTML self-contained 61.5KB (external script/link/fetch 全 0)
  • Release v0.8.0 — kioku-wiki-0.8.0.mcpb attached

2026-05-08 — v0.7.5: Sprint 2 完走 — kioku_health 11 metrics (stretch 5 追加) + auto-lint refactor

v0.7.5 marks Sprint 2 (記憶品質 dashboard) completion — same-day micro cascade after v0.7.4 morning release. Where v0.7.4 shipped the core 6 metrics (orphan / stale / duplicate title / hot.md age / last ingest / unprocessed session-logs), v0.7.5 adds the stretch 5 metrics identified in the codex roadmap §「指標案」 and refactors auto-lint to no longer overlap with kioku_health's machine-checkable surface.

  • kioku_health 6 → 11 metrics — the 5 added metrics:
    • broken_wikilink — [[link]] references that don't resolve to any page in wiki/ (= orphan link)
    • source_sha256_duplicate — pages sharing the same source_sha256: frontmatter (= idempotent ingest broken or manual dup)
    • pages_warm_zone — pages with updated: between 7-30 days (= warm zone, between fresh and stale-30d)
    • page_count_by_type — breakdown by page type (concept / project / decision / source-summary / log / index / meta / その他)
    • summaries_growth_rate — wiki/sources/*-summary.md additions in last 7d / 30d, expressed as count/day
  • auto-lint LINT_PROMPT 6 → 4 観点 refactor — `scrip