@askdkc/kiokuko 0.1.17 → 0.1.20

package/README.ja.md

@@ -1,165 +1,144 @@
-# Kiokuko
+# Kiokuko（記憶庫）
 
 [English](README.md) | 日本語 | [简体中文](README.zh-CN.md) | [한국어](README.ko.md)
 
-Kiokukoは、AIコーディングエージェント向けのモデル非依存な外部記憶です。npmでグローバルインストールすると、現在のOSユーザー用SQLiteデータベースに構造化された記憶を保存し、native stdio MCP経由でCodex、OpenCode、Claude Code、Hermes Agentにタスク準備とrecall/checkpointツールを提供します。
+**MCPでつなぎ、RAGで思い出し、作業後に記憶する。**
 
-## グローバルへのインストールと有効化
+Kiokukoは、AIコーディングエージェント向けの外部記憶です。
 
-Node.js 24以上が必要です。
+過去の作業から得た知識をローカルのSQLiteへ保存し、次の依頼で関連する記憶だけを検索してAIへ渡します。
 
-```bash
-npm install --global @askdkc/kiokuko
-kiokuko setup
-```
+ユーザーが毎回プロンプトに過去の経緯を貼ったり、記憶を手作業で探したりする必要はありません。普段どおりAIを使うだけで、プロジェクト固有の知識が少しずつ蓄積され、次の作業へ再利用されます。
 
-引数なしの`setup`は`PATH`上で各対応クライアント（`codex`、`opencode`、`claude`、`hermes`）の実行ファイルを確認します。対話可能な端末では選択画面を表示し、検出できたクライアントをチェック済みで初期選択します。Enterでそのまま確定でき、クライアント名または番号をカンマ区切りで入力して変更できます。`none`でクライアント設定なしを選べます。非対話端末や`--json`ではプロンプトを表示せず、検出できたクライアントだけを設定します。`hermes`が検出された場合は`hermes config path`で現在のプロファイルを取得し、利用できない場合は有効な`active_profile`または既定の`$HOME/.hermes`を使います。対応クライアントを1つも検出できない場合もデータベースは初期化しますが、クライアント設定は書き込みません。クライアントを明示的に設定するには`--clients`を使ってください。`--clients`を明示した場合は、常にその指定が優先されます。
+## すぐ使う
 
-npmパッケージ名は`@askdkc/kiokuko`ですが、インストールされるCLIコマンド名は引き続き`kiokuko`です。
-
-セットアップ後は、setupの結果に表示されたクライアントを再起動してください。Hermesの`/reload-mcp`はMCP登録を再読み込みできますが、更新された標準スキルの検出には再起動または新規セッションが必要です。`hermes mcp test kiokuko`でスモークテストできます。Hermesは有効なプロファイルのnative stdio MCPを使い、グローバル指示ファイル、Hermes plugin、hookは作成しません。
-
-`setup`は明示的に実行する冪等な処理です。npmの`postinstall`がAIクライアントの設定を変更することはありません。既存のTOML/JSON/JSONC/YAML設定、コメント、指示内容、改行コード、ファイルモードを維持し、Kiokukoは管理対象セクションだけを更新します。既定では、固定されたローカルマニフェストから`kiokuko-ui-design-soul`標準スキルも導入します。setup時のダウンロードやHIGページのスクレイピングは行いません。
-
-既存データベースに未適用のマイグレーションがある場合、setupは先に現在のユーザー用データディレクトリ内の`backups/`へバックアップを作成し、整合性を検査します。現在のKiokukoより新しいバージョンで更新されたデータベースは変更せず拒否します。
+Node.js 24.16以上が必要です。
+以下の2コマンドで楽々スタートです💕
 
 ```bash
-# 書き込まずに変更対象ファイルと予定内容を確認
-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
-
-# 標準スキルの新規配置を省略（既存の管理済みコピーは削除しない）
-kiokuko setup --no-standard-skills
-```
-
-Hermesの設定はプロファイル単位です。`$HOME/.hermes/profiles/work/config.yaml`のようなnamed profileには、そのプロファイルのMCP設定と標準スキルだけを配置し、rootや非アクティブなプロファイルは変更しません。別プロセスで一時的に指定した`hermes -p <name>`は自動推測しません。確実にnamed profileを指定するには、次のように`HERMES_HOME`へプロファイルディレクトリを渡します。
-
-```bash
-HERMES_HOME="$HOME/.hermes/profiles/work" kiokuko setup --clients hermes
+npm install --global @askdkc/kiokuko
+kiokuko setup
 ```
 
