@askdkc/kiokuko 0.1.3 → 0.1.5

package/README.ja.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 日本語 | [简体中文](README.zh-CN.md) | [한국어](README.ko.md)
 
-Kiokukoは、AIコーディングエージェント向けのモデル非依存な外部記憶です。npmでグローバルインストールすると、現在のOSユーザー用SQLiteデータベースに構造化された記憶を保存し、stdio MCP経由でCodex、OpenCode、Claude Codeにタスク準備とrecall/checkpointツールを提供します。
+Kiokukoは、AIコーディングエージェント向けのモデル非依存な外部記憶です。npmでグローバルインストールすると、現在のOSユーザー用SQLiteデータベースに構造化された記憶を保存し、native stdio MCP経由でCodex、OpenCode、Claude Code、Hermes Agentにタスク準備とrecall/checkpointツールを提供します。
 
 ## グローバルへのインストールと有効化
 
@@ -15,9 +15,11 @@ kiokuko setup
 
 npmパッケージ名は`@askdkc/kiokuko`ですが、インストールされるCLIコマンド名は引き続き`kiokuko`です。
 
-セットアップ後にCodex、OpenCode、Claude Codeを再起動してください。それ以降は、各クライアントのグローバル指示が重要な作業の前後にKiokukoを呼び出すようエージェントへ指示し、必要になるとグローバル設定から`kiokuko mcp`が起動されます。
+セットアップ後にCodex、OpenCode、Claude Code、Hermes Agentを再起動してください。Hermesは`/reload-mcp`でも再読み込みでき、`hermes mcp test kiokuko`でスモークテストできます。Hermesは有効なプロファイルのnative stdio MCPだけを使い、グローバル指示ファイル、Hermes plugin、hookは作成しません。
 
-`setup`は明示的に実行する冪等な処理です。npmの`postinstall`がAIクライアントの設定を変更することはありません。既存のTOML/JSON/JSONC設定、コメント、指示内容、改行コード、ファイルモードを維持し、Kiokukoは管理対象セクションだけを更新します。
+`setup`は明示的に実行する冪等な処理です。npmの`postinstall`がAIクライアントの設定を変更することはありません。既存のTOML/JSON/JSONC/YAML設定、コメント、指示内容、改行コード、ファイルモードを維持し、Kiokukoは管理対象セクションだけを更新します。
+
+既存データベースに未適用のマイグレーションがある場合、setupは先に現在のユーザー用データディレクトリ内の`backups/`へバックアップを作成し、整合性を検査します。現在のKiokukoより新しいバージョンで更新されたデータベースは変更せず拒否します。
 
 ```bash
 # 書き込まずに変更対象ファイルと予定内容を確認
@@ -27,6 +29,7 @@ kiokuko setup --dry-run --json
 kiokuko setup --clients codex
 kiokuko setup --clients opencode
 kiokuko setup --clients claude
+kiokuko setup --clients hermes
 
 # クライアントプロセスがnpmのPATHを継承しない場合は絶対パスを指定
 kiokuko setup --command /absolute/path/to/kiokuko
@@ -34,13 +37,16 @@ kiokuko setup --command /absolute/path/to/kiokuko
 
 セットアップ対象は次のとおりです。
 
-| クライアント | MCP設定 | グローバル指示 |
-|---|---|---|
-| Codex | `$CODEX_HOME/config.toml`または`~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md`または`~/.codex/AGENTS.md` |
-| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json`または`~/.config/opencode/opencode.json` | 同じディレクトリの`AGENTS.md` |
-| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json`または`~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md`または`~/.claude/CLAUDE.md` |
+| クライアント | MCP設定 | グローバル指示 | 実行時ガード |
+|---|---|---|---|
+| Codex | `$CODEX_HOME/config.toml`または`~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md`または`~/.codex/AGENTS.md` | — |
+| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json`または`~/.config/opencode/opencode.json` | 同じディレクトリの`AGENTS.md` | `plugins/kiokuko-loop-guard.js` |
+| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json`または`~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md`または`~/.claude/CLAUDE.md` | — |
+| Hermes Agent | 有効なプロファイルの`config.yaml`（`$HERMES_HOME`、`$HOME/.hermes`、またはWindowsの`%LOCALAPPDATA%/hermes`） | なし | なし |
+
+Hermesの設定はプロファイル単位です。`mcp_servers.kiokuko`に`command: kiokuko`と`args: [mcp]`を登録します。Hermesの組み込みmemoryとskillsはKiokukoとは別です。モデルがMCP tool descriptionを使うかどうかはbest effortです。
 
-OpenCodeの`opencode.jsonc`がすでに存在する場合、Kiokukoはコメントを維持したままそのファイルを更新します。CodexにKiokuko管理外の`[mcp_servers.kiokuko]`テーブルが存在する場合、上書き対象を推測せずセットアップを停止します。
+OpenCodeの`opencode.jsonc`がすでに存在する場合、Kiokukoはコメントを維持したままそのファイルを更新します。CodexにKiokuko管理外の`[mcp_servers.kiokuko]`テーブルが存在する場合、上書き対象を推測せずセットアップを停止します。管理対象のOpenCodeガードは、可視エージェントを12 stepに制限し、1ユーザー要求につき`task_prepare`と`memory_checkpoint`を各1回までにし、チェックポイント後のツール利用を閉じ、同一呼び出しまたは読み取り専用の探索結果が3回続いた後の再実行を停止します。カウンターとフィンガープリントはプロセスメモリにだけ保持します。
 
 ## 記憶のスコープ
 
@@ -53,12 +59,12 @@ OpenCodeの`opencode.jsonc`がすでに存在する場合、Kiokukoはコメン
 
 MCPの公開インターフェースは意図的に小さくしています。
 
-- `task_prepare`: Akinator形式の取り込み、上限付きの記憶・参照検索、現在のクライアントから渡されたSKILL/MCPツール名との照合を一度に行います。
+- `task_prepare`: 1ユーザー要求につき1回だけ、Akinator形式の取り込み、上限付きの記憶・参照検索、現在のクライアントから渡されたSKILL/MCPツール名との照合を行います。
 - `task_answer`: ユーザーの依頼または確認済みのリポジトリ情報に根拠がある回答だけで、取り込みを続行します。
 - `memory_recall`: 上限付きのproject/globalコンテキストを読み取ります。結果には常にuntrustedマークが付きます。
-- `memory_checkpoint`: 上限付きの永続的な記憶を`candidate`かつ`untrusted`として保存します。シークレットに見える内容は拒否されます。
+- `memory_checkpoint`: ユーザー要求の最後に1回だけ、上限付きの永続的な記憶を`candidate`かつ`untrusted`として保存します。シークレットに見える内容は拒否されます。
 
-これは指示による自動利用であり、プロンプトの横取りではありません。Codex、OpenCode、Claude Codeが特定のターンでツールを呼ばない可能性は残ります。Kiokukoはフックをインストールせず、会話全文を取得せず、取得したSKILLを自動インストールせず、記憶を暗黙にverifiedへ昇格させません。
+これは指示による自動利用であり、プロンプトの横取りではありません。Codex、OpenCode、Claude Code、Hermes Agentが特定のターンでツールを呼ばない可能性は残ります。Hermesでの自動利用・モデル利用はMCP tool descriptionによるbest effortです。Hermesの組み込みmemoryとskillsは分離されたままです。KiokukoはHermes用のグローバル指示ファイル、plugin、hookを作成せず、会話全文を取得せず、取得したSKILLを自動インストールせず、記憶を暗黙にverifiedへ昇格させません。OpenCodeセットアップは上記の限定的なローカルループガードだけをインストールします。
 
 ## 開発
 
@@ -81,7 +87,7 @@ npm exec -- tsx src/bin/kiokuko.ts mcp
 
 ## Akinator形式の知識取り込み
 
-重要な作業では、セットアップ済みのエージェント指示が`task_prepare`を呼び出します。このツールはタスク種別、対象、成功条件など、不足している価値の高い項目だけを質問し、クエリとBot用途タグからローカル記憶を選択します。クライアントが現在利用可能なSKILLとMCPツールの名前を渡した場合は、必要な機能を照合し、`available`、`missing`、`unknown`を区別して返します。この一覧は一時的にだけ使用され、保存されません。CLIの`guide`コマンドでも同じ取り込みを手動実行できます。
+重要な作業では、セットアップ済みのエージェント指示が`task_prepare`を呼び出します。このツールはタスク種別、対象、成功条件など、不足している価値の高い項目だけを質問し、クエリと役割・用途タグからローカル記憶を選択します。クライアントが現在利用可能なSKILLとMCPツールの名前を渡した場合は、必要な機能を照合し、`available`、`missing`、`unknown`を区別して返します。この一覧は一時的にだけ使用され、保存されません。CLIの`guide`コマンドでも同じ取り込みを手動実行できます。
 
 ```bash
 kiokuko guide start "Implement the API change and add tests" \
