kiokuko 1.0.41 → 1.0.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/README.ja.md +21 -159
  2. package/README.ko.md +21 -125
  3. package/README.md +21 -194
  4. package/README.zh-CN.md +21 -126
  5. package/dist/agent-file/atomic-write.d.ts.map +1 -1
  6. package/dist/agent-file/atomic-write.js +2 -1
  7. package/dist/agent-file/atomic-write.js.map +1 -1
  8. package/dist/akinator/agent-task.d.ts +4 -2
  9. package/dist/akinator/agent-task.d.ts.map +1 -1
  10. package/dist/akinator/agent-task.js +14 -4
  11. package/dist/akinator/agent-task.js.map +1 -1
  12. package/dist/akinator/preparation-recovery.d.ts.map +1 -1
  13. package/dist/assurance/inspect.d.ts +1 -1
  14. package/dist/cli.d.ts.map +1 -1
  15. package/dist/cli.js +64 -7
  16. package/dist/cli.js.map +1 -1
  17. package/dist/commands/agent.d.ts.map +1 -1
  18. package/dist/commands/agent.js +15 -3
  19. package/dist/commands/agent.js.map +1 -1
  20. package/dist/commands/code-version.d.ts +6 -0
  21. package/dist/commands/code-version.d.ts.map +1 -0
  22. package/dist/commands/code-version.js +66 -0
  23. package/dist/commands/code-version.js.map +1 -0
  24. package/dist/commands/doctor.d.ts +14 -0
  25. package/dist/commands/doctor.d.ts.map +1 -1
  26. package/dist/commands/doctor.js +101 -32
  27. package/dist/commands/doctor.js.map +1 -1
  28. package/dist/commands/use.d.ts.map +1 -1
  29. package/dist/commands/use.js +10 -1
  30. package/dist/commands/use.js.map +1 -1
  31. package/dist/context/broker.d.ts +4 -1
  32. package/dist/context/broker.d.ts.map +1 -1
  33. package/dist/context/broker.js +9 -3
  34. package/dist/context/broker.js.map +1 -1
  35. package/dist/context/ranking.d.ts +1 -1
  36. package/dist/context/ranking.d.ts.map +1 -1
  37. package/dist/context/ranking.js +2 -1
  38. package/dist/context/ranking.js.map +1 -1
  39. package/dist/context/scoped-broker.d.ts +3 -1
  40. package/dist/context/scoped-broker.d.ts.map +1 -1
  41. package/dist/context/scoped-broker.js +8 -5
  42. package/dist/context/scoped-broker.js.map +1 -1
  43. package/dist/gateway/checkpoint-mutation-service.d.ts.map +1 -1
  44. package/dist/gateway/checkpoint-mutation-service.js +2 -1
  45. package/dist/gateway/checkpoint-mutation-service.js.map +1 -1
  46. package/dist/mcp/chatgpt-contract.d.ts +32 -0
  47. package/dist/mcp/chatgpt-contract.d.ts.map +1 -1
  48. package/dist/mcp/chatgpt-contract.js +4 -2
  49. package/dist/mcp/chatgpt-contract.js.map +1 -1
  50. package/dist/mcp/request-deadline.d.ts +1 -1
  51. package/dist/mcp/request-deadline.d.ts.map +1 -1
  52. package/dist/mcp/request-deadline.js +1 -0
  53. package/dist/mcp/request-deadline.js.map +1 -1
  54. package/dist/mcp/server.d.ts.map +1 -1
  55. package/dist/mcp/server.js +47 -4
  56. package/dist/mcp/server.js.map +1 -1
  57. package/dist/memory/applicability-context.d.ts +24 -0
  58. package/dist/memory/applicability-context.d.ts.map +1 -0
  59. package/dist/memory/applicability-context.js +129 -0
  60. package/dist/memory/applicability-context.js.map +1 -0
  61. package/dist/memory/checkpoint-contract.d.ts +30 -0
  62. package/dist/memory/checkpoint-contract.d.ts.map +1 -1
  63. package/dist/memory/checkpoint-contract.js +5 -0
  64. package/dist/memory/checkpoint-contract.js.map +1 -1
  65. package/dist/memory/code-versions.d.ts +79 -0
  66. package/dist/memory/code-versions.d.ts.map +1 -0
  67. package/dist/memory/code-versions.js +159 -0
  68. package/dist/memory/code-versions.js.map +1 -0
  69. package/dist/memory/context-budget.d.ts +5 -0
  70. package/dist/memory/context-budget.d.ts.map +1 -0
  71. package/dist/memory/context-budget.js +5 -0
  72. package/dist/memory/context-budget.js.map +1 -0
  73. package/dist/memory/entry-history.d.ts +29 -0
  74. package/dist/memory/entry-history.d.ts.map +1 -0
  75. package/dist/memory/entry-history.js +66 -0
  76. package/dist/memory/entry-history.js.map +1 -0
  77. package/dist/memory/federated-retrieval.d.ts.map +1 -1
  78. package/dist/memory/federated-retrieval.js +25 -7
  79. package/dist/memory/federated-retrieval.js.map +1 -1
  80. package/dist/memory/global-conversation-query.d.ts +3 -0
  81. package/dist/memory/global-conversation-query.d.ts.map +1 -1
  82. package/dist/memory/global-conversation-query.js +5 -2
  83. package/dist/memory/global-conversation-query.js.map +1 -1
  84. package/dist/memory/history-delivery.d.ts +57 -0
  85. package/dist/memory/history-delivery.d.ts.map +1 -0
  86. package/dist/memory/history-delivery.js +85 -0
  87. package/dist/memory/history-delivery.js.map +1 -0
  88. package/dist/memory/hybrid-retrieval.d.ts +5 -0
  89. package/dist/memory/hybrid-retrieval.d.ts.map +1 -1
  90. package/dist/memory/hybrid-retrieval.js +28 -9
  91. package/dist/memory/hybrid-retrieval.js.map +1 -1
  92. package/dist/memory/interaction-contract.d.ts +12 -2
  93. package/dist/memory/interaction-contract.d.ts.map +1 -1
  94. package/dist/memory/interaction-contract.js +3 -2
  95. package/dist/memory/interaction-contract.js.map +1 -1
  96. package/dist/memory/interaction-recall.d.ts +3 -0
  97. package/dist/memory/interaction-recall.d.ts.map +1 -1
  98. package/dist/memory/interaction-recall.js +2 -1
  99. package/dist/memory/interaction-recall.js.map +1 -1
  100. package/dist/memory/lesson-derivation.d.ts +1 -1
  101. package/dist/memory/lifecycle.d.ts.map +1 -1
  102. package/dist/memory/lifecycle.js +18 -1
  103. package/dist/memory/lifecycle.js.map +1 -1
  104. package/dist/memory/observation-contract.d.ts +8 -2
  105. package/dist/memory/observation-contract.d.ts.map +1 -1
  106. package/dist/memory/observation-contract.js +3 -1
  107. package/dist/memory/observation-contract.js.map +1 -1
  108. package/dist/memory/observations.d.ts.map +1 -1
  109. package/dist/memory/observations.js +21 -5
  110. package/dist/memory/observations.js.map +1 -1
  111. package/dist/memory/relation-delivery.d.ts +107 -0
  112. package/dist/memory/relation-delivery.d.ts.map +1 -0
  113. package/dist/memory/relation-delivery.js +163 -0
  114. package/dist/memory/relation-delivery.js.map +1 -0
  115. package/dist/memory/retrieval.d.ts +14 -0
  116. package/dist/memory/retrieval.d.ts.map +1 -1
  117. package/dist/memory/retrieval.js +19 -11
  118. package/dist/memory/retrieval.js.map +1 -1
  119. package/dist/memory/structured-memory.d.ts +5 -0
  120. package/dist/memory/structured-memory.d.ts.map +1 -1
  121. package/dist/memory/structured-memory.js +28 -6
  122. package/dist/memory/structured-memory.js.map +1 -1
  123. package/dist/repository/binding-repair.d.ts +38 -0
  124. package/dist/repository/binding-repair.d.ts.map +1 -0
  125. package/dist/repository/binding-repair.js +129 -0
  126. package/dist/repository/binding-repair.js.map +1 -0
  127. package/dist/server/agent-checkpoint-use-case.d.ts.map +1 -1
  128. package/dist/server/agent-checkpoint-use-case.js +1 -0
  129. package/dist/server/agent-checkpoint-use-case.js.map +1 -1
  130. package/dist/server/routes/agent-capability-gate.d.ts.map +1 -1
  131. package/dist/server/routes/agent-capability-gate.js +1 -0
  132. package/dist/server/routes/agent-capability-gate.js.map +1 -1
  133. package/dist/web/server.d.ts.map +1 -1
  134. package/dist/web/server.js +5 -1
  135. package/dist/web/server.js.map +1 -1
  136. package/docs/README.ja.md +2 -0
  137. package/docs/README.md +2 -0
  138. package/docs/cli-contract.md +24 -5
  139. package/docs/context-delivery.md +69 -0
  140. package/docs/getting-started.ja.md +8 -5
  141. package/docs/getting-started.md +11 -8
  142. package/docs/history-evidence.md +139 -0
  143. package/docs/interaction-memory.md +1 -1
  144. package/docs/setup-notes.ja.md +122 -0
  145. package/docs/setup-notes.ko.md +107 -0
  146. package/docs/setup-notes.md +133 -0
  147. package/docs/setup-notes.zh-CN.md +107 -0
  148. package/migrations/014_code_version_evidence.sql +26 -0
  149. package/package.json +1 -1