-Desktopプロセスから`kiokuko`が見つからない場合は、空の`command -v`結果を渡さず、絶対パスへ移行します。
-
-```bash
-KIOKUKO_BIN="$(command -v kiokuko)"
-test -n "$KIOKUKO_BIN" && test -x "$KIOKUKO_BIN" || { echo "kiokuko executable not found" >&2; exit 1; }
-kiokuko setup --clients hermes --command "$KIOKUKO_BIN"
+`setup`は、インストール済みの対応クライアントを検出し、SQLiteデータベースとMCP接続を自動設定します。
+対話式setupでは、監査済みcommunity Skillも参考資料として利用するか確認します。既定は「いいえ」です。
+モデル向けの記憶は、capability gateを通るMCPツール `task_prepare` と
+`task_answer` からだけタスクへ渡されます。Kiokukoは、これらの呼び出し前に
+記憶を暗黙取得するclient Hookやpluginをインストールしません。
+
+設定後、対象のAIクライアントを起動し、あとは普段どおり使うだけです。すでに起動している場合は、いったん終了してから起動し直してください。
+
+対応クライアント：
+
+- Codex
+- OpenCode
+- Claude Code
+- Hermes Agent
+
+## 使うほど賢くなる仕組み
+
+```text
+ユーザーの依頼
+      ↓
+関連する過去の記憶を検索
+      ↓
+AIが記憶を参照して作業
+      ↓
+再利用できる成果や教訓を保存
+      ↓
+次の依頼で再び検索
 ```
 
-セットアップ対象は次のとおりです。
+Kiokukoは、次の流れを繰り返します。
 
-| クライアント | MCP設定 | グローバル指示 | 実行時ガード | 標準スキル |
-|---|---|---|---|---|
-| Codex | `$CODEX_HOME/config.toml`または`~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md`または`~/.codex/AGENTS.md` | — | `~/.agents/skills/kiokuko-ui-design-soul` |
-| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json`または`~/.config/opencode/opencode.json` | 同じディレクトリの`AGENTS.md` | `plugins/kiokuko-loop-guard.js` | グローバル設定内の`skills/kiokuko-ui-design-soul` |
-| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json`または`~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md`または`~/.claude/CLAUDE.md` | — | Claude設定内の`skills/kiokuko-ui-design-soul` |
-| Hermes Agent | 有効なプロファイルの`config.yaml`（`$HERMES_HOME`、`$HOME/.hermes`、またはWindowsの`%LOCALAPPDATA%/hermes`） | なし | なし | 有効なプロファイル内の`skills/kiokuko-ui-design-soul` |
+1. 作業前に、現在のプロジェクトとGlobal記憶を検索する
+2. 関連性の高い記憶だけをAIへ渡す
+3. AIが作業を実行する
+4. 作業後に、再利用できる知識を記憶する
+5. 次の作業で、その記憶を再利用する
 
-Hermesの設定はプロファイル単位です。`mcp_servers.kiokuko`に`command: kiokuko`と`args: [mcp]`を登録します。管理対象の正規形であれば`--command`でcommandだけを移行でき、args、コメント、他serverは保持します。未管理entry、余分なfield、`mcp`以外のargsは引き続きconflictです。Hermesの組み込みmemoryとskillsはKiokukoとは別です。モデルがMCP tool descriptionを使うかどうかはbest effortです。
+つまりKiokukoは、**永続的な記憶を蓄積していくRAGシステム**です。
 
-OpenCodeの`opencode.jsonc`がすでに存在する場合、Kiokukoはコメントを維持したままそのファイルを更新します。CodexにKiokuko管理外の`[mcp_servers.kiokuko]`テーブルが存在する場合、上書き対象を推測せずセットアップを停止します。管理対象のOpenCodeガードは、可視エージェントを12 stepに制限し、1ユーザー要求につき`task_prepare`と`memory_checkpoint`を各1回までにし、チェックポイント後のツール利用を閉じ、同一呼び出しまたは読み取り専用の探索結果が3回続いた後の再実行を停止します。カウンターとフィンガープリントはプロセスメモリにだけ保持します。
+MCPはAIクライアントとKiokukoを接続し、RAGは必要な記憶を検索してAIへ渡します。
 
-標準スキルの各ファイルにはKiokuko管理マーカーがあります。setupは固定された既知ファイルだけを更新し、完全一致は`unchanged`とし、無関係な兄弟ファイルは変更しません。同名ファイルに管理マーカーがなければ、ファイルやデータベースへ書き込む前に`CONFLICT`で停止します。
+## 記憶はプロジェクトごとに分離
 
-## 記憶のスコープ
+通常の検索では、無関係なプロジェクトの記憶を混ぜません。
 
-データベースはOSユーザー全体で共有されますが、通常のrecallがデータベース全体を無条件に検索することはありません。
+- **Project記憶**  
+  現在のリポジトリだけで使う知識
 
-- `project`記憶は、`.kiokuko.json`、既知の正規パス、またはGit remoteから自動解決されます。他のプロジェクトの記憶は除外されます。
-- `global`記憶は、本当にプロジェクト横断で利用する設定や教訓のために予約されています。
-- デフォルトの`auto` recallは、現在のプロジェクトとglobal記憶だけを返します。
-- remoteのないリポジトリには、パスから導出した安定した識別子を使用します。自動解決時にKiokukoがリポジトリ内へファイルを書き込むことはありません。
+- **Ecosystem記憶**  
+  元のプロジェクトに保持したまま、言語、フレームワーク、データベース、ランタイム、ツールなどの適用条件が現在のプロジェクトと一致する場合だけ再利用する知識
 
-MCPの公開インターフェースは意図的に小さくしています。
+- **Global記憶**  
+  特定のプロジェクトに依存せず、複数プロジェクトで再利用するよう明示的に一般化した知識
 
-- `task_prepare`: 1ユーザー要求につき1回だけ、Akinator形式の取り込み、上限付きの記憶・参照検索、現在のクライアントから渡されたSKILL/MCPツール名との照合を行います。
-- `task_answer`: ユーザーの依頼または確認済みのリポジトリ情報に根拠がある回答だけで、取り込みを続行します。
-- `memory_recall`: 上限付きのproject/globalコンテキストを読み取ります。結果には常にuntrustedマークが付きます。
-- `curator_check`: 最終checkpointの前に、原則としてスキル化可能な候補だけを返します。qualified hitは「実行可能なAkinator経路を独立runで完了し、freshな検証または成功テストがある」場合だけです。検索・recall回数は数えません。
-- `curator_globalize`: 表示されたスキル名と3行概要をユーザーが明示的に承認した後だけ、revision確認済みの再生成ドラフトをGlobalへ保存します。
-- `memory_checkpoint`: ユーザー要求の最後に1回だけ、上限付きの永続的な記憶を`candidate`かつ`untrusted`として保存します。同時に、提案記憶ごとのAkinator絞り込み経路をrunと検証証拠に結び付けます。シークレットに見える内容は拒否されます。
+自由形式のタグが一致するだけでは、Project記憶は他のプロジェクトへ共有されません。Ecosystem検索では、記憶に保存された構造化された適用条件と、現在のプロジェクトから検出した技術構成の両方が一致するかを確認します。プロジェクト固有のパスや識別子などを含む記憶は対象外です。
 
-## Curator
+プロジェクトはGitリモートやパスから自動判定されます。
 
-`kiokuko curator`は、プロジェクト内のcandidate記憶から、他のプロジェクトでも再利用できそうな知識を判定します。プロジェクト識別子やパスを中立化し、「目的・手順・適用条件・検証」の構造を持つ汎用ドラフトをローカルで決定論的に再生成します。スキル名、3行程度の概要、再生成した本文に加え、qualified hit数、独立run数、workspace数、抽象→具体サイロ充足度を表示してから、対話的にGlobalへの追加を確認します。`--skill-ready-only`は定期確認に使う高根拠候補だけへ絞り込みます。
+Project記憶をGlobal記憶へ移す場合は、Curatorで候補を確認して明示的に承認します。
 
 ```bash
 kiokuko curator