@@ -103,7 +109,7 @@ capability一覧の省略は0件ではなく「不明」として扱い、フォ
 
 ## ローカルWeb UI
 
-ループバック専用HTTPサーバーを起動すると、Bot用途、記憶タイプ、横断タグで記憶エントリを閲覧し、ブラウザからcandidateエントリを編集できます。
+ループバック専用HTTPサーバーを起動すると、役割・用途、記憶タイプ、横断タグで記憶エントリを閲覧し、ブラウザからcandidateエントリを編集できます。
 
 ```bash
 kiokuko web

package/README.ko.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | 한국어
 
-Kiokuko는 AI 코딩 에이전트를 위한 모델 독립적인 외부 메모리 도구입니다. npm으로 한 번 전역 설치하면 현재 운영체제 사용자의 SQLite 데이터베이스에 구조화된 메모리를 저장하고, stdio MCP를 통해 Codex, OpenCode 및 Claude Code에 작업 준비와 recall/checkpoint 도구를 제공합니다.
+Kiokuko는 AI 코딩 에이전트를 위한 모델 독립적인 외부 메모리 도구입니다. npm으로 한 번 전역 설치하면 현재 운영체제 사용자의 SQLite 데이터베이스에 구조화된 메모리를 저장하고, native stdio MCP를 통해 Codex, OpenCode, Claude Code 및 Hermes Agent에 작업 준비와 recall/checkpoint 도구를 제공합니다.
 
 ## 전역 설치 및 활성화
 
@@ -15,9 +15,11 @@ kiokuko setup
 
 npm 패키지 이름은 `@askdkc/kiokuko`이지만 설치되는 CLI 명령 이름은 계속 `kiokuko`입니다.
 
-설정 후 Codex, OpenCode 및 Claude Code를 다시 시작하십시오. 이후 각 클라이언트의 전역 지침이 중요한 작업 전과 지속성 있는 작업 후에 Kiokuko를 호출하도록 에이전트에 지시하며, 도구가 필요할 때 전역 설정에서 `kiokuko mcp`를 시작합니다.
+설정 후 Codex, OpenCode, Claude Code 및 Hermes Agent를 다시 시작하십시오. Hermes는 `/reload-mcp`로 다시 불러올 수도 있으며 `hermes mcp test kiokuko`로 smoke test할 수 있습니다. Hermes는 유효한 profile의 native stdio MCP만 사용하며 전역 지침 파일, Hermes plugin 또는 hook을 만들지 않습니다.
 
-`setup`은 명시적으로 실행하는 멱등 작업입니다. npm `postinstall`은 AI 클라이언트 설정을 수정하지 않습니다. 기존 TOML/JSONC 설정, 주석, 지침 내용, 줄바꿈 형식 및 파일 모드는 유지되며 Kiokuko는 관리 구역만 수정합니다.
+`setup`은 명시적으로 실행하는 멱등 작업입니다. npm `postinstall`은 AI 클라이언트 설정을 수정하지 않습니다. 기존 TOML/JSON/JSONC/YAML 설정, 주석, 지침 내용, 줄바꿈 형식 및 파일 모드는 유지되며 Kiokuko는 관리 구역만 수정합니다.
+
+기존 데이터베이스에 적용되지 않은 마이그레이션이 있으면 setup은 먼저 현재 사용자의 데이터 디렉터리 안에 있는 `backups/`에 백업을 만들고 무결성을 검사합니다. 현재 Kiokuko보다 새로운 버전에서 기록된 데이터베이스는 변경하지 않고 거부합니다.
 
 ```bash
 # 아무것도 쓰지 않고 정확한 대상 파일과 예정된 변경 사항 확인