@@ -0,0 +1,122 @@
1
+ # 設定とトラブルシューティング
2
+
3
+ <a id="setup-messages"></a>
4
+
5
+ ### npmの通知とセットアップエラー
6
+
7
+ `install scripts not yet covered by allowScripts`は、依存パッケージのスクリプトに実行許可が記録されていないという通知です。
8
+ `esbuild`はビルドツール、`fsevents`はmacOSのファイル監視用です。この通知だけではセットアップの失敗とは限りません。
9
+
10
+ 通知が出たパッケージのディレクトリで確認します。
11
+
12
+ ```bash
13
+ npm install-scripts ls
14
+ ```
15
+
16
+ `esbuild`と`fsevents`が表示され、スクリプトを確認したうえで実行を許可する場合は、次のコマンドで記録します。
17
+
18
+ ```bash
19
+ npm install-scripts approve esbuild fsevents
20
+ ```
21
+
22
+ 許可はそのディレクトリの`package.json`に保存されます。macOSでKiokukoをグローバルインストールした場合は、エラーに表示されたKiokukoのインストール先で実行してください。
23
+ 別のプロジェクトで実行すると、そのプロジェクトの許可設定を確認・変更します。
24
+ 詳しくは[npmのスクリプト許可ガイド](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/)を参照してください。
25
+
26
+ 最後に`Local semantic retrieval dependencies remain unavailable`と`Cannot find package ... @huggingface/hub/index.js`が出た場合は、
27
+ 埋め込みランタイムを読み込めず、semantic検索の設定が完了していません。スクリプトの許可でこの読み込みエラーが直るとは確認できていません。
28
+ 問い合わせる際は、エラー全文と`kiokuko --version`、`node --version`、`npm --version`の結果を添えてください。
29
+
30
+ ### Codex用の保存済み実行版
31
+
32
+ npmの導入先が置き換わってもCodexのMCPとライフサイクルhookを同じ版で動かすには、ユーザー専用のアプリケーションデータ領域に実行版を用意します。進行中の作業を終え、Codexを停止してから設定を切り替えてください。
33
+
34
+ ```bash
35
+ kiokuko runtime-prepare --runtime-root "$HOME/Library/Application Support/Kiokuko/runtimes" --json
36
+ kiokuko setup --clients codex --no-embeddings --no-standard-skills --runtime-manifest /absolute/path/to/runtime/manifest.json --client-stopped
37
+ kiokuko runtime-diagnose --manifest /absolute/path/to/runtime/manifest.json --json
38
+ ```
39
+
40
+ Linuxでは実行版の保存先に`${XDG_DATA_HOME:-$HOME/.local/share}/kiokuko/runtimes`を使います。2行目と3行目のmanifestは、1行目が返す`manifestPath`に置き換えます。現在のNodeがバイナリ外の共有ライブラリに依存する場合、準備は失敗します。その場合は`--node /absolute/path/to/node`で単独起動できるNodeを指定してください。準備だけではクライアント設定は変わりません。`setup`は保存したファイルを検証し、管理対象のMCPと全hookを同じ版へ更新します。途中で失敗した設定ファイルは元に戻します。診断結果が`readyForRestart: true`になってからCodexを再起動してください。独自のMCP起動コマンドは保持され、別途移行が必要です。
41
+
42
+ npmを更新しただけでは使用版は切り替わりません。更新時は作業を終えてCodexを停止し、新版を準備して、そのmanifestで`setup`を実行してから再起動します。旧実行版は自動削除しません。新版がメモリDBをmigrationした後に旧版へ戻す場合は、先にDB互換性を確認してください。保存容量はNodeと導入済みの任意依存によって変わりますが、1版につき数百MBを見込み、複数版を残す前に実際の容量を確認してください。
43
+
44
+ ### リポジトリの指示ファイル
45
+
46
+ `kiokuko use`はリポジトリの`AGENTS.md`(または設定した指示ファイル)に短い参照を置き、
47
+ 生成した指示を`.kiokuko/AGENTS.md`に保存します。テンプレートやリポジトリ識別情報の更新は
48
+ 生成ファイルへ反映し、旧形式のバージョン付きブロックは次のuse/setup更新で参照へ移行します。
49
+ 独自の指示はKiokukoの管理マーカー外に置いてください。ユーザーの記述と他製品の部分は保持します。
50
+
51
+ 通常のsetupは欠落したルート指示ファイルを再作成せずスキップします。
52
+ 通常の`kiokuko doctor`は、登録済みのルート指示・生成指示ファイルの欠落を
53
+ 対話・非対話の両方で、確認待ちや追加の修復フラグなしに作成します。
54
+ 登録ID・workspace・binding・正規パスの一致が条件です。作成するのは欠落ファイルだけで、
55
+ 既存の独自記述を保持し、削除済みの独自指示は復元できません。権限不足・危険なシンボリックリンク・
56
+ 同時変更は対象ごとに報告し、ほかの対象の処理を続けます。欠落・矛盾するbindingは推測で置き換えず診断します。
57
+
58
+ ```bash
59
+ kiokuko doctor
60
+ kiokuko doctor --json
61
+ kiokuko doctor --fix --repair-root /absolute/path/to/project
62
+ ```
63
+
64
+ `kiokuko doctor --json`は欠落した指示を作成せず診断します。`--fix`は登録済みbindingを修復する明示的なモードで、
65
+ `--repair-root`には`--fix`が必要です。`--fix --json`でもbindingの修復は実行されます。
66
+ 既存の管理部分の更新は別途対話確認を行い、非対話実行では承認扱いにしません。
67
+ 欠落した生成指示はuse/setupでも復元できます。アンインストールでは両ファイルのKiokuko管理部分だけを除去します。
68
+ 詳しくは[CLI契約(英語)](cli-contract.md)を参照してください。
69
+
70
+ ## アンインストール
71
+
72
+ Kiokukoを使うクライアントと`kiokuko serve`を終了してから実行します。
73
+
74
+ ```bash
75
+ kiokuko uninstall --dry-run
76
+ kiokuko uninstall
77
+ # 全エージェントを選択して正常終了後、最後に表示されたコマンドを実行
78
+ npm uninstall --global kiokuko
79
+ ```
80
+
81
+ ↑↓で移動、Spaceで選択を切り替え、Enterで確定、Escで中止します。初期状態は未選択です。
82
+ 選択したエージェントの管理設定・Skillだけを削除します。**全4エージェントを選ぶと記憶DB・埋め込みモデル・登録済みプロジェクトの管理部分も削除**し、最後にnpmの削除コマンドを表示します。一部だけを選んだ場合は共有データとnpmパッケージを残します。ユーザーが書いた内容は保持します。
83
+ スクリプトでは `kiokuko uninstall --clients opencode,claude`、完全削除には `kiokuko uninstall --all` を使います。
84
+ 独自の配置先を指定していた場合は、セットアップ時と同じ環境変数で実行してください。[削除範囲と失敗時の扱い](cli-contract.md#uninstall)
85
+
86
+ <a id="chatgpt"></a>
87
+
88
+ ## ChatGPTで使う(プレビュー)
89
+
90
+ Developer modeで自分用プラグインとして接続し、記憶を保存・検索します。ストア配布版はありません。
91
+
92
+ 1. **Kiokukoを準備する。** `kiokuko mcp --help`に`--profile`と`--access`がある版を使います。なければ[ソース版を導入](chatgpt.ja.md)。DBが未作成なら`kiokuko init`を実行します。
93
+ 2. **Tunnelクライアントを入れる。** macOSでは[公式Homebrew手順](https://github.com/openai/tunnel-client#install-with-homebrew)でインストールします。
94
+
95
+ ```bash
96
+ brew install openai/tools/tunnel-client
97
+ tunnel-client --version
98
+ ```
99
+
100
+ 他のOSは[公式配布先](https://github.com/openai/tunnel-client/releases/latest)を参照。[Tunnel設定](https://platform.openai.com/settings/organization/tunnels)で利用するChatGPT workspaceに関連付けたTunnel IDと、Tunnels Read + Use権限の[実行用APIキー](https://platform.openai.com/settings/organization/api-keys)を用意します。
101
+
102
+ 3. **手元のPCで接続を起動する。** `<tunnel_id>`と`<runtime_api_key>`を取得した値に置き換えます。
103
+
104
+ ```bash
105
+ export CONTROL_PLANE_API_KEY="<runtime_api_key>"
106
+ tunnel-client init \
107
+ --sample sample_mcp_stdio_local \
108
+ --profile kiokuko-chatgpt \
109
+ --tunnel-id "<tunnel_id>" \
110
+ --mcp-command "kiokuko mcp --profile chatgpt-memory --access read-write"
111
+ tunnel-client doctor --profile kiokuko-chatgpt --explain
112
+ kiokuko chatgpt run --profile kiokuko-chatgpt
113
+ ```
114
+
115
+ 利用中は起動したままにします。別の端末で起動する場合はAPIキーを再設定し、最後の`run`を実行します。
116
+
117
+ 4. **ChatGPTに登録する。** 設定 → **Security and login → Developer mode**を有効化。**Plugins → +**で名前を`Kiokuko`、説明を「記憶の保存と検索」にし、**Connection → Tunnel**で同じIDを指定します。新しい会話のツールメニューからKiokukoを選びます。[公式の画面手順](https://developers.openai.com/plugins/deploy/connect-chatgpt)
118
+
119
+ 使い方: 「この内容をKiokukoに保存して」「Kiokukoから○○についての記憶を探して」。書き込み確認が出たら内容を確認して承認します。
120
+
121
+ 検索だけなら起動コマンドの`read-write`を`read`に変更します。ChatGPT標準メモリの保存先は変わりません。**ChatGPT実機での接続確認は未実施**です。[困ったとき](chatgpt.ja.md)
122
+
@@ -0,0 +1,107 @@
1
+ # 설정 및 문제 해결
2
+
3
+ <a id="setup-messages"></a>
4
+
5
+ ### npm 알림과 설정 오류
6
+
7
+ `install scripts not yet covered by allowScripts`는 해당 의존성 스크립트의 실행 승인이 npm에 기록되지 않았다는 뜻입니다.
8
+ `esbuild`는 빌드 도구이고, `fsevents`는 macOS 파일 감시에 사용됩니다. 이 알림만으로 설정이 실패했다고 볼 수는 없습니다.
9
+
10
+ 알림이 발생한 패키지 디렉터리에서 확인하세요.
11
+
12
+ ```bash
13
+ npm install-scripts ls
14
+ ```
15
+
16
+ `esbuild`와 `fsevents`가 표시되고, 스크립트를 검토한 뒤 실행을 허용하려면 다음 명령으로 승인을 기록하세요.
17
+
18
+ ```bash
19
+ npm install-scripts approve esbuild fsevents
20
+ ```
21
+
22
+ 승인은 해당 디렉터리의 `package.json`에 저장됩니다. macOS에 Kiokuko를 전역 설치했다면 오류에 표시된 Kiokuko 설치 디렉터리에서 실행하세요.
23
+ 다른 프로젝트에서 실행하면 그 프로젝트의 승인 설정을 조회하고 변경합니다.
24
+ 자세한 내용은 [npm 스크립트 승인 안내](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/)를 참조하세요.
25
+
26
+ 설정이 `Local semantic retrieval dependencies remain unavailable`과 `Cannot find package ... @huggingface/hub/index.js`로 끝나면,
27
+ 임베딩 런타임을 불러오지 못해 semantic 검색 설정이 완료되지 않은 상태입니다. 스크립트 승인으로 이 불러오기 오류가 해결되는지는 확인되지 않았습니다.
28
+ 도움을 요청할 때는 전체 오류와 `kiokuko --version`, `node --version`, `npm --version`의 출력을 첨부하세요.
29
+
30
+ ### 저장소 지침 파일
31
+
32
+ `kiokuko use`는 저장소의 `AGENTS.md` 또는 설정한 지침 파일에 짧고 안정적인 참조를 두며,
33
+ 생성된 지침은 `.kiokuko/AGENTS.md`에 저장합니다. 템플릿과 저장소 식별 정보의 변경은 생성 파일에 반영하고,
34
+ 이전 버전의 관리 블록은 다음 use/setup 갱신에서 참조로 바뀝니다. 사용자 지침은 Kiokuko 관리 마커 밖에 두십시오.
35
+ 사용자 텍스트와 다른 제품의 영역은 보존합니다.
36
+
37
+ 일반 setup은 누락된 루트 지침 파일을 건너뜁니다. 일반 `kiokuko doctor`는 등록된 저장소에서 누락된
38
+ 루트 지침 및 생성 지침 파일을 TTY와 비TTY 실행 모두에서 확인 대기나 추가 복구 플래그 없이 자동 생성합니다.
39
+ 등록된 저장소 ID, workspace, binding, 정규 경로가 일치해야 합니다. 없는 파일만 생성하고 기존 사용자 내용을 보존하며,
40
+ 삭제된 사용자 지침을 복원할 수는 없습니다. 권한 부족, 안전하지 않은 심볼릭 링크, 동시 변경은 대상별로 보고하고
41
+ 다른 대상의 처리를 계속합니다. 누락되거나 충돌하는 binding은 추측해서 대체하지 않고 진단합니다.
42
+
43
+ ```bash
44
+ kiokuko doctor
45
+ kiokuko doctor --json
46
+ kiokuko doctor --fix --repair-root /absolute/path/to/project
47
+ ```
48
+
49
+ `kiokuko doctor --json`은 누락된 지침을 생성하지 않고 진단합니다. `--fix`는 등록된 binding을 명시적으로 복구하는 모드이며,
50
+ `--repair-root`에는 `--fix`가 필요합니다. `--fix --json`도 binding 복구를 수행합니다.
51
+ 기존 관리 영역의 갱신은 별도의 대화형 확인이 필요하며 비TTY 실행은 승인으로 간주하지 않습니다.
52
+ 누락된 생성 지침은 use/setup으로도 복원할 수 있습니다. 제거 시 두 파일에서 Kiokuko 관리 영역만 삭제합니다.
53
+ 자세한 내용은 [CLI 계약(영문)](cli-contract.md)을 참조하십시오.
54
+
55
+ ## 제거
56
+
57
+ Kiokuko를 사용하는 클라이언트와 `kiokuko serve`를 먼저 종료하세요.
58
+
59
+ ```bash
60
+ kiokuko uninstall --dry-run
61
+ kiokuko uninstall
62
+ # 모든 에이전트를 선택하고 정리가 완료되면 표시된 명령을 실행합니다:
63
+ npm uninstall --global kiokuko
64
+ ```
65
+
66
+ ↑↓로 이동하고 Space로 선택을 전환하며 Enter로 확정하고 Esc로 취소합니다. 처음에는 모두 선택 해제되어 있습니다.
67
+ 선택한 에이전트의 관리 설정과 Skill을 제거합니다. **4개 에이전트를 모두 선택하면 기억 DB, 임베딩 모델, 프로젝트 연결도 삭제**하고 npm 제거 명령을 표시합니다. 일부만 선택하면 공유 데이터와 npm 패키지를 유지합니다. 사용자 내용은 보존합니다.
68
+ 스크립트에서는 `kiokuko uninstall --clients opencode,claude`, 완전 제거에는 `kiokuko uninstall --all`을 사용하세요. 사용자 지정 경로는 setup과 같은 환경 변수로 실행하세요.
69
+ [삭제 범위](cli-contract.md#uninstall)를 참고하세요.
70
+
71
+ <a id="chatgpt"></a>
72
+
73
+ ## ChatGPT에서 사용하기(미리 보기)
74
+
75
+ Developer mode에서 개인용 플러그인으로 연결해 기억을 저장하고 검색합니다. 스토어 배포 버전은 없습니다.
76
+
77
+ 1. **Kiokuko를 준비합니다.** `kiokuko mcp --help`에 `--profile`과 `--access`가 있는 버전을 사용합니다. 없다면 [소스에서 설치](chatgpt.md)합니다. DB가 없으면 `kiokuko init`을 실행합니다.
78
+ 2. **Tunnel 클라이언트를 설치합니다.** macOS에서는 [공식 Homebrew 설치 방법](https://github.com/openai/tunnel-client#install-with-homebrew)을 사용합니다.
79
+
80
+ ```bash
81
+ brew install openai/tools/tunnel-client
82
+ tunnel-client --version
83
+ ```
84
+
85
+ 다른 OS는 [공식 배포 페이지](https://github.com/openai/tunnel-client/releases/latest)를 참고합니다. [Tunnel 설정](https://platform.openai.com/settings/organization/tunnels)에서 ChatGPT workspace에 연결된 Tunnel ID와 Tunnels Read + Use 권한이 있는 [실행용 API 키](https://platform.openai.com/settings/organization/api-keys)를 준비합니다.
86
+
87
+ 3. **컴퓨터에서 연결을 시작합니다.** `<tunnel_id>`와 `<runtime_api_key>`를 발급받은 값으로 바꿉니다.
88
+
89
+ ```bash
90
+ export CONTROL_PLANE_API_KEY="<runtime_api_key>"
91
+ tunnel-client init \
92
+ --sample sample_mcp_stdio_local \
93
+ --profile kiokuko-chatgpt \
94
+ --tunnel-id "<tunnel_id>" \
95
+ --mcp-command "kiokuko mcp --profile chatgpt-memory --access read-write"
96
+ tunnel-client doctor --profile kiokuko-chatgpt --explain
97
+ kiokuko chatgpt run --profile kiokuko-chatgpt
98
+ ```
99
+
100
+ 사용하는 동안 계속 실행해 둡니다. 새 터미널에서는 API 키를 다시 설정한 뒤 마지막 `run` 명령을 실행합니다.
101
+
102
+ 4. **ChatGPT에 등록합니다.** **Settings → Security and login → Developer mode**를 켭니다. **Plugins → +**에서 이름을 `Kiokuko`, 설명을 “기억 저장 및 검색”으로 입력하고 **Connection → Tunnel**에 같은 ID를 지정합니다. 새 대화의 도구 메뉴에서 Kiokuko를 선택합니다. [공식 화면 안내](https://developers.openai.com/plugins/deploy/connect-chatgpt)
103
+
104
+ 사용 예: “이 내용을 Kiokuko에 저장해 줘” 또는 “Kiokuko에서 [주제]에 관한 기억을 찾아 줘”. 쓰기 확인이 나오면 내용을 확인하고 승인합니다.
105
+
106
+ 검색만 사용하려면 실행 명령의 `read-write`를 `read`로 바꿉니다. ChatGPT 기본 메모리의 저장소는 바뀌지 않습니다. **ChatGPT 실제 연결 시험은 아직 하지 않았습니다.** [문제 해결](chatgpt.md)
107
+
@@ -0,0 +1,133 @@
1
+ # Setup and troubleshooting
2
+
3
+ <a id="setup-messages"></a>
4
+
5
+ ### npm notices and setup errors
6
+
7
+ `install scripts not yet covered by allowScripts` means npm has no recorded
8
+ approval for those dependency scripts. `esbuild` is a build tool; `fsevents`
9
+ supports macOS file watching. The notice alone does not mean setup failed.
10
+
11
+ Run this in the package directory that produced the notice:
12
+
13
+ ```bash
14
+ npm install-scripts ls
15
+ ```
16
+
17
+ If it lists `esbuild` and `fsevents`, and you have reviewed and want to allow their
18
+ scripts, record approval with:
19
+
20
+ ```bash
21
+ npm install-scripts approve esbuild fsevents
22
+ ```
23
+
24
+ Approval updates that directory's `package.json`. For a global macOS Kiokuko
25
+ install, use the installed Kiokuko directory shown in the error; running these
26
+ commands in another project reviews and changes that project's policy.
27
+ See [npm's script approval guide](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/).
28
+
29
+ If setup ends with `Local semantic retrieval dependencies remain unavailable`
30
+ and `Cannot find package ... @huggingface/hub/index.js`, the embedding runtime
31
+ could not load and semantic setup is incomplete. Script approval is not a
32
+ confirmed fix for this import error. Report the full error and the output of
33
+ `kiokuko --version`, `node --version`, and `npm --version` when requesting help.
34
+
35
+ ### Saved runtime for Codex
36
+
37
+ To keep Codex MCP and lifecycle hooks on one version while npm replaces its installation, prepare a separate runtime in a private application-data directory. Finish current work and stop Codex before changing its configuration:
38
+
39
+ ```bash
40
+ kiokuko runtime-prepare --runtime-root "$HOME/Library/Application Support/Kiokuko/runtimes" --json
41
+ kiokuko setup --clients codex --no-embeddings --no-standard-skills --runtime-manifest /absolute/path/to/runtime/manifest.json --client-stopped
42
+ kiokuko runtime-diagnose --manifest /absolute/path/to/runtime/manifest.json --json
43
+ ```
44
+
45
+ On Linux, use `${XDG_DATA_HOME:-$HOME/.local/share}/kiokuko/runtimes` as the runtime root. Replace the manifest example with the `manifestPath` printed by the first command. If the current Node executable depends on libraries outside its own binary, preparation fails; supply a standalone Node binary with `--node /absolute/path/to/node`. Preparation never changes client settings. The setup command verifies the saved files, updates the managed MCP and all lifecycle hooks together, and restores previous configuration files if the update fails. Restart Codex only when the diagnostic reports `readyForRestart: true`. Existing custom MCP commands are preserved and require separate migration.
46
+
47
+ An npm update alone does not switch the saved version. To upgrade, stop Codex after current work, prepare the new version, run the setup command with its new manifest, then restart. Keep the old saved directory for recovery; old versions are not deleted automatically. If the new version migrated the memory database, check database compatibility before returning to an older version. Allow several hundred megabytes per saved version, depending on Node and installed optional dependencies; check the actual directory size before keeping multiple versions.
48
+
49
+ ### Repository instruction files
50
+
51
+ `kiokuko use` keeps a short, stable pointer in the repository's `AGENTS.md`
52
+ (or the configured agent file). Generated instructions live in `.kiokuko/AGENTS.md`.
53
+ Template and repository identity updates refresh that generated file; older
54
+ versioned blocks migrate to the pointer on the next use/setup refresh. Keep custom
55
+ instructions outside Kiokuko's managed markers; user text and other products'
56
+ sections are preserved.
57
+
58
+ Routine setup skips a missing root instruction file. Ordinary `kiokuko doctor`
59
+ automatically creates missing registered root/generated instruction files, in both
60
+ TTY and non-TTY use, without a confirmation prompt or an extra repair flag.
61
+ Recovery requires a matching registered repository ID, workspace, binding and
62
+ canonical path. It creates only absent files, preserves existing custom content,
63
+ and cannot restore deleted custom instructions. Permission failures, unsafe
64
+ symlinks and concurrent changes are reported for each target while other targets
65
+ continue. Missing/conflicting bindings are diagnosed rather than guessed.
66
+
67
+ ```bash
68
+ kiokuko doctor
69
+ kiokuko doctor --json
70
+ kiokuko doctor --fix --repair-root /absolute/path/to/project
71
+ ```
72
+
73
+ `kiokuko doctor --json` diagnoses without creating missing instructions. `--fix`
74
+ is the explicit registered-binding repair mode; `--repair-root` requires `--fix`.
75
+ Combining `--fix` with `--json` still permits that binding repair. Existing section
76
+ updates remain a separate interactive confirmation; non-TTY use does not approve
77
+ them. Missing generated instructions can also be restored by use/setup. Uninstall
78
+ removes only Kiokuko's managed regions from both files. See
79
+ [the CLI contract](cli-contract.md) for repair details.
80
+
81
+ ## Uninstall
82
+
83
+ Stop clients using Kiokuko and any `kiokuko serve` process first.
84
+
85
+ ```bash
86
+ kiokuko uninstall --dry-run
87
+ kiokuko uninstall
88
+ # After selecting all agents and completing cleanup, run the printed command:
89
+ npm uninstall --global kiokuko
90
+ ```
91
+
92
+ Use Up/Down to move, Space to toggle, Enter to submit, and Esc to cancel. All choices start unchecked.
93
+ Only selected agents' managed settings and Skills are removed. **Selecting all four also deletes shared memory, embedding models, and managed project bindings**, then prints the npm removal command. Partial selection retains shared data and the npm package. User content is preserved.
94
+ For scripts, use `kiokuko uninstall --clients opencode,claude` or `kiokuko uninstall --all` for complete cleanup.
95
+ Use the same environment overrides as setup for custom locations. See [cleanup scope and failures](cli-contract.md#uninstall).
96
+
97
+ <a id="chatgpt"></a>
98
+
99
+ ## Use with ChatGPT (preview)
100
+
101
+ Connect a personal plugin in Developer mode to save and recall memory. No store-distributed plugin is available.
102
+
103
+ 1. **Prepare Kiokuko.** Use a version whose `kiokuko mcp --help` lists `--profile` and `--access`; otherwise [install from source](chatgpt.md). Run `kiokuko init` if you do not have a database.
104
+ 2. **Install the Tunnel client.** On macOS, use the [official Homebrew instructions](https://github.com/openai/tunnel-client#install-with-homebrew):
105
+
106
+ ```bash
107
+ brew install openai/tools/tunnel-client
108
+ tunnel-client --version
109
+ ```
110
+
111
+ For other operating systems, see the [official releases](https://github.com/openai/tunnel-client/releases/latest). In [Tunnel settings](https://platform.openai.com/settings/organization/tunnels), obtain a Tunnel ID associated with your ChatGPT workspace and a [runtime API key](https://platform.openai.com/settings/organization/api-keys) with Tunnels Read + Use permission.
112
+
113
+ 3. **Start the connection on your computer.** Replace `<tunnel_id>` and `<runtime_api_key>` with your values.
114
+
115
+ ```bash
116
+ export CONTROL_PLANE_API_KEY="<runtime_api_key>"
117
+ tunnel-client init \
118
+ --sample sample_mcp_stdio_local \
119
+ --profile kiokuko-chatgpt \
120
+ --tunnel-id "<tunnel_id>" \
121
+ --mcp-command "kiokuko mcp --profile chatgpt-memory --access read-write"
122
+ tunnel-client doctor --profile kiokuko-chatgpt --explain
123
+ kiokuko chatgpt run --profile kiokuko-chatgpt
124
+ ```
125
+
126
+ Keep it running while using the connection. In a new terminal, set the API key again and execute the final `run` command.
127
+
128
+ 4. **Register in ChatGPT.** Enable **Settings → Security and login → Developer mode**. Under **Plugins → +**, name it `Kiokuko`, describe it as “Save and recall memory”, and choose **Connection → Tunnel** with the same ID. Select Kiokuko from the tools menu in a new conversation. [Official UI instructions](https://developers.openai.com/plugins/deploy/connect-chatgpt)
129
+
130
+ Try: “Save this information in Kiokuko” or “Search Kiokuko for memories about [topic].” Review and approve write requests when prompted.
131
+
132
+ For search only, change `read-write` to `read` in the launch command. This does not change ChatGPT's built-in memory storage. **Live ChatGPT connection testing is pending.** [Troubleshooting](chatgpt.md)
133
+
@@ -0,0 +1,107 @@
1
+ # 设置与故障排查
2
+
3
+ <a id="setup-messages"></a>
4
+
5
+ ### npm 提示与设置错误
6
+
7
+ `install scripts not yet covered by allowScripts` 表示 npm 尚未记录这些依赖脚本的执行许可。
8
+ `esbuild` 是构建工具,`fsevents` 用于 macOS 文件监控。仅出现此提示不代表设置失败。
9
+
10
+ 在产生提示的包目录中运行:
11
+
12
+ ```bash
13
+ npm install-scripts ls
14
+ ```
15
+
16
+ 如果列出了 `esbuild` 和 `fsevents`,并且你已检查脚本、决定允许执行,可运行:
17
+
18
+ ```bash
19
+ npm install-scripts approve esbuild fsevents
20
+ ```
21
+
22
+ 许可会写入该目录的 `package.json`。在 macOS 上全局安装 Kiokuko 时,请在错误信息显示的 Kiokuko 安装目录中操作;
23
+ 在其他项目中运行这些命令,查看和修改的是那个项目的许可设置。
24
+ 详情请参阅 [npm 脚本许可指南](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/)。
25
+
26
+ 如果设置最终报出 `Local semantic retrieval dependencies remain unavailable` 和 `Cannot find package ... @huggingface/hub/index.js`,
27
+ 说明嵌入运行时无法加载,semantic 检索尚未配置完成。尚未确认批准脚本能解决此导入错误。
28
+ 寻求帮助时,请附上完整错误信息以及 `kiokuko --version`、`node --version`、`npm --version` 的输出。
29
+
30
+ ### 仓库指令文件
31
+
32
+ `kiokuko use`在仓库的`AGENTS.md`(或配置的指令文件)中保留简短、稳定的引用,
33
+ 生成的指令存放在`.kiokuko/AGENTS.md`。模板及仓库身份更新会刷新生成文件;
34
+ 旧的带版本管理块会在下次use/setup更新时迁移为引用。请将自定义指令放在Kiokuko管理标记之外;
35
+ 用户文本和其他产品的内容会保留。
36
+
37
+ 常规setup会跳过缺失的根指令文件。普通`kiokuko doctor`在交互式和非TTY运行中,
38
+ 都会自动创建已注册仓库缺失的根指令及生成指令文件,无需确认或额外修复标志。
39
+ 前提是注册仓库ID、workspace、binding及规范路径一致。恢复只创建缺失文件,保留已有自定义内容,
40
+ 无法恢复已删除的自定义指令。权限不足、不安全的符号链接和并发修改会按目标报告,
41
+ 并继续处理其他目标。缺失或冲突的binding仅被诊断,不会凭猜测替换。
42
+
43
+ ```bash
44
+ kiokuko doctor
45
+ kiokuko doctor --json
46
+ kiokuko doctor --fix --repair-root /absolute/path/to/project
47
+ ```
48
+
49
+ `kiokuko doctor --json`只诊断,不创建缺失指令。`--fix`是显式修复已注册binding的模式;
50
+ `--repair-root`必须配合`--fix`使用。`--fix --json`仍会执行binding修复。
51
+ 更新现有管理部分仍需单独的交互确认,非TTY运行不视为批准。
52
+ 缺失的生成指令也可通过use/setup恢复。卸载只移除两个文件中的Kiokuko管理部分。
53
+ 详见[CLI契约(英文)](cli-contract.md)。
54
+
55
+ ## 卸载
56
+
57
+ 先退出使用 Kiokuko 的客户端和 `kiokuko serve`。
58
+
59
+ ```bash
60
+ kiokuko uninstall --dry-run
61
+ kiokuko uninstall
62
+ # 选中全部代理并完成清理后,执行最后显示的命令:
63
+ npm uninstall --global kiokuko
64
+ ```
65
+
66
+ ↑↓ 移动,Space 切换选择,Enter 确认,Esc 取消。默认全部未选中。
67
+ 仅删除所选代理的受管理配置和 Skill。**选中全部四个代理时,还会删除共享记忆数据库、嵌入模型和项目绑定**,最后显示 npm 卸载命令。部分选择会保留共享数据和 npm 包。用户内容保持不变。
68
+ 脚本中使用 `kiokuko uninstall --clients opencode,claude`,完全清理使用 `kiokuko uninstall --all`。自定义路径需要使用与 setup 相同的环境变量。
69
+ 详见[清理范围](cli-contract.md#uninstall)。
70
+
71
+ <a id="chatgpt"></a>
72
+
73
+ ## 在 ChatGPT 中使用(预览)
74
+
75
+ 通过 Developer mode 添加个人插件连接,保存和搜索记忆。目前没有商店分发版。
76
+
77
+ 1. **准备 Kiokuko。** 使用 `kiokuko mcp --help` 中包含 `--profile` 和 `--access` 的版本;否则[从源码安装](chatgpt.md)。尚无数据库时运行 `kiokuko init`。
78
+ 2. **安装 Tunnel 客户端。** macOS 使用[官方 Homebrew 安装方式](https://github.com/openai/tunnel-client#install-with-homebrew):
79
+
80
+ ```bash
81
+ brew install openai/tools/tunnel-client
82
+ tunnel-client --version
83
+ ```
84
+
85
+ 其他系统参见[官方发布页](https://github.com/openai/tunnel-client/releases/latest)。在 [Tunnel 设置](https://platform.openai.com/settings/organization/tunnels)中准备关联到 ChatGPT workspace 的 Tunnel ID,以及具有 Tunnels Read + Use 权限的[运行用 API 密钥](https://platform.openai.com/settings/organization/api-keys)。
86
+
87
+ 3. **在电脑上启动连接。** 将 `<tunnel_id>` 和 `<runtime_api_key>` 替换为取得的值。
88
+
89
+ ```bash
90
+ export CONTROL_PLANE_API_KEY="<runtime_api_key>"
91
+ tunnel-client init \
92
+ --sample sample_mcp_stdio_local \
93
+ --profile kiokuko-chatgpt \
94
+ --tunnel-id "<tunnel_id>" \
95
+ --mcp-command "kiokuko mcp --profile chatgpt-memory --access read-write"
96
+ tunnel-client doctor --profile kiokuko-chatgpt --explain
97
+ kiokuko chatgpt run --profile kiokuko-chatgpt
98
+ ```
99
+
100
+ 使用期间保持运行。在新终端中,先重新设置 API 密钥,再执行最后一行 `run` 命令。
101
+
102
+ 4. **在 ChatGPT 中添加。** 开启 **Settings → Security and login → Developer mode**。在 **Plugins → +** 中填写名称 `Kiokuko`、说明“保存和搜索记忆”,再通过 **Connection → Tunnel** 指定同一个 ID。在新对话的工具菜单中选择 Kiokuko。[官方界面步骤](https://developers.openai.com/plugins/deploy/connect-chatgpt)
103
+
104
+ 使用示例:“把这些内容保存到 Kiokuko”或“在 Kiokuko 中查找关于[主题]的记忆”。出现写入确认时,检查内容后批准。
105
+
106
+ 只需搜索时,将启动命令中的 `read-write` 改为 `read`。这不会更改 ChatGPT 内置记忆的保存位置。**尚未在 ChatGPT 中实测连接。** [故障排查](chatgpt.md)
107
+
@@ -0,0 +1,26 @@
1
+ -- Raw code evidence is operational history, never an approved memory or execution permission.
2
+ CREATE TABLE code_version_evidence (
3
+ version_id TEXT PRIMARY KEY,
4
+ evidence_id TEXT NOT NULL UNIQUE REFERENCES ledger_evidence(evidence_id) ON DELETE CASCADE,
5
+ run_id TEXT NOT NULL REFERENCES ledger_runs(run_id) ON DELETE CASCADE,
6
+ entry_id TEXT REFERENCES entries(id) ON DELETE CASCADE,
7
+ workspace TEXT NOT NULL,
8
+ repository_id TEXT NOT NULL REFERENCES repositories(repository_id) ON DELETE CASCADE,
9
+ owner_id TEXT NOT NULL,
10
+ branch TEXT,
11
+ parent_version_id TEXT,
12
+ path TEXT NOT NULL,
13
+ reported_outcome TEXT NOT NULL CHECK(reported_outcome IN ('accepted','rejected','failed','unknown')),
14
+ reason TEXT NOT NULL,
15
+ environment_json TEXT NOT NULL CHECK(json_valid(environment_json)),
16
+ required_environment_json TEXT CHECK(required_environment_json IS NULL OR json_valid(required_environment_json)),
17
+ diff_text TEXT NOT NULL,
18
+ diff_digest TEXT NOT NULL CHECK(length(diff_digest)=64),
19
+ binding_digest TEXT NOT NULL CHECK(length(binding_digest)=64),
20
+ created_at TEXT NOT NULL
21
+ ) STRICT;
22
+ CREATE INDEX code_version_recall ON code_version_evidence(owner_id,repository_id,workspace,branch,entry_id,created_at DESC,version_id ASC);
23
+ CREATE TRIGGER code_version_immutable BEFORE UPDATE ON code_version_evidence
24
+ BEGIN SELECT RAISE(ABORT,'Code version evidence is immutable'); END;
25
+
26
+ CREATE INDEX entry_supersession_history ON entries(workspace,superseded_by,id) WHERE status='superseded';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kiokuko",
3
- "version": "1.0.41",
3
+ "version": "1.0.44",
4
4
  "description": "Model-agnostic external memory for AI coding agents",
5
5
  "type": "module",
6
6
  "bin": {