-kiokuko curator --json
-kiokuko curator --skill-ready-only
-kiokuko curator --entry-id <entry-id>
 ```
 
-Web UIの`Curator`ボタンでは、全プロジェクトworkspaceの汎用化候補を一覧表示します。候補ごとのチェックボックスで追加・見送りを選択し、選択した候補を1回の明示操作でGlobalへ追加できます。Globalには元のプロジェクト固有本文ではなく再生成ドラフトを保存します。外部LLMやAPIキーは使いません。追加後もGlobalエントリは`candidate`かつ`untrusted`のままで、元のworkspace・revision・provenanceを保持します。
-
-これは指示による自動利用であり、プロンプトの横取りではありません。Codex、OpenCode、Claude Code、Hermes Agentが特定のターンでツールを呼ばない可能性は残ります。Hermesでの自動利用・モデル利用はMCP tool descriptionによるbest effortです。Hermesの組み込みmemoryとskillsは分離されたままです。KiokukoはHermes用のグローバル指示ファイル、plugin、hookを作成せず、会話全文を取得せず、外部から取得したSKILLを自動インストールせず、記憶を暗黙にverifiedへ昇格させません。OpenCodeへ導入するpluginは上記の限定的なローカルループガードだけであり、同梱標準スキルはpluginではなくクライアントnativeのskillです。
+## 記憶を確認する
 
-## 開発
+ローカルWeb UIから、保存された記憶の検索、確認、編集ができます。
 
 ```bash
-npm install
-npm run typecheck
-npm test
-npm run build
-npm pack --dry-run
+kiokuko web
 ```
 
-## 開発環境での実行
+ブラウザで次を開きます。
 
-```bash
-npm exec -- tsx src/bin/kiokuko.ts setup --dry-run --json
-npm exec -- tsx src/bin/kiokuko.ts mcp
+```text
+http://127.0.0.1:4173
 ```
 
-`kiokuko use`は、移植可能な明示的バインディングが必要な場合の任意機能として残っています。`.kiokuko.json`と`AGENTS.md`内の管理ブロックを作成しますが、通常のMCP利用では不要です。
+Web UIはローカル環境だけで動作し、外部ネットワークへ公開されません。
+Web UIと明示的なmemory CLI commandは人間/operator向けの管理surfaceです。
+モデルが `task_prepare` / `task_answer` を迂回してタスク記憶を取得する経路ではありません。
 
-## Akinator形式の知識取り込み
+## 外部Skill
 