@@ -27,6 +29,7 @@ kiokuko setup --dry-run --json
 kiokuko setup --clients codex
 kiokuko setup --clients opencode
 kiokuko setup --clients claude
+kiokuko setup --clients hermes
 
 # 클라이언트 프로세스가 npm의 PATH를 상속하지 않는 경우 절대 경로 사용
 kiokuko setup --command /absolute/path/to/kiokuko
@@ -34,13 +37,16 @@ kiokuko setup --command /absolute/path/to/kiokuko
 
 설정 대상은 다음과 같습니다.
 
-| 클라이언트 | MCP 설정 | 전역 지침 |
-|---|---|---|
-| Codex | `$CODEX_HOME/config.toml` 또는 `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` 또는 `~/.codex/AGENTS.md` |
-| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json` 또는 `~/.config/opencode/opencode.json` | 같은 디렉터리의 `AGENTS.md` |
-| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json` 또는 `~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md` 또는 `~/.claude/CLAUDE.md` |
+| 클라이언트 | MCP 설정 | 전역 지침 | 런타임 가드 |
+|---|---|---|---|
+| Codex | `$CODEX_HOME/config.toml` 또는 `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` 또는 `~/.codex/AGENTS.md` | — |
+| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json` 또는 `~/.config/opencode/opencode.json` | 같은 디렉터리의 `AGENTS.md` | `plugins/kiokuko-loop-guard.js` |
+| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json` 또는 `~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md` 또는 `~/.claude/CLAUDE.md` | — |
+| Hermes Agent | 유효한 profile의 `config.yaml` (`$HERMES_HOME`, `$HOME/.hermes` 또는 `%LOCALAPPDATA%/hermes`) | 없음 | 없음 |
+
+Hermes 설정은 profile 범위의 native stdio MCP입니다. `mcp_servers.kiokuko`에 `command: kiokuko`, `args: [mcp]`를 등록합니다. Hermes의 내장 memory와 skills는 Kiokuko와 별개이며, 모델이 MCP tool descriptions를 사용할지는 best effort입니다.
 
-OpenCode의 `opencode.jsonc`가 이미 있으면 Kiokuko는 주석을 유지하면서 해당 파일을 수정합니다. Codex에 Kiokuko가 관리하지 않는 `[mcp_servers.kiokuko]` 테이블이 이미 있으면 어떤 설정을 덮어쓸지 추측하지 않고 설정을 중단합니다.
+OpenCode의 `opencode.jsonc`가 이미 있으면 Kiokuko는 주석을 유지하면서 해당 파일을 수정합니다. Codex에 Kiokuko가 관리하지 않는 `[mcp_servers.kiokuko]` 테이블이 이미 있으면 어떤 설정을 덮어쓸지 추측하지 않고 설정을 중단합니다. 관리되는 OpenCode 가드는 보이는 에이전트를 12 step으로 제한하고, 사용자 요청마다 `task_prepare`와 `memory_checkpoint`를 각각 한 번만 허용하며, 체크포인트 후 도구 단계를 닫고, 동일 호출 또는 읽기 전용 탐색 결과가 세 번 연속 나온 뒤의 재실행을 차단합니다. 카운터와 지문은 프로세스 메모리에만 보관됩니다.
 
 ## 메모리 범위
 
@@ -53,12 +59,12 @@ OpenCode의 `opencode.jsonc`가 이미 있으면 Kiokuko는 주석을 유지하
 
 MCP 인터페이스는 의도적으로 작게 유지됩니다.
 
-- `task_prepare`: Akinator 방식 수집, 제한된 메모리/참조 검색, 현재 클라이언트가 제공한 스킬 및 MCP 도구 이름과의 매칭을 수행합니다.
+- `task_prepare`: 사용자 요청마다 한 번만 Akinator 방식 수집, 제한된 메모리/참조 검색, 현재 클라이언트가 제공한 스킬 및 MCP 도구 이름과의 매칭을 수행합니다.
 - `task_answer`: 사용자 요청 또는 검증된 저장소 근거로 뒷받침되는 답변만 사용해 수집을 계속합니다.
 - `memory_recall`: 제한된 project/global 컨텍스트를 읽으며 항상 untrusted로 표시합니다.
-- `memory_checkpoint`: 제한된 지속성 항목을 `candidate` 및 `untrusted`로 저장합니다. 비밀 정보로 보이는 내용은 거부됩니다.
+- `memory_checkpoint`: 사용자 요청 마지막에 한 번만 제한된 지속성 항목을 `candidate` 및 `untrusted`로 저장합니다. 비밀 정보로 보이는 내용은 거부됩니다.
 