-重要な作業では、セットアップ済みのエージェント指示が`task_prepare`を呼び出します。Akinatorは人気投票や固定フォームではなく、抽象的な意図から複数の行動系列を候補にし、質問ごとに候補を除外・具体化して、選択行動、検証方法、停止条件まで収束させる推論ガイドです。返却する抽象→具体サイロは、意図、行動系列、対象、成功状態、選択行動、検証の各層と充足度を持ちます。タスク種別、対象、観測可能な成功条件など、不足している価値の高い項目だけを質問し、その後にクエリと役割・用途タグからローカル記憶を選択します。クライアントが現在利用可能なSKILLとMCPツールの完全な名前と短い説明を渡した場合は、必要な機能を照合し、`available`、`missing`、`unknown`を区別して返します。説明は項目単位で短縮・除外され、この一覧は一時的にだけ使用され、保存されません。CLIの`guide`コマンドでも同じ取り込みを手動実行できます。
+外部Skillの発見は参考データ専用で、Akinatorのtask preparationでは既定で
+`official` モードを使います。現在のGitHub commitを検証し、制限した本文を
+常に `candidate` + `untrusted` + `reference` の記憶として保存します。
+インストールや実行は行いません。自動発見を止める場合は
+`KIOKUKO_SKILL_DISCOVERY=off` を指定します。`community` は引き続き明示的な
+opt-inです。対話式 `kiokuko setup` はcommunityを有効にするか確認し、バッチ実行では
+`--skill-discovery community` で明示できます。
 
-UI、UX、frontend、screen、SwiftUI、画面、アクセシビリティなどの具体的なUI語彙を含む依頼では、クライアントのcapability一覧に存在する`kiokuko-ui-design-soul`を`task_prepare`が明示的に推薦します。`design`単独、backend-only作業、画像生成だけの依頼では発火しません。
+具体的な操作例:
 
 ```bash
-kiokuko guide start "Implement the API change and add tests" \
-  --workspace <workspace> --json
-kiokuko guide answer <session-id> --workspace <workspace> \
-  --question-id target --value src/api.ts --json
-kiokuko guide answer <session-id> --workspace <workspace> \
-  --question-id expected --value "All tests pass" --json
-kiokuko guide context <session-id> --workspace <workspace> --json
+kiokuko skills find svelte --official-only --json
+kiokuko skills list
+kiokuko skills disable sveltejs/ai-tools/svelte-code-writer
+kiokuko skills refresh sveltejs/ai-tools/svelte-code-writer
 ```
 
-ローカル検索で関連エントリが見つからず、クライアントが能力カタログとして空配列を明示した場合に限り、`task_prepare`は次の単一の許可済み公開リポジトリから現在の`main`ツリーを取得できます。
-
-- https://github.com/mattpocock/skills
+Web UIのExternal Skills画面ではsource状態を確認し、mappingを無効化・再有効化
+できます。インストール、script実行、MCP登録の操作はありません。
 
-capability一覧の省略・破損・非空はフォールバックを無効にします。CLIで手動利用する場合は、`guide context ... --no-client-skills`で同じ条件を明示します。`disable-model-invocation: true`のSKILLは自動選択から除外します。
+## 安全性
 
-インポートされた各エントリには、リポジトリ、commit SHA、ソースパスが記録されます。これらは信頼されていない参照資料であり、自動的に`verified`へ昇格したり、コマンドとして実行されたりすることはありません。同期の再実行はコンテンツハッシュにより冪等です。
+Kiokukoは会話全文を保存しません。
 
-## ローカルWeb UI
+パスワード、APIキー、トークン、秘密鍵など、シークレットに見える内容は保存を拒否します。
 
-ループバック専用HTTPサーバーを起動すると、役割・用途、記憶タイプ、横断タグで記憶エントリを閲覧し、ブラウザからcandidateエントリを編集できます。
+保存された記憶は常に参考情報として扱われます。過去の記憶より、現在のコード、設定、実行結果が優先されます。
 
-```bash
-kiokuko web
-# http://127.0.0.1:4173 を開く
-```
-
-UIは英語、日本語、簡体字中国語、韓国語に対応します。初回はブラウザの言語を使用し、明示的に選択した言語はブラウザに保存されます。`?lang=en`、`?lang=ja`、`?lang=zh-CN`、`?lang=ko`で上書きできます。
+## 注意
 
-`--port 0`で空いているポートを自動選択でき、`--json`で選択されたURLをJSONとして出力できます。Web UIが非ループバックインターフェースへサーバーを公開することはありません。verifiedおよびsupersededエントリは読み取り専用です。candidateの編集には楽観的リビジョン検査が使われ、監査履歴が維持されます。
+Kiokukoはプロンプトを横取りする仕組みではありません。自動利用は各AIクライアントとモデルのMCP呼び出しに依存するため、すべてのターンで必ず呼び出される保証はありません。
 
-`bot:researcher`、`bot:builder`、`bot:reviewer`などのタグは、種類をまたいだフィルターとして使用できます。エントリまたはサイドバーのタグをクリックすると、記憶タイプに関係なく一致するすべてのエントリが表示されます。
+詳細なコマンドは次から確認できます。
 
-記憶エントリは信頼されていない保存データです。過去のエントリを利用する前に、現在のファイルとランタイム状態を確認してください。パスワード、APIキー、トークン、秘密鍵、セッションCookieを保存しないでください。
-
-このリポジトリは自動公開されません。`npm publish`、commit、pushにはユーザーによる明示的な許可が必要です。
+```bash
+kiokuko --help
+kiokuko setup --help
+```

package/README.ko.md