-이는 지침에 기반한 자동 사용이며 프롬프트 가로채기가 아닙니다. Codex, OpenCode 및 Claude Code가 특정 턴에서 도구를 호출하지 않을 가능성은 여전히 있습니다. Kiokuko는 훅을 설치하거나 전체 대화를 수집하거나 가져온 스킬을 자동 설치하거나 메모리를 조용히 verified 상태로 승격하지 않습니다.
+이는 지침에 기반한 자동 사용이며 프롬프트 가로채기가 아닙니다. Codex, OpenCode, Claude Code 및 Hermes Agent가 특정 턴에서 도구를 호출하지 않을 가능성은 여전히 있습니다. Hermes의 자동/모델 사용은 MCP tool descriptions에 따른 best effort입니다. Hermes의 내장 memory와 skills는 분리되어 있습니다. Kiokuko는 Hermes 전역 지침 파일, plugin 또는 hook을 만들지 않으며 전체 대화를 수집하거나 가져온 스킬을 자동 설치하거나 메모리를 조용히 verified 상태로 승격하지 않습니다. OpenCode 설정은 위에서 설명한 제한된 로컬 루프 가드만 설치합니다.
 
 ## 개발
 
@@ -81,7 +87,7 @@ npm exec -- tsx src/bin/kiokuko.ts mcp
 
 ## Akinator 방식 지식 수집
 
-중요한 작업에서는 설정된 에이전트 지침이 `task_prepare`를 호출합니다. 이 도구는 작업 유형, 대상 및 성공 조건과 같이 누락된 고가치 필드만 질문한 뒤 쿼리와 Bot 목적 태그를 사용하여 로컬 메모리를 선택합니다. 클라이언트가 현재 사용 가능한 스킬과 MCP 도구 이름을 제공하면 필요한 기능을 매칭하고 `available`, `missing`, `unknown`을 구분해 반환합니다. 이 목록은 일시적으로만 사용되며 저장되지 않습니다. CLI의 `guide` 명령으로 같은 수집을 수동 실행할 수 있습니다.
+중요한 작업에서는 설정된 에이전트 지침이 `task_prepare`를 호출합니다. 이 도구는 작업 유형, 대상 및 성공 조건과 같이 누락된 고가치 필드만 질문한 뒤 쿼리와 역할과 용도 태그를 사용하여 로컬 메모리를 선택합니다. 클라이언트가 현재 사용 가능한 스킬과 MCP 도구 이름을 제공하면 필요한 기능을 매칭하고 `available`, `missing`, `unknown`을 구분해 반환합니다. 이 목록은 일시적으로만 사용되며 저장되지 않습니다. CLI의 `guide` 명령으로 같은 수집을 수동 실행할 수 있습니다.
 
 ```bash
 kiokuko guide start "Implement the API change and add tests" \
@@ -103,7 +109,7 @@ capability 목록 생략은 0개가 아니라 "알 수 없음"으로 처리되
 
 ## 로컬 Web UI
 
-루프백 전용 HTTP 서버를 시작하면 Bot 목적, 메모리 유형 및 교차 태그별로 메모리 항목을 탐색하고 브라우저에서 candidate 항목을 편집할 수 있습니다.
+루프백 전용 HTTP 서버를 시작하면 역할과 용도, 메모리 유형 및 교차 태그별로 메모리 항목을 탐색하고 브라우저에서 candidate 항목을 편집할 수 있습니다.
 
 ```bash
 kiokuko web

package/README.md

@@ -5,7 +5,7 @@ English | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | [한국
 Kiokuko(記憶庫) is model-agnostic external memory for AI coding agents. One global npm
 installation stores structured memory in the current user's SQLite database and
 exposes guided task preparation plus recall/checkpoint tools to Codex, OpenCode,
-and Claude Code over stdio MCP.
+Claude Code, and Hermes Agent over native stdio MCP.
 
 The name **Kiokuko** comes from the Japanese **記憶庫**: **記憶** means
 "memory," and **庫** means "storehouse," so the name describes a place for
@@ -23,14 +23,21 @@ kiokuko setup
 The npm package name is `@askdkc/kiokuko`; the installed CLI command remains
 `kiokuko`.
 
-Restart Codex, OpenCode, and Claude Code after setup. From then on, their global
-instructions tell the agent to call Kiokuko before non-trivial work and after
-durable work, and their global config starts `kiokuko mcp` when needed.
+Restart Codex, OpenCode, Claude Code, and Hermes Agent after setup. Hermes can also
+reload the MCP registry with `/reload-mcp`; smoke-test the active Hermes profile
+with `hermes mcp test kiokuko`. Codex, OpenCode, and Claude Code use their existing
+instruction surfaces to request Kiokuko before non-trivial work and after durable
+work. Hermes uses its profile-scoped native MCP registration only: Kiokuko does not
+create a global instruction file, Hermes plugin, or Hermes hook.
 
 `setup` is explicit and idempotent. npm `postinstall` never edits AI-client
-configuration. Existing TOML/JSON/JSONC settings, comments, instruction content,
-line endings, and file modes are preserved; Kiokuko owns only its managed
-sections.
+configuration. Existing TOML/JSON/JSONC/YAML settings, comments, instruction content, line endings,
+and file modes are preserved; Kiokuko owns only its managed sections.
+
+When an existing database has pending migrations, setup first creates and
+integrity-checks a backup in the adjacent `backups/` directory under the current
+user's data directory. A
+database written by a newer Kiokuko version is rejected without modification.
 
 ```bash
 # Preview exact target files without writing anything
@@ -40,6 +47,7 @@ kiokuko setup --dry-run --json
 kiokuko setup --clients codex
 kiokuko setup --clients opencode
 kiokuko setup --clients claude
+kiokuko setup --clients hermes
 
 # Use an absolute executable path if the client process does not inherit npm's PATH
 kiokuko setup --command /absolute/path/to/kiokuko
@@ -47,16 +55,23 @@ kiokuko setup --command /absolute/path/to/kiokuko
 
 The setup targets are:
 
-| Client | MCP config | Global instructions |
-|---|---|---|
-| Codex | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md` |
-| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json` | the adjacent `AGENTS.md` |
-| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json` or `~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md` or `~/.claude/CLAUDE.md` |
+| Client | MCP config | Global instructions | Runtime guard |
+|---|---|---|---|
+| Codex | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md` | — |
+| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json` | the adjacent `AGENTS.md` | `plugins/kiokuko-loop-guard.js` |
+| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json` or `~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md` or `~/.claude/CLAUDE.md` | — |
+| Hermes Agent | effective profile `config.yaml` under `$HERMES_HOME`, `$HOME/.hermes`, or `%LOCALAPPDATA%/hermes` | none | none |
+
+Hermes is configured as a profile-scoped native stdio MCP server with `command: kiokuko` and `args: [mcp]`. `setup` follows a valid sticky `active_profile` when `HERMES_HOME` is a root, and never silently falls back from a missing named profile.
 
 If an OpenCode `opencode.jsonc` already exists, Kiokuko updates that file and
 preserves comments. If Codex already has an unmanaged
 `[mcp_servers.kiokuko]` table, setup refuses to guess which configuration to
-overwrite.
+overwrite. The managed OpenCode guard caps visible agents at 12 steps, permits
+`task_prepare` and `memory_checkpoint` only once per user request, closes tool
+use after a checkpoint, and stops repeated calls or read-only discovery results
+after three unchanged iterations. It keeps its counters and fingerprints in
+process memory only.
 
 ## Memory scope
 
@@ -73,19 +88,23 @@ full-database search:
 
 The MCP surface is deliberately small:
 
-- `task_prepare`: run the Akinator intake, recall bounded memory and references,
+- `task_prepare`: once per user request, run the Akinator intake, recall bounded memory and references,
   and match required skills/MCP tools against the capability names supplied by
   the current client.
 - `task_answer`: continue an intake only with an answer grounded in the user
   request or verified repository evidence.
 - `memory_recall`: read bounded project/global context, always marked untrusted.
-- `memory_checkpoint`: store bounded durable entries as `candidate` and
+- `memory_checkpoint`: once at the end of a user request, store bounded durable entries as `candidate` and
   `untrusted`; secret-like content is rejected.
 
-This is instruction-driven automatic use, not prompt interception. Codex,
-OpenCode, and Claude Code can still choose not to call a tool on a particular
-turn. Kiokuko does not install hooks, capture full transcripts, install fetched
-skills, or silently promote memory to verified status.
+This is instruction-driven automatic use for clients with instruction surfaces,
+not prompt interception. Codex, OpenCode, Claude Code, and Hermes Agent can still
+choose not to call a tool on a particular turn; Hermes automatic/model use is best
+effort from MCP tool descriptions. Hermes's built-in memory and skills
+remain separate. Kiokuko does not capture full transcripts, install fetched skills,
+create a Hermes global instruction file, or silently promote memory to verified
+status. The OpenCode setup installs only the bounded local loop guard described
+above.
 
 ## Development
 
@@ -112,7 +131,7 @@ requires it.
 
 For non-trivial work, the installed agent instructions call `task_prepare`.
 That tool asks only for missing high-value fields such as the task type, target,
-and success condition, then selects local memory by query and Bot-purpose tags.
+and success condition, then selects local memory by query and role and purpose tags.
 If the client supplies its currently available skill and MCP-tool names, the
 result also identifies matching capabilities and clearly distinguishes
 available, missing, and unknown skills. The catalog is ephemeral and is not
@@ -146,7 +165,7 @@ executed as a command. Repeated sync is content-hash idempotent.
 
 ## Local web UI
 
-Start a loopback-only HTTP server to browse memory entries by Bot purpose,
+Start a loopback-only HTTP server to browse memory entries by role and purpose,
 memory type, and cross-cutting tags, and edit candidate entries from the browser:
 
 ```bash

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [日本語](README.ja.md) | 简体中文 | [한국어](README.ko.md)
 
-Kiokuko 是面向 AI 编程智能体、与模型无关的外部记忆工具。通过一次 npm 全局安装，它会将结构化记忆保存在当前操作系统用户的 SQLite 数据库中，并通过 stdio MCP 向 Codex、OpenCode 和 Claude Code 提供任务准备及 recall/checkpoint 工具。
+Kiokuko 是面向 AI 编程智能体、与模型无关的外部记忆工具。通过一次 npm 全局安装，它会将结构化记忆保存在当前操作系统用户的 SQLite 数据库中，并通过 native stdio MCP 向 Codex、OpenCode、Claude Code 和 Hermes Agent 提供任务准备及 recall/checkpoint 工具。
 
 ## 全局安装与启用
 
@@ -15,9 +15,11 @@ kiokuko setup
 
 npm 包名是 `@askdkc/kiokuko`，安装后的 CLI 命令名仍然是 `kiokuko`。
 
-设置完成后，请重启 Codex、OpenCode 和 Claude Code。此后，各客户端的全局指令会要求智能体在处理重要工作之前调用 Kiokuko，并在产生持久性成果后写入检查点；需要工具时，全局配置会启动 `kiokuko mcp`。
+设置完成后，请重启 Codex、OpenCode、Claude Code 和 Hermes Agent。Hermes 也可以使用 `/reload-mcp` 重新加载，并用 `hermes mcp test kiokuko` 做 smoke test。Hermes 只使用有效 profile 中的原生 stdio MCP；Kiokuko 不会创建全局指令文件、Hermes plugin 或 hook。
 
-`setup` 是显式且幂等的操作。npm 的 `postinstall` 永远不会修改 AI 客户端配置。现有 TOML/JSONC 设置、注释、指令内容、换行符和文件权限都会保留；Kiokuko 只管理自己的区块。
+`setup` 是显式且幂等的操作。npm 的 `postinstall` 永远不会修改 AI 客户端配置。现有 TOML/JSON/JSONC/YAML 设置、注释、指令内容、换行符和文件权限都会保留；Kiokuko 只管理自己的区块。
+
+如果现有数据库存在尚未应用的迁移，setup 会先在当前用户数据目录下的 `backups/` 中创建备份并执行完整性检查。由更新版本 Kiokuko 写入的数据库会被拒绝，且不会受到修改。
 
 ```bash
 # 不写入任何内容，预览确切的目标文件和计划变更
@@ -27,6 +29,7 @@ kiokuko setup --dry-run --json
 kiokuko setup --clients codex
 kiokuko setup --clients opencode
 kiokuko setup --clients claude
+kiokuko setup --clients hermes
 
 # 如果客户端进程未继承 npm 的 PATH，请使用可执行文件绝对路径
 kiokuko setup --command /absolute/path/to/kiokuko
@@ -34,13 +37,16 @@ kiokuko setup --command /absolute/path/to/kiokuko
 
 设置目标如下：
 
-| 客户端 | MCP 配置 | 全局指令 |
-|---|---|---|
-| Codex | `$CODEX_HOME/config.toml` 或 `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` 或 `~/.codex/AGENTS.md` |
-| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json` 或 `~/.config/opencode/opencode.json` | 同目录下的 `AGENTS.md` |
-| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json` 或 `~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md` 或 `~/.claude/CLAUDE.md` |
+| 客户端 | MCP 配置 | 全局指令 | 运行时防护 |
+|---|---|---|---|
+| Codex | `$CODEX_HOME/config.toml` 或 `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` 或 `~/.codex/AGENTS.md` | — |
+| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json` 或 `~/.config/opencode/opencode.json` | 同目录下的 `AGENTS.md` | `plugins/kiokuko-loop-guard.js` |
+| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json` 或 `~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md` 或 `~/.claude/CLAUDE.md` | — |
+| Hermes Agent | 有效 profile 的 `config.yaml`（`$HERMES_HOME`、`$HOME/.hermes` 或 `%LOCALAPPDATA%/hermes`） | 无 | 无 |
+
+Hermes 配置是 profile 级别的 native stdio MCP，注册 `mcp_servers.kiokuko`，其中 `command: kiokuko`、`args: [mcp]`。Hermes 内置 memory 和 skills 与 Kiokuko 分离；模型是否使用这些 MCP 工具取决于 MCP tool descriptions，属于 best effort。
 
-如果 OpenCode 的 `opencode.jsonc` 已存在，Kiokuko 会保留注释并更新该文件。如果 Codex 中已存在不受 Kiokuko 管理的 `[mcp_servers.kiokuko]` 表，设置程序不会猜测应该覆盖哪项配置，而是直接停止。
+如果 OpenCode 的 `opencode.jsonc` 已存在，Kiokuko 会保留注释并更新该文件。如果 Codex 中已存在不受 Kiokuko 管理的 `[mcp_servers.kiokuko]` 表，设置程序不会猜测应该覆盖哪项配置，而是直接停止。受管理的 OpenCode 防护会把可见智能体限制为 12 个 step；每个用户请求最多调用一次 `task_prepare` 和一次 `memory_checkpoint`；检查点完成后关闭工具阶段；连续三次出现相同调用或相同的只读检索结果后阻止再次执行。计数器和指纹仅保存在进程内存中。
 
 ## 记忆作用域
 
@@ -53,12 +59,12 @@ kiokuko setup --command /absolute/path/to/kiokuko
 
 MCP 接口被有意保持为最小范围：
 
-- `task_prepare`：执行 Akinator 式采集、有界记忆/参考检索，并与当前客户端提供的技能和 MCP 工具名称进行匹配。
+- `task_prepare`：每个用户请求仅执行一次 Akinator 式采集、有界记忆/参考检索，并与当前客户端提供的技能和 MCP 工具名称进行匹配。
 - `task_answer`：仅使用用户请求或已验证仓库证据支持的答案继续采集。
 - `memory_recall`：读取有界的 project/global 上下文，并始终标记为 untrusted。
-- `memory_checkpoint`：将有界的持久性条目保存为 `candidate` 和 `untrusted`；疑似密钥的内容会被拒绝。
+- `memory_checkpoint`：在用户请求结束时仅执行一次，将有界的持久性条目保存为 `candidate` 和 `untrusted`；疑似密钥的内容会被拒绝。
 
-这种自动使用由指令驱动，并不会拦截提示词。Codex、OpenCode 和 Claude Code 仍可能决定在某个回合不调用工具。Kiokuko 不会安装钩子、捕获完整对话、自动安装获取到的技能，也不会静默地将记忆提升为 verified 状态。
+这种自动使用由指令驱动，并不会拦截提示词。Codex、OpenCode、Claude Code 和 Hermes Agent 仍可能决定在某个回合不调用工具；Hermes 的自动/模型使用是基于 MCP tool descriptions 的 best effort。Hermes 内置 memory 和 skills 保持独立。Kiokuko 不会创建 Hermes 全局指令文件、plugin 或 hook，不会捕获完整对话、自动安装获取到的技能，也不会静默地将记忆提升为 verified 状态。OpenCode 设置只会安装上述受限的本地循环防护。
 
 ## 开发
 
@@ -81,7 +87,7 @@ npm exec -- tsx src/bin/kiokuko.ts mcp
 
 ## Akinator 式知识采集
 
-对于重要工作，设置好的智能体指令会调用 `task_prepare`。该工具只询问任务类型、目标和成功条件等缺失的高价值字段，再根据查询和 Bot 用途标签选择本地记忆。如果客户端提供当前可用的技能和 MCP 工具名称，结果还会匹配所需能力，并区分 `available`、`missing` 和 `unknown`；该目录仅临时使用，不会存储。CLI 的 `guide` 命令可手动执行同一流程：
+对于重要工作，设置好的智能体指令会调用 `task_prepare`。该工具只询问任务类型、目标和成功条件等缺失的高价值字段，再根据查询和角色与用途标签选择本地记忆。如果客户端提供当前可用的技能和 MCP 工具名称，结果还会匹配所需能力，并区分 `available`、`missing` 和 `unknown`；该目录仅临时使用，不会存储。CLI 的 `guide` 命令可手动执行同一流程：
 
 ```bash
 kiokuko guide start "Implement the API change and add tests" \
@@ -103,7 +109,7 @@ kiokuko guide context <session-id> --workspace <workspace> --json
 
 ## 本地 Web UI
 
-启动仅限回环地址的 HTTP 服务器，即可按 Bot 用途、记忆类型和跨类别标签浏览记忆条目，并在浏览器中编辑 candidate 条目：
+启动仅限回环地址的 HTTP 服务器，即可按角色与用途、记忆类型和跨类别标签浏览记忆条目，并在浏览器中编辑 candidate 条目：
 
 ```bash
 kiokuko web

package/dist/agent-file/render.d.ts

@@ -1,4 +1,4 @@
-export declare const AGENT_TEMPLATE_VERSION = 4;
+export declare const AGENT_TEMPLATE_VERSION = 5;
 export interface AgentTemplateValues {
     repositoryId: string;
     workspace: string;

package/dist/agent-file/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/agent-file/render.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,GAAG,qBAAqB,GAAG,0BAA0B,CAAC;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;CAC7C;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAoCtE;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,CAG5G"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/agent-file/render.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,GAAG,qBAAqB,GAAG,0BAA0B,CAAC;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;CAC7C;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAsCtE;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,CAG5G"}

package/dist/agent-file/render.js

@@ -1,5 +1,5 @@
 import { BEGIN_MARKER, END_MARKER, upsertManagedBlock } from './managed-block.js';
-export const AGENT_TEMPLATE_VERSION = 4;
+export const AGENT_TEMPLATE_VERSION = 5;
 export function renderManagedBlock(values) {
     const version = values.templateVersion ?? AGENT_TEMPLATE_VERSION;
     return [
@@ -19,7 +19,7 @@ export function renderManagedBlock(values) {
         '',
         '### Before non-trivial work',
         '',
-        '1. Call `task_prepare` with the actual task, current working directory, and only profile hints supported by the user request or repository evidence.',
+        '1. Call `task_prepare` at most once for the current user request, with the actual task, current working directory, and only profile hints supported by the user request or repository evidence. Reuse its result for the rest of the request; never call it again after `memory_checkpoint`.',
         '2. Include the complete names and short descriptions of skills and MCP tools available in the current client. Pass an empty catalog only when none are available; omit it when availability is unknown. The catalog is not stored.',
         '3. Kiokuko may consult `https://github.com/mattpocock/skills` only when the supplied catalog contains zero skills. If any skill is available, or the catalog is unknown, external skill fallback stays disabled.',
         '4. If the intake needs an answer, call `task_answer` with the same capability catalog only when current evidence supports the answer; otherwise ask the user the returned question.',
@@ -28,9 +28,11 @@ export function renderManagedBlock(values) {
         '',
         '### After substantial work',
         '',
-        '1. Call `memory_checkpoint` only for concise, durable, verified facts, decisions, lessons, preferences, or references that will help future work.',
-        '2. Keep repository knowledge in project scope. Use global scope only for knowledge that truly applies across projects.',
-        '3. Checkpoints remain untrusted candidates until explicitly reviewed; never auto-promote them to verified.',
+        '1. Call `memory_checkpoint` at most once for the current user request, only for concise, durable, verified facts, decisions, lessons, preferences, or references that will help future work.',
+        '2. Treat a completed `memory_checkpoint` as terminal for tool use: do not call it or any other tool again; immediately return the final response.',
+        '3. Do not retry an unchanged tool call after it fails or returns no new information. Summarize the blocker or current result and stop tool use.',
+        '4. Keep repository knowledge in project scope. Use global scope only for knowledge that truly applies across projects.',
+        '5. Checkpoints remain untrusted candidates until explicitly reviewed; never auto-promote them to verified.',
         '',
         'If the MCP tools are unavailable, report the failure briefly and continue from repository evidence. Never store passwords, API keys, access tokens, private keys, session cookies, auth headers, provider credentials, client secrets, private user data, full transcripts, or capability catalogs.',
         '',

package/dist/agent-file/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/agent-file/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAElF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAcxC,MAAM,UAAU,kBAAkB,CAAC,MAA2B;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,eAAe,IAAI,sBAAsB,CAAC;IACjE,OAAO;QACL,YAAY;QACZ,kCAAkC,OAAO,MAAM;QAC/C,8EAA8E;QAC9E,EAAE;QACF,4BAA4B;QAC5B,EAAE;QACF,8DAA8D;QAC9D,EAAE;QACF,oBAAoB,GAAG,MAAM,CAAC,YAAY,GAAG,GAAG;QAChD,gBAAgB,GAAG,MAAM,CAAC,SAAS,GAAG,GAAG;QACzC,wBAAwB,GAAG,MAAM,CAAC,UAAU,GAAG,GAAG;QAClD,EAAE;QACF,kLAAkL;QAClL,EAAE;QACF,6BAA6B;QAC7B,EAAE;QACF,sJAAsJ;QACtJ,oOAAoO;QACpO,kNAAkN;QAClN,qLAAqL;QACrL,kMAAkM;QAClM,4IAA4I;QAC5I,EAAE;QACF,4BAA4B;QAC5B,EAAE;QACF,mJAAmJ;QACnJ,wHAAwH;QACxH,4GAA4G;QAC5G,EAAE;QACF,qSAAqS;QACrS,EAAE;QACF,UAAU;KACX,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAA4B,EAAE,MAA2B;IACvF,MAAM,MAAM,GAAG,kBAAkB,CAAC,QAAQ,IAAI,EAAE,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/agent-file/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAElF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAcxC,MAAM,UAAU,kBAAkB,CAAC,MAA2B;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,eAAe,IAAI,sBAAsB,CAAC;IACjE,OAAO;QACL,YAAY;QACZ,kCAAkC,OAAO,MAAM;QAC/C,8EAA8E;QAC9E,EAAE;QACF,4BAA4B;QAC5B,EAAE;QACF,8DAA8D;QAC9D,EAAE;QACF,oBAAoB,GAAG,MAAM,CAAC,YAAY,GAAG,GAAG;QAChD,gBAAgB,GAAG,MAAM,CAAC,SAAS,GAAG,GAAG;QACzC,wBAAwB,GAAG,MAAM,CAAC,UAAU,GAAG,GAAG;QAClD,EAAE;QACF,kLAAkL;QAClL,EAAE;QACF,6BAA6B;QAC7B,EAAE;QACF,8RAA8R;QAC9R,oOAAoO;QACpO,kNAAkN;QAClN,qLAAqL;QACrL,kMAAkM;QAClM,4IAA4I;QAC5I,EAAE;QACF,4BAA4B;QAC5B,EAAE;QACF,8LAA8L;QAC9L,mJAAmJ;QACnJ,iJAAiJ;QACjJ,wHAAwH;QACxH,4GAA4G;QAC5G,EAAE;QACF,qSAAqS;QACrS,EAAE;QACF,UAAU;KACX,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAA4B,EAAE,MAA2B;IACvF,MAAM,MAAM,GAAG,kBAAkB,CAAC,QAAQ,IAAI,EAAE,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;AAC5D,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAepD,OAAO,EAA0B,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAwB,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAoD1F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,wBAAwB,CAAC;CAC3C;AAuDD,wBAAgB,QAAQ,CAAC,YAAY,GAAE,eAAoB,GAAG,OAAO,CA6LpE;AAcD,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,EAAE,YAAY,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB/G"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAepD,OAAO,EAA0B,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAwB,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AA0D1F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,wBAAwB,CAAC;CAC3C;AAuDD,wBAAgB,QAAQ,CAAC,YAAY,GAAE,eAAoB,GAAG,OAAO,CA8LpE;AAcD,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,EAAE,YAAY,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB/G"}

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { Command, CommanderError } from 'commander';
 import { initializeDatabase } from './commands/init.js';
 import { useRepository } from './commands/use.js';
@@ -20,6 +21,11 @@ import { registerLedgerCommands } from './commands/ledger.js';
 import { answerAkinator, getAkinatorContext, startAkinator } from './akinator/orchestrator.js';
 import { parseSetupClients, setupGlobalClients } from './commands/setup.js';
 import { runMcpServer } from './mcp/server.js';
+const packageMetadata = createRequire(import.meta.url)('../package.json');
+if (typeof packageMetadata.version !== 'string' || packageMetadata.version.length === 0) {
+    throw new Error('Kiokuko package version is unavailable');
+}
+const packageVersion = packageMetadata.version;
 async function readJsonInput(filePath) {
     const text = filePath === '-' ? await new Promise((resolve, reject) => {
         let value = '';
@@ -140,15 +146,16 @@ async function dispatchRequest(request) {
 }
 export function buildCli(dependencies = {}) {
     const cli = new Command();
-    cli.name('kiokuko').description('Model-agnostic external memory for AI coding agents').version('0.1.0');
+    cli.name('kiokuko').description('Model-agnostic external memory for AI coding agents').version(packageVersion);
     cli.exitOverride();
     cli.configureOutput({ outputError: () => undefined });
     cli.command('init').description('Initialize the global Kiokuko database').option('--json').action(async (options) => {
         const result = await initializeDatabase();
-        humanOrJson(options.json, 'init', result, `Kiokuko database initialized (version ${result.currentVersion})`);
+        const backupNotice = result.backupPath === null ? '' : ` Pre-migration backup: ${result.backupPath}`;
+        humanOrJson(options.json, 'init', result, `Kiokuko database initialized (version ${result.currentVersion}).${backupNotice}`);
     });
-    cli.command('setup').description('Configure global Kiokuko memory for Codex, OpenCode, and Claude Code')
-        .option('--clients <clients>', 'Comma-separated clients: codex,opencode,claude', 'codex,opencode,claude')
+    cli.command('setup').description('Configure global Kiokuko memory for Codex, OpenCode, Claude Code, and Hermes Agent')
+        .option('--clients <clients>', 'Comma-separated clients: codex,opencode,claude,hermes', 'codex,opencode,claude,hermes')
         .option('--command <path>', 'Kiokuko executable name or absolute path', 'kiokuko')
         .option('--dry-run', 'Validate and show planned changes without writing')
         .option('--json', 'Emit a JSON response')
@@ -161,7 +168,7 @@ export function buildCli(dependencies = {}) {
         const changed = data.files.filter((file) => file.action !== 'unchanged').length;
         const message = options.dryRun
             ? `Kiokuko setup plan for ${data.clients.join(', ')}: ${changed} file${changed === 1 ? '' : 's'} would change.`
-            : `Kiokuko configured for ${data.clients.join(', ')} (${changed} file${changed === 1 ? '' : 's'} changed). ${data.nextStep}`;
+            : `Kiokuko configured for ${data.clients.join(', ')} (${changed} file${changed === 1 ? '' : 's'} changed).${data.databaseBackupPath === null ? '' : ` Pre-migration backup: ${data.databaseBackupPath}.`} ${data.nextStep}`;
         humanOrJson(options.json, 'setup', data, message);
     });
     cli.command('mcp').description('Run the Kiokuko MCP server over stdio').action(async () => {