@@ -1,150 +1,138 @@
-# Kiokuko
+# Kiokuko(기억 저장소)
 
 [English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | 한국어
 
-Kiokuko는 AI 코딩 에이전트를 위한 모델 독립적인 외부 메모리 도구입니다. npm으로 한 번 전역 설치하면 현재 운영체제 사용자의 SQLite 데이터베이스에 구조화된 메모리를 저장하고, native stdio MCP를 통해 Codex, OpenCode, Claude Code 및 Hermes Agent에 작업 준비와 recall/checkpoint 도구를 제공합니다.
+**MCP로 연결하고, RAG로 떠올리고, 작업 후에 기억합니다.**
 
-## 전역 설치 및 활성화
+Kiokuko는 AI 코딩 에이전트를 위한 외부 메모리입니다.
 
-Node.js 24 이상이 필요합니다.
+이전 작업에서 얻은 지식을 로컬 SQLite에 저장하고, 다음 요청에서 관련된 메모리만 검색해 AI에 전달합니다.
 
-```bash
-npm install --global @askdkc/kiokuko
-kiokuko setup
-```
+사용자는 매번 프롬프트에 과거의 경위를 붙여넣거나 메모리를 직접 찾을 필요가 없습니다. 평소처럼 AI를 사용하기만 하면 프로젝트 고유의 지식이 조금씩 쌓이고 다음 작업에 재사용됩니다.
 
-인자 없는 `setup`은 `PATH`에서 지원되는 각 클라이언트(`codex`, `opencode`, `claude`, `hermes`)의 실행 파일을 확인합니다. 대화형 터미널에서는 선택 목록을 표시하고 감지된 클라이언트를 미리 체크합니다. Enter를 누르면 현재 선택을 적용하며, 쉼표로 구분한 클라이언트 이름 또는 번호를 입력해 선택을 변경할 수 있고 `none`으로 클라이언트 설정 없음을 선택할 수 있습니다. 비대화형 터미널이나 `--json` 사용 시에는 프롬프트를 표시하지 않고 감지된 클라이언트만 설정합니다. `hermes`가 감지되면 `hermes config path`로 현재 profile을 확인하고, 그렇지 않으면 유효한 `active_profile` marker 또는 기본 `$HOME/.hermes`를 사용합니다. 지원되는 클라이언트를 하나도 감지하지 못해도 데이터베이스는 초기화하지만 클라이언트 설정은 작성하지 않습니다. 클라이언트를 명시적으로 설정하려면 `--clients`를 사용하십시오. `--clients`를 명시하면 항상 해당 선택이 우선됩니다.
+## 바로 시작하기
 
-npm 패키지 이름은 `@askdkc/kiokuko`이지만 설치되는 CLI 명령 이름은 계속 `kiokuko`입니다.
-
-설정 후 setup 결과에 표시된 클라이언트를 다시 시작하십시오. Hermes의 `/reload-mcp`는 MCP 등록을 다시 불러오지만 업데이트된 표준 스킬을 찾으려면 재시작 또는 새 세션이 필요합니다. `hermes mcp test kiokuko`로 smoke test할 수 있습니다. Hermes는 유효한 profile의 native stdio MCP를 사용하며 전역 지침 파일, Hermes plugin 또는 hook을 만들지 않습니다.
-
-`setup`은 명시적으로 실행하는 멱등 작업입니다. npm `postinstall`은 AI 클라이언트 설정을 수정하지 않습니다. 기존 TOML/JSON/JSONC/YAML 설정, 주석, 지침 내용, 줄바꿈 형식 및 파일 모드는 유지되며 Kiokuko는 관리 구역만 수정합니다. 기본적으로 setup은 고정된 로컬 매니페스트에서 `kiokuko-ui-design-soul` 표준 스킬도 설치하며, setup 중 다운로드나 HIG 페이지 스크래핑은 하지 않습니다.
-
-기존 데이터베이스에 적용되지 않은 마이그레이션이 있으면 setup은 먼저 현재 사용자의 데이터 디렉터리 안에 있는 `backups/`에 백업을 만들고 무결성을 검사합니다. 현재 Kiokuko보다 새로운 버전에서 기록된 데이터베이스는 변경하지 않고 거부합니다.
+Node.js 24.16 이상이 필요합니다.
+다음 두 명령어로 쉽게 시작할 수 있습니다 💕
 
 ```bash
-# 아무것도 쓰지 않고 정확한 대상 파일과 예정된 변경 사항 확인
-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
-
-# 새 표준 스킬 배치를 건너뜀; 기존 복사본은 삭제하지 않음
-kiokuko setup --no-standard-skills
+npm install --global @askdkc/kiokuko
+kiokuko setup
 ```
 
-Hermes 설정은 profile 범위입니다. `$HOME/.hermes/profiles/work/config.yaml` 같은 named profile에는 해당 profile의 MCP 설정과 표준 skill만 배치하고 root 및 비활성 profile은 변경하지 않습니다. 다른 프로세스에서 임시로 지정한 `hermes -p <name>`은 자동 추측하지 않습니다. named profile을 확실히 지정하려면 다음처럼 `HERMES_HOME`에 profile 디렉터리를 전달하십시오.
-
-```bash
-HERMES_HOME="$HOME/.hermes/profiles/work" kiokuko setup --clients hermes
+`setup`은 설치된 지원 클라이언트를 감지하고 SQLite 데이터베이스와 MCP 연결을 자동으로 설정합니다.
+대화형 setup은 감사된 community Skill도 참고 자료로 사용할지 묻고, 기본 응답은 아니요입니다.
+모델용 메모리는 capability gate를 거치는 MCP 도구 `task_prepare`와
+`task_answer`를 통해서만 작업에 전달됩니다. Kiokuko는 이 호출 전에 메모리를
+암묵적으로 불러오는 클라이언트 훅이나 플러그인을 설치하지 않습니다.
+
+설정 후 대상 AI 클라이언트를 실행하고 평소처럼 사용하면 됩니다. 이미 실행 중이라면 한 번 종료한 후 다시 시작하십시오.
+
+지원 클라이언트:
+
+- Codex
+- OpenCode
+- Claude Code
+- Hermes Agent
+
+## 사용할수록 똑똑해지는 구조
+
+```text
+사용자 요청
+      ↓
+관련 과거 메모리 검색
+      ↓
+AI가 메모리를 참고해 작업
+      ↓
+재사용 가능한 결과나 교훈 저장
+      ↓
+다음 요청에서 다시 검색
 ```
 
-Desktop 프로세스가 `PATH`에서 `kiokuko`를 찾지 못하면 빈 `command -v` 결과를 넘기지 말고 절대 경로로 전환하십시오.
+Kiokuko는 다음 흐름을 반복합니다.
 
-```bash
-KIOKUKO_BIN="$(command -v kiokuko)"
-test -n "$KIOKUKO_BIN" && test -x "$KIOKUKO_BIN" || { echo "kiokuko executable not found" >&2; exit 1; }
-kiokuko setup --clients hermes --command "$KIOKUKO_BIN"
-```
-
-설정 대상은 다음과 같습니다.
+1. 작업 전에 현재 프로젝트와 Global 메모리를 검색합니다
+2. 관련성이 높은 메모리만 AI에 전달합니다
+3. AI가 작업을 수행합니다
+4. 작업 후 재사용할 수 있는 지식을 메모리로 저장합니다
+5. 다음 작업에서 그 메모리를 재사용합니다
 
-| 클라이언트 | MCP 설정 | 전역 지침 | 런타임 가드 | 표준 스킬 |
-|---|---|---|---|---|
-| Codex | `$CODEX_HOME/config.toml` 또는 `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` 또는 `~/.codex/AGENTS.md` | — | `~/.agents/skills/kiokuko-ui-design-soul` |
-| OpenCode | `$XDG_CONFIG_HOME/opencode/opencode.json` 또는 `~/.config/opencode/opencode.json` | 같은 디렉터리의 `AGENTS.md` | `plugins/kiokuko-loop-guard.js` | 전역 설정의 `skills/kiokuko-ui-design-soul` |
-| Claude Code | `$CLAUDE_CONFIG_DIR/.claude.json` 또는 `~/.claude.json` | `$CLAUDE_CONFIG_DIR/CLAUDE.md` 또는 `~/.claude/CLAUDE.md` | — | Claude 설정의 `skills/kiokuko-ui-design-soul` |
-| Hermes Agent | 유효한 profile의 `config.yaml` (`$HERMES_HOME`, `$HOME/.hermes` 또는 `%LOCALAPPDATA%/hermes`) | 없음 | 없음 | 유효한 profile의 `skills/kiokuko-ui-design-soul` |
+즉, Kiokuko는 **영구 메모리를 축적하는 RAG 시스템**입니다.
 
-Hermes 설정은 profile 범위의 native stdio MCP입니다. `mcp_servers.kiokuko`에 `command: kiokuko`, `args: [mcp]`를 등록합니다. 관리되는 canonical entry는 `--command`로 command만 변경할 수 있으며 args, 주석, 다른 server는 유지됩니다. 관리되지 않은 entry, 추가 field, `mcp`가 아닌 args는 계속 conflict입니다. Hermes의 내장 memory와 skills는 Kiokuko와 별개이며, 모델이 MCP tool descriptions를 사용할지는 best effort입니다.
+MCP는 AI 클라이언트와 Kiokuko를 연결하고, RAG는 필요한 메모리를 검색해 AI에 전달합니다.
 
-OpenCode의 `opencode.jsonc`가 이미 있으면 Kiokuko는 주석을 유지하면서 해당 파일을 수정합니다. Codex에 Kiokuko가 관리하지 않는 `[mcp_servers.kiokuko]` 테이블이 이미 있으면 어떤 설정을 덮어쓸지 추측하지 않고 설정을 중단합니다. 관리되는 OpenCode 가드는 보이는 에이전트를 12 step으로 제한하고, 사용자 요청마다 `task_prepare`와 `memory_checkpoint`를 각각 한 번만 허용하며, 체크포인트 후 도구 단계를 닫고, 동일 호출 또는 읽기 전용 탐색 결과가 세 번 연속 나온 뒤의 재실행을 차단합니다. 카운터와 지문은 프로세스 메모리에만 보관됩니다.
+## 메모리는 프로젝트별로 분리됩니다
 
-각 표준 스킬 파일에는 Kiokuko 관리 마커가 있습니다. setup은 고정된 알려진 파일만 업데이트하고 완전 일치는 `unchanged`로 보고하며 관련 없는 형제 파일은 유지합니다. 같은 이름의 파일에 관리 마커가 없으면 파일이나 데이터베이스를 쓰기 전에 `CONFLICT`로 중단합니다.
+일반 검색에서는 관련 없는 프로젝트의 메모리를 섞지 않습니다.
 
-## 메모리 범위
+- **Project 메모리**
+  현재 저장소에서만 사용하는 지식
 
-데이터베이스는 운영체제 사용자 전체에서 공유되지만 일반 recall은 전역 데이터베이스 전체를 검색하지 않습니다.
+- **Global 메모리**
+  언어, 프레임워크, 데이터베이스, 도구 등 여러 프로젝트에서 재사용할 수 있는 지식
 
-- `project` 메모리는 `.kiokuko.json`, 알려진 정규 경로 또는 Git remote에서 자동으로 확인됩니다. 다른 프로젝트의 메모리는 제외됩니다.
-- `global` 메모리는 실제로 여러 프로젝트에 적용되는 선호 사항과 교훈을 위해 예약됩니다.
-- 기본 `auto` recall은 현재 프로젝트와 global 메모리만 반환합니다.
-- remote가 없는 저장소에는 경로에서 파생된 안정적인 식별자가 할당됩니다. 자동 확인 중 Kiokuko는 저장소에 어떤 파일도 쓰지 않습니다.
+프로젝트는 Git remote 또는 경로에서 자동으로 판별됩니다.
 
-MCP 인터페이스는 의도적으로 작게 유지됩니다.
+Project 메모리를 Global 메모리로 옮길 때는 Curator에서 후보를 확인하고 명시적으로 승인합니다.
 
-- `task_prepare`: 사용자 요청마다 한 번만 Akinator 방식 수집, 제한된 메모리/참조 검색, 현재 클라이언트가 제공한 스킬 및 MCP 도구 이름과의 매칭을 수행합니다.
-- `task_answer`: 사용자 요청 또는 검증된 저장소 근거로 뒷받침되는 답변만 사용해 수집을 계속합니다.
-- `memory_recall`: 제한된 project/global 컨텍스트를 읽으며 항상 untrusted로 표시합니다.
-- `memory_checkpoint`: 사용자 요청 마지막에 한 번만 제한된 지속성 항목을 `candidate` 및 `untrusted`로 저장합니다. 비밀 정보로 보이는 내용은 거부됩니다.
+```bash
+kiokuko curator
+```
 
-이는 지침에 기반한 자동 사용이며 프롬프트 가로채기가 아닙니다. Codex, OpenCode, Claude Code 및 Hermes Agent가 특정 턴에서 도구를 호출하지 않을 가능성은 여전히 있습니다. Hermes의 자동/모델 사용은 MCP tool descriptions에 따른 best effort입니다. Hermes의 내장 memory와 skills는 분리되어 있습니다. Kiokuko는 Hermes 전역 지침 파일, plugin 또는 hook을 만들지 않으며 전체 대화를 수집하거나 외부에서 가져온 스킬을 자동 설치하거나 메모리를 조용히 verified 상태로 승격하지 않습니다. OpenCode에 설치하는 유일한 plugin은 위의 제한된 로컬 루프 가드이며 동봉 표준 스킬은 plugin이 아니라 클라이언트 native skill입니다.
+## 메모리 확인하기
 
-## 개발
+로컬 Web UI에서 저장된 메모리를 검색, 확인하고 편집할 수 있습니다.
 
 ```bash
-npm install
-npm run typecheck
-npm test
-npm run build
-npm pack --dry-run
+kiokuko web
 ```
 
-## 개발 환경에서 사용
+브라우저에서 다음 주소를 여십시오.
 
-```bash
-npm exec -- tsx src/bin/kiokuko.ts setup --dry-run --json
-npm exec -- tsx src/bin/kiokuko.ts mcp
+```text
+http://127.0.0.1:4173
 ```
 
-`kiokuko use`는 이식 가능한 명시적 바인딩이 필요한 경우를 위한 선택 기능으로 유지됩니다. `.kiokuko.json`과 `AGENTS.md`의 관리 블록을 생성하지만 일반적인 MCP 사용에는 더 이상 필요하지 않습니다.
+Web UI는 로컬 환경에서만 작동하며 외부 네트워크에 공개되지 않습니다.
+Web UI와 명시적 memory CLI 명령은 사람/operator용 관리 화면입니다. 모델이
+`task_prepare` / `task_answer`를 우회하여 작업 메모리를 가져오는 경로가 아닙니다.
 
-## Akinator 방식 지식 수집
+## 외부 스킬
 
-중요한 작업에서는 설정된 에이전트 지침이 `task_prepare`를 호출합니다. 이 도구는 작업 유형, 대상 및 성공 조건과 같이 누락된 고가치 필드만 질문한 뒤 쿼리와 역할과 용도 태그를 사용하여 로컬 메모리를 선택합니다. 클라이언트가 현재 사용 가능한 스킬과 MCP 도구의 전체 이름 및 짧은 설명을 제공하면 필요한 기능을 매칭하고 `available`, `missing`, `unknown`을 구분해 반환합니다. 설명은 항목별로 축약 또는 제외되며 이 목록은 일시적으로만 사용되고 저장되지 않습니다. CLI의 `guide` 명령으로 같은 수집을 수동 실행할 수 있습니다.
+외부 스킬 검색은 참고 데이터 전용이며 Akinator task preparation에서 기본적으로
+`official` 모드를 사용합니다. 현재 GitHub 커밋을 검증하고 제한된 내용을 신뢰할 수
+없는 후보 메모리로 저장하지만 자동 설치나 실행은 하지 않습니다. 자동 검색을
+중지하려면 `KIOKUKO_SKILL_DISCOVERY=off`를 지정합니다. `community`는 계속 명시적으로
+활성화해야 합니다. 대화형 `kiokuko setup`에서 활성화 여부를 확인하며, 배치 실행은
+`--skill-discovery community`를 사용할 수 있습니다.
 
-작업에 UI, UX, frontend, screen, SwiftUI, 화면 또는 accessibility 같은 구체적인 인터페이스 용어가 있으면 `task_prepare`는 클라이언트 capability 목록의 `kiokuko-ui-design-soul`을 명시적으로 추천합니다. 일반적인 `design`, backend-only 작업 또는 이미지 생성만 있는 요청에서는 발동하지 않습니다.
+명령 예시:
 
 ```bash
-kiokuko guide start "Implement the API change and add tests" \
-  --workspace <workspace> --json
-kiokuko guide answer <session-id> --workspace <workspace> \
-  --question-id target --value src/api.ts --json
-kiokuko guide answer <session-id> --workspace <workspace> \
-  --question-id expected --value "All tests pass" --json
-kiokuko guide context <session-id> --workspace <workspace> --json
+kiokuko skills find svelte --official-only --json
+kiokuko skills list
+kiokuko skills disable sveltejs/ai-tools/svelte-code-writer
+kiokuko skills refresh sveltejs/ai-tools/svelte-code-writer
 ```
 
-로컬 검색에서 관련 항목을 찾지 못하고 클라이언트가 사용 가능한 스킬이 0개라고 명시한 경우에만 `task_prepare`가 다음 단일 허용 목록 공개 저장소에서 현재 `main` 트리를 가져올 수 있습니다.
-
-- https://github.com/mattpocock/skills
+Web UI의 외부 스킬 화면에서는 출처 상태를 확인하고 가져온 매핑을 비활성화하거나
+다시 활성화할 수 있습니다. 설치, 스크립트 실행, MCP 등록 기능은 없습니다.
 
-capability 목록을 생략하거나, 손상되었거나, 비어 있지 않으면 폴백을 비활성화합니다. 수동 CLI 사용은 `guide context ... --no-client-skills`로 같은 조건을 명시해야 합니다. `disable-model-invocation: true`로 표시된 스킬은 자동 선택에서 제외됩니다.
+## 안전성
 
-가져온 각 항목에는 저장소, commit SHA 및 소스 경로가 기록됩니다. 신뢰되지 않은 참조 자료이므로 자동으로 `verified`로 승격되거나 명령으로 실행되지 않습니다. 반복 동기화는 콘텐츠 해시를 통해 멱등성을 유지합니다.
+Kiokuko는 전체 대화를 저장하지 않습니다.
 
-## 로컬 Web UI
+비밀번호, API 키, 토큰, 개인 키 등 시크릿처럼 보이는 내용은 저장을 거부합니다.
 
-루프백 전용 HTTP 서버를 시작하면 역할과 용도, 메모리 유형 및 교차 태그별로 메모리 항목을 탐색하고 브라우저에서 candidate 항목을 편집할 수 있습니다.
+저장된 메모리는 항상 참고 정보로 취급됩니다. 과거 메모리보다 현재 코드, 설정, 실행 결과가 우선합니다.
 
-```bash
-kiokuko web
-# http://127.0.0.1:4173 열기
-```
-
-UI는 영어, 일본어, 중국어 간체 및 한국어를 지원합니다. 처음에는 브라우저 언어를 사용하고 명시적으로 선택한 언어는 브라우저에 저장합니다. `?lang=en`, `?lang=ja`, `?lang=zh-CN`, `?lang=ko`로 재정의할 수도 있습니다.
+## 주의
 
-`--port 0`을 사용하면 사용 가능한 포트를 자동으로 선택하고, `--json`을 사용하면 선택된 URL을 JSON으로 출력합니다. Web UI는 루프백이 아닌 인터페이스에 서버를 노출하지 않습니다. verified 및 superseded 항목은 읽기 전용이며 candidate 편집에는 낙관적 리비전 검사를 사용하고 감사 기록을 유지합니다.
+Kiokuko는 프롬프트를 가로채는 방식이 아닙니다. 자동 사용은 각 AI 클라이언트와 모델의 MCP 호출에 의존하므로 모든 턴에서 반드시 호출된다는 보장은 없습니다.
 
-`bot:researcher`, `bot:builder`, `bot:reviewer` 같은 태그를 유형 간 필터로 사용할 수 있습니다. 항목 또는 사이드바의 태그를 클릭하면 메모리 유형과 관계없이 일치하는 모든 항목을 표시합니다.
+자세한 명령어는 다음에서 확인할 수 있습니다.
 
-메모리 항목은 신뢰되지 않은 저장 데이터입니다. 과거 항목을 사용하기 전에 현재 파일과 런타임 상태를 확인하십시오. 비밀번호, API 키, 토큰, 개인 키 또는 세션 쿠키를 저장하지 마십시오.
-
-이 저장소는 자동으로 게시되지 않습니다. `npm publish`, commit 및 push에는 사용자의 명시적 승인이 필요합니다.
+```bash
+kiokuko --help
+kiokuko setup --help
+```