kiokuko 1.0.43 → 1.0.44

package/README.ja.md

@@ -1,177 +1,39 @@
 # Kiokuko（記憶庫）
 
-1.0では旧DBを利用できません。新規DBで開始してください。[破壊的変更と旧設定の撤去手順](docs/breaking-changes-1.0.md)を参照してください。
-
 [English](README.md) | 日本語 | [简体中文](README.zh-CN.md) | [한국어](README.ko.md)
 
-**MCPで接続し、必要な記憶を検索し、作業後に知識を蓄積する。**
-
-KiokukoはAIコーディングエージェント向けのローカル外部メモリです。SQLiteに知識を保存し、
-次のタスクに関係する文脈を検索し、作業結果から再利用できる知識を記録します。
+AIエージェント用のローカルメモリです。好み・判断・訂正をSQLiteに保存し、
+必要な文脈をMCP経由で検索します。
 
-## 基本概念
-
-```text
-依頼 → MCP接続 → 関係する記憶を検索 → 作業
-                                  ↓
-                         再利用できる知識を保存
-```
+**Codex・OpenCode・Claude Code・Hermes Agent**に対応。
+[ChatGPTへの接続はプレビュー版です](docs/setup-notes.ja.md#chatgpt)。
 
-記憶はProject・Ecosystem・Globalに分離されます。現在のコード、設定、実行結果が過去の記憶より優先されます。
+## インストール
 
-## 最短セットアップ
-
-Node.js 24.16.0以上が必要です（Node.js 26.1.0以上にも対応）。
+Node.js **24.16.0以上**が必要です。
 
 ```bash
-npm install --global kiokuko
+npm i -g kiokuko
 kiokuko setup
 ```
 
-`setup`はローカルDB・標準Skill・MCP接続に加えて、ローカルsemantic検索も設定します。
-初回は埋め込みランタイムとモデルを導入します。
-起動中のクライアントは、設定後に一度再起動してください。正確な設定規則は
-[導入ガイド](docs/getting-started.ja.md)を参照してください。
-
-埋め込みランタイムとモデルを導入せず、クライアント設定だけ行う場合:
+クライアントを再起動すれば、あとは普段どおり使えます。MCP・標準Skill・
+ローカルsemantic検索を設定します。埋め込みモデルのダウンロードを省く場合は
+`kiokuko setup --no-embeddings`を使ってください。
 
-```bash
-kiokuko setup --no-embeddings
-```
+1.0未満からの更新には新規DBが必要です。
+[移行と旧設定の撤去](docs/breaking-changes-1.0.md)。
 
-埋め込みのセットアップを省略します。既存の埋め込み設定は変更しません。
+## ドキュメント
 
 <a id="setup-messages"></a>
 
-### npmの通知とセットアップエラー
-
-`install scripts not yet covered by allowScripts`は、依存パッケージのスクリプトに実行許可が記録されていないという通知です。
-`esbuild`はビルドツール、`fsevents`はmacOSのファイル監視用です。この通知だけではセットアップの失敗とは限りません。
-
-通知が出たパッケージのディレクトリで確認します。
-
-```bash
-npm install-scripts ls
-```
-
-`esbuild`と`fsevents`が表示され、スクリプトを確認したうえで実行を許可する場合は、次のコマンドで記録します。
-
-```bash
-npm install-scripts approve esbuild fsevents
-```
-
-許可はそのディレクトリの`package.json`に保存されます。macOSでKiokukoをグローバルインストールした場合は、エラーに表示されたKiokukoのインストール先で実行してください。
-別のプロジェクトで実行すると、そのプロジェクトの許可設定を確認・変更します。
-詳しくは[npmのスクリプト許可ガイド](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/)を参照してください。
-
-最後に`Local semantic retrieval dependencies remain unavailable`と`Cannot find package ... @huggingface/hub/index.js`が出た場合は、
-埋め込みランタイムを読み込めず、semantic検索の設定が完了していません。スクリプトの許可でこの読み込みエラーが直るとは確認できていません。
-問い合わせる際は、エラー全文と`kiokuko --version`、`node --version`、`npm --version`の結果を添えてください。
-
-### Codex用の保存済み実行版
-
-npmの導入先が置き換わってもCodexのMCPとライフサイクルhookを同じ版で動かすには、ユーザー専用のアプリケーションデータ領域に実行版を用意します。進行中の作業を終え、Codexを停止してから設定を切り替えてください。
-
-```bash
-kiokuko runtime-prepare --runtime-root "$HOME/Library/Application Support/Kiokuko/runtimes" --json
-kiokuko setup --clients codex --no-embeddings --no-standard-skills --runtime-manifest /absolute/path/to/runtime/manifest.json --client-stopped
-kiokuko runtime-diagnose --manifest /absolute/path/to/runtime/manifest.json --json
-```
-
-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起動コマンドは保持され、別途移行が必要です。
-
-npmを更新しただけでは使用版は切り替わりません。更新時は作業を終えてCodexを停止し、新版を準備して、そのmanifestで`setup`を実行してから再起動します。旧実行版は自動削除しません。新版がメモリDBをmigrationした後に旧版へ戻す場合は、先にDB互換性を確認してください。保存容量はNodeと導入済みの任意依存によって変わりますが、1版につき数百MBを見込み、複数版を残す前に実際の容量を確認してください。
-
-## アンインストール
-
-Kiokukoを使うクライアントと`kiokuko serve`を終了してから実行します。
-
-```bash
-kiokuko uninstall --dry-run
-kiokuko uninstall
-# 全エージェントを選択して正常終了後、最後に表示されたコマンドを実行
-npm uninstall --global kiokuko
-```
-
-↑↓で移動、Spaceで選択を切り替え、Enterで確定、Escで中止します。初期状態は未選択です。
-選択したエージェントの管理設定・Skillだけを削除します。**全4エージェントを選ぶと記憶DB・埋め込みモデル・登録済みプロジェクトの管理部分も削除**し、最後にnpmの削除コマンドを表示します。一部だけを選んだ場合は共有データとnpmパッケージを残します。ユーザーが書いた内容は保持します。
-スクリプトでは `kiokuko uninstall --clients opencode,claude`、完全削除には `kiokuko uninstall --all` を使います。
-独自の配置先を指定していた場合は、セットアップ時と同じ環境変数で実行してください。[削除範囲と失敗時の扱い](docs/cli-contract.md#uninstall)
-
-## 主な機能
-
-- **RAGメモリ**: lexical検索に加え、`setup`でローカルsemantic検索を設定。
-- **Akinator**: 曖昧な依頼を作業前に具体化。
-- **ローカルWeb UI**: 保存した記憶の確認と整理。
-- **参照専用Skill**: 外部Skillは検証して保存するが、自動実行しない。
-
-`kiokuko embeddings setup`は、`kiokuko setup`と同じ処理を行う互換コマンドとして利用できます。
-
-managed MCP blockと登録済みプロジェクトのinstructionsを更新します。unmanaged identityの置換は対話確認後だけ行い、
-非対話または`--dry-run --json`では変更せずfail closedします。詳細は
-[semantic retrievalガイド](docs/semantic-retrieval.ja.md)を参照してください。
-
-## 対応クライアント
-
-Codex、OpenCode、Claude Code、Hermes Agentに対応しています。client別の設定、再起動、Web UIは
-[導入ガイド](docs/getting-started.ja.md)にまとめています。
-
-セッションの記録には[AgenticReplay](docs/agenticreplay.ja.md)を使い、Kiokukoに接続する
-クライアントをレコーダーから起動します。任意で使うツールで、別途インストールします。
-
-## ChatGPTで使う（プレビュー）
-
-Developer modeで自分用プラグインとして接続し、記憶を保存・検索します。ストア配布版はありません。
-
-1. **Kiokukoを準備する。** `kiokuko mcp --help`に`--profile`と`--access`がある版を使います。なければ[ソース版を導入](docs/chatgpt.ja.md)。DBが未作成なら`kiokuko init`を実行します。
-2. **Tunnelクライアントを入れる。** macOSでは[公式Homebrew手順](https://github.com/openai/tunnel-client#install-with-homebrew)でインストールします。
-
-   ```bash
-   brew install openai/tools/tunnel-client
-   tunnel-client --version
-   ```
-
-   他の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)を用意します。
-
-3. **手元のPCで接続を起動する。** `<tunnel_id>`と`<runtime_api_key>`を取得した値に置き換えます。
-
-   ```bash
-   export CONTROL_PLANE_API_KEY="<runtime_api_key>"
-   tunnel-client init \
-     --sample sample_mcp_stdio_local \
-     --profile kiokuko-chatgpt \
-     --tunnel-id "<tunnel_id>" \
-     --mcp-command "kiokuko mcp --profile chatgpt-memory --access read-write"
-   tunnel-client doctor --profile kiokuko-chatgpt --explain
-   kiokuko chatgpt run --profile kiokuko-chatgpt
-   ```
-
-   利用中は起動したままにします。別の端末で起動する場合はAPIキーを再設定し、最後の`run`を実行します。
-
-4. **ChatGPTに登録する。** 設定 → **Security and login → Developer mode**を有効化。**Plugins → ＋**で名前を`Kiokuko`、説明を「記憶の保存と検索」にし、**Connection → Tunnel**で同じIDを指定します。新しい会話のツールメニューからKiokukoを選びます。[公式の画面手順](https://developers.openai.com/plugins/deploy/connect-chatgpt)
-
-使い方: 「この内容をKiokukoに保存して」「Kiokukoから○○についての記憶を探して」。書き込み確認が出たら内容を確認して承認します。
-
-検索だけなら起動コマンドの`read-write`を`read`に変更します。ChatGPT標準メモリの保存先は変わりません。**ChatGPT実機での接続確認は未実施**です。[困ったとき](docs/chatgpt.ja.md)
-
-## 安全性と制約
-
-会話全文は保存せず、パスワード、API key、token、秘密鍵に似た内容を拒否します。保存された記憶は参考情報であり、
-現在のリポジトリと実行結果で確認してください。
-
-MCPの利用はclientとモデルが決めるため、**毎回必ずKiokukoが呼ばれる保証はありません**。信頼境界と公開エラーは
-[Security and trust](docs/security-and-trust.ja.md)で説明しています。
-
-## 詳細ドキュメント
-
-- [ドキュメント目次](docs/README.ja.md)
 - [導入ガイド](docs/getting-started.ja.md)
-- [基本概念](docs/concepts.ja.md)
-- [Semantic retrieval](docs/semantic-retrieval.ja.md)
-- [Akinator のプロフィール補助](docs/akinator-memory.md)
-- [記憶の適用記録・検証結果・Codex フック](docs/memory-assurance.md)
-- [Security and trust](docs/security-and-trust.ja.md)
-- [CLI contract](docs/cli-contract.md)
-
-実装者向け資料は[architecture](docs/architecture.md)、[database](docs/database.md)、[execution ledger](docs/execution-ledger.md)、
-[client compatibility](docs/client-compatibility.md)を参照してください。
+- [設定・トラブルシューティング・アンインストール](docs/setup-notes.ja.md)
+- [記憶と検索](docs/concepts.ja.md)
+- [履歴とコードの証拠（英語）](docs/history-evidence.md)
+- [ドキュメント一覧](docs/README.ja.md)
+
+保存した記憶には誤りがありえます。秘密情報に見える内容は拒否し、会話全文は保存しません。
+MCPの呼び出しはクライアントとモデルの判断に依存します。
+[安全性と信頼の境界](docs/security-and-trust.ja.md)。

package/README.ko.md

@@ -1,143 +1,39 @@
 # Kiokuko (記憶庫)
 
-1.0에서는 기존 DB를 지원하지 않습니다. 새 DB를 사용하세요. [주요 변경 사항과 이전 설정 제거](docs/breaking-changes-1.0.md)를 확인하세요。
-
 [English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | 한국어
 
-**MCP로 연결하고, 필요한 기억을 검색하고, 작업 후 지식을 축적합니다.**
-
-Kiokuko는 AI 코딩 에이전트를 위한 로컬 외부 메모리입니다. 지식을 SQLite에 저장하고 다음 작업에 관련된 문맥을 검색하며,
-재사용 가능한 결과를 기록합니다.
-
-```text
-요청 → MCP 연결 → 관련 기억 검색 → 작업 수행
-                             ↓
-                         재사용 지식 저장
-```
+AI 에이전트를 위한 로컬 메모리입니다. 선호 사항, 결정, 수정 내용을 SQLite에
+저장하고 MCP를 통해 관련 문맥을 검색합니다.
 
-기억은 Project·Ecosystem·Global로 분리되고 현재 코드, 설정, 실행 결과가 과거 기억보다 우선합니다.
+**Codex, OpenCode, Claude Code, Hermes Agent**를 지원합니다.
+[ChatGPT 연결은 미리 보기 버전입니다](docs/setup-notes.ko.md#chatgpt).
 
-## 빠른 시작
+## 설치
 
-Node.js 24.16.0 이상이 필요합니다（Node.js 26.1.0 이상도 지원）.
+Node.js **24.16.0 이상**이 필요합니다.
 
 ```bash
-npm install --global kiokuko
+npm i -g kiokuko
 kiokuko setup
 ```
 
-`setup`은 데이터베이스, 표준 Skill, MCP 연결과 로컬 semantic 검색을 설정합니다.
-처음 실행할 때 임베딩 런타임과 모델을 설치합니다. 이미 실행 중인 클라이언트는
-설정 후 재시작하십시오. 정확한 규칙은 [영문 Getting started](docs/getting-started.md)를 참조하십시오.
-
-임베딩 런타임과 모델을 설치하지 않고 클라이언트만 설정하려면:
+클라이언트를 재시작한 뒤 평소대로 사용하세요. MCP, 표준 Skill, 로컬 semantic
+검색이 설정됩니다. 임베딩 다운로드를 건너뛰려면
+`kiokuko setup --no-embeddings`를 사용하세요.
 
-```bash
-kiokuko setup --no-embeddings
-```
+1.0 이전 버전에서 업데이트하려면 새 데이터베이스가 필요합니다.
+[마이그레이션 및 이전 설정 정리](docs/breaking-changes-1.0.md).
 
-임베딩 설정 단계를 건너뛰며 기존 임베딩 설정은 변경하지 않습니다.
+## 문서
 
 <a id="setup-messages"></a>
 
-### npm 알림과 설정 오류
-
-`install scripts not yet covered by allowScripts`는 해당 의존성 스크립트의 실행 승인이 npm에 기록되지 않았다는 뜻입니다.
-`esbuild`는 빌드 도구이고, `fsevents`는 macOS 파일 감시에 사용됩니다. 이 알림만으로 설정이 실패했다고 볼 수는 없습니다.
-
-알림이 발생한 패키지 디렉터리에서 확인하세요.
-
-```bash
-npm install-scripts ls
-```
-
-`esbuild`와 `fsevents`가 표시되고, 스크립트를 검토한 뒤 실행을 허용하려면 다음 명령으로 승인을 기록하세요.
-
-```bash
-npm install-scripts approve esbuild fsevents
-```
-
-승인은 해당 디렉터리의 `package.json`에 저장됩니다. macOS에 Kiokuko를 전역 설치했다면 오류에 표시된 Kiokuko 설치 디렉터리에서 실행하세요.
-다른 프로젝트에서 실행하면 그 프로젝트의 승인 설정을 조회하고 변경합니다.
-자세한 내용은 [npm 스크립트 승인 안내](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/)를 참조하세요.
-
-설정이 `Local semantic retrieval dependencies remain unavailable`과 `Cannot find package ... @huggingface/hub/index.js`로 끝나면,
-임베딩 런타임을 불러오지 못해 semantic 검색 설정이 완료되지 않은 상태입니다. 스크립트 승인으로 이 불러오기 오류가 해결되는지는 확인되지 않았습니다.
-도움을 요청할 때는 전체 오류와 `kiokuko --version`, `node --version`, `npm --version`의 출력을 첨부하세요.
-
-## 제거
-
-Kiokuko를 사용하는 클라이언트와 `kiokuko serve`를 먼저 종료하세요.
-
-```bash
-kiokuko uninstall --dry-run
-kiokuko uninstall
-# 모든 에이전트를 선택하고 정리가 완료되면 표시된 명령을 실행합니다:
-npm uninstall --global kiokuko
-```
-
-↑↓로 이동하고 Space로 선택을 전환하며 Enter로 확정하고 Esc로 취소합니다. 처음에는 모두 선택 해제되어 있습니다.
-선택한 에이전트의 관리 설정과 Skill을 제거합니다. **4개 에이전트를 모두 선택하면 기억 DB, 임베딩 모델, 프로젝트 연결도 삭제**하고 npm 제거 명령을 표시합니다. 일부만 선택하면 공유 데이터와 npm 패키지를 유지합니다. 사용자 내용은 보존합니다.
-스크립트에서는 `kiokuko uninstall --clients opencode,claude`, 완전 제거에는 `kiokuko uninstall --all`을 사용하세요. 사용자 지정 경로는 setup과 같은 환경 변수로 실행하세요.
-[삭제 범위](docs/cli-contract.md#uninstall)를 참고하세요.
-
-## 주요 기능
-
-- RAG 기억（lexical 검색과 `setup`으로 구성하는 로컬 semantic 검색）
-- 모호한 요청을 구체화하는 Akinator
-- 기억을 검토하는 로컬 Web UI
-- 자동 실행하지 않는 검증된 참조 전용 External Skill
-
-`kiokuko embeddings setup`은 `kiokuko setup`과 동일한 처리를 하는 호환 명령으로 유지됩니다.
-
-managed MCP block과 프로젝트 instructions를 갱신합니다. unmanaged identity 교체는 대화형 확인 후에만 수행되며,
-비대화형 또는 `--dry-run --json` 실행은 변경 없이 fail closed합니다. 자세한 내용은 [영문 semantic retrieval](docs/semantic-retrieval.md)을 보십시오.
-
-## 지원 클라이언트
-
-Codex, OpenCode, Claude Code, Hermes Agent.
-
-## ChatGPT에서 사용하기(미리 보기)
-
-Developer mode에서 개인용 플러그인으로 연결해 기억을 저장하고 검색합니다. 스토어 배포 버전은 없습니다.
-
-1. **Kiokuko를 준비합니다.** `kiokuko mcp --help`에 `--profile`과 `--access`가 있는 버전을 사용합니다. 없다면 [소스에서 설치](docs/chatgpt.md)합니다. DB가 없으면 `kiokuko init`을 실행합니다.
-2. **Tunnel 클라이언트를 설치합니다.** macOS에서는 [공식 Homebrew 설치 방법](https://github.com/openai/tunnel-client#install-with-homebrew)을 사용합니다.
-
-   ```bash
-   brew install openai/tools/tunnel-client
-   tunnel-client --version
-   ```
-
-   다른 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)를 준비합니다.
-
-3. **컴퓨터에서 연결을 시작합니다.** `<tunnel_id>`와 `<runtime_api_key>`를 발급받은 값으로 바꿉니다.
-
-   ```bash
-   export CONTROL_PLANE_API_KEY="<runtime_api_key>"
-   tunnel-client init \
-     --sample sample_mcp_stdio_local \
-     --profile kiokuko-chatgpt \
-     --tunnel-id "<tunnel_id>" \
-     --mcp-command "kiokuko mcp --profile chatgpt-memory --access read-write"
-   tunnel-client doctor --profile kiokuko-chatgpt --explain
-   kiokuko chatgpt run --profile kiokuko-chatgpt
-   ```
-
-   사용하는 동안 계속 실행해 둡니다. 새 터미널에서는 API 키를 다시 설정한 뒤 마지막 `run` 명령을 실행합니다.
-
-4. **ChatGPT에 등록합니다.** **Settings → Security and login → Developer mode**를 켭니다. **Plugins → ＋**에서 이름을 `Kiokuko`, 설명을 “기억 저장 및 검색”으로 입력하고 **Connection → Tunnel**에 같은 ID를 지정합니다. 새 대화의 도구 메뉴에서 Kiokuko를 선택합니다. [공식 화면 안내](https://developers.openai.com/plugins/deploy/connect-chatgpt)
-
-사용 예: “이 내용을 Kiokuko에 저장해 줘” 또는 “Kiokuko에서 [주제]에 관한 기억을 찾아 줘”. 쓰기 확인이 나오면 내용을 확인하고 승인합니다.
-
-검색만 사용하려면 실행 명령의 `read-write`를 `read`로 바꿉니다. ChatGPT 기본 메모리의 저장소는 바뀌지 않습니다. **ChatGPT 실제 연결 시험은 아직 하지 않았습니다.** [문제 해결](docs/chatgpt.md)
-
-## 안전성과 제한
-
-전체 대화를 저장하지 않으며 비밀번호, API key, token, private key처럼 보이는 내용은 거부합니다. 기억은 참고 정보이므로 현재 코드와 실행 결과를 확인하십시오.
-
-MCP 호출 여부는 클라이언트와 모델이 결정하므로 **모든 턴에서 Kiokuko가 호출된다는 보장은 없습니다**. 자세한 신뢰 경계는 [영문 Security and trust](docs/security-and-trust.md)를 참조하십시오.
-
-## 자세한 문서
+- [시작하기 (영문)](docs/getting-started.md)
+- [설정, 문제 해결 및 제거](docs/setup-notes.ko.md)
+- [메모리와 검색 (영문)](docs/concepts.md)
+- [이력과 코드 증거 (영문)](docs/history-evidence.md)
+- [전체 문서 (영문)](docs/README.md)
 
-[영문 문서 목차](docs/README.md)에서 Getting started, Concepts, Semantic retrieval, Security and trust와 구현자용 문서로 이동할 수 있습니다.
+저장된 기억은 틀릴 수 있습니다. 비밀 정보로 보이는 내용은 거부하고 전체 대화는
+저장하지 않습니다. MCP 호출은 클라이언트와 모델의 판단에 달려 있습니다.
+[보안과 신뢰 (영문)](docs/security-and-trust.md).

package/README.md

@@ -1,214 +1,39 @@
 # Kiokuko (記憶庫)
 
-Version 1.0 requires a new database and removes the previous orchestration. See [breaking changes and setup cleanup](docs/breaking-changes-1.0.md).
-
 English | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | [한국어](README.ko.md)
 
-**Connect through MCP, learn from interaction, and recall useful context.**
-
-Kiokuko is local external memory for AI agents, for coding work and ordinary
-conversation. Your client can save durable preferences, decisions, corrections,
-and useful results as untrusted SQLite records, then recall relevant context for
-the next interaction. You keep using your client normally through MCP.
-
-## The core idea
-
-```text
-request → MCP connection → retrieve relevant memory → do the work
-                                             ↓
-                                  save reusable knowledge
-```
-
-Recall defaults to 16,000 Unicode body characters, with a separate bounded typed-relation envelope. Explicit budgets and item limits are preserved. See [context delivery](docs/context-delivery.md).
+Local memory for AI agents. Save preferences, decisions, and corrections in
+SQLite, then recall relevant context through MCP.
 
-Memory is separated into Project, Ecosystem, and Global scopes. Current source,
-configuration, and execution results take precedence over remembered context.
+Works with **Codex, OpenCode, Claude Code, and Hermes Agent**.
+[ChatGPT support is in preview](docs/setup-notes.md#chatgpt).
 
-## Quick start
+## Install
 
-Node.js 24.16.0 or newer is required (Node.js 26.1.0 or newer is also supported).
+Requires Node.js **24.16.0 or newer**.
 
 ```bash
-npm install --global kiokuko
+npm i -g kiokuko
 kiokuko setup
 ```
 
-`setup` initializes the local database, detects supported clients, installs the
-bundled standard Skills, configures their MCP connection, and enables local semantic
-retrieval. The first run installs the embedding runtime and model. Restart a client that
-was already running after setup. Exact configuration rules and recovery procedures
-are in the [Getting started guide](docs/getting-started.md).
+Restart your client, then use it normally. Setup configures MCP, bundled Skills,
+and local semantic search. To skip embedding downloads, use
+`kiokuko setup --no-embeddings`.
 
-To configure clients without installing the embedding runtime or model:
+Upgrading from before 1.0 requires a new database.
+[Migration and cleanup](docs/breaking-changes-1.0.md).
 
-```bash
-kiokuko setup --no-embeddings
-```
-
-This skips embedding setup and preserves any existing embedding settings.
+## Docs
 
 <a id="setup-messages"></a>
 
-### npm notices and setup errors
-
-`install scripts not yet covered by allowScripts` means npm has no recorded
-approval for those dependency scripts. `esbuild` is a build tool; `fsevents`
-supports macOS file watching. The notice alone does not mean setup failed.
-
-Run this in the package directory that produced the notice:
-
-```bash
-npm install-scripts ls
-```
-
-If it lists `esbuild` and `fsevents`, and you have reviewed and want to allow their
-scripts, record approval with:
-
-```bash
-npm install-scripts approve esbuild fsevents
-```
-
-Approval updates that directory's `package.json`. For a global macOS Kiokuko
-install, use the installed Kiokuko directory shown in the error; running these
-commands in another project reviews and changes that project's policy.
-See [npm's script approval guide](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/).
-
-If setup ends with `Local semantic retrieval dependencies remain unavailable`
-and `Cannot find package ... @huggingface/hub/index.js`, the embedding runtime
-could not load and semantic setup is incomplete. Script approval is not a
-confirmed fix for this import error. Report the full error and the output of
-`kiokuko --version`, `node --version`, and `npm --version` when requesting help.
-
-### Saved runtime for Codex
-
-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:
-
-```bash
-kiokuko runtime-prepare --runtime-root "$HOME/Library/Application Support/Kiokuko/runtimes" --json
-kiokuko setup --clients codex --no-embeddings --no-standard-skills --runtime-manifest /absolute/path/to/runtime/manifest.json --client-stopped
-kiokuko runtime-diagnose --manifest /absolute/path/to/runtime/manifest.json --json
-```
-
-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.
-
-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.
-
-### Repository instruction files
-
-`kiokuko use` keeps a short, stable pointer in the repository's `AGENTS.md`
-(or the configured agent file). Kiokuko's generated instructions live in
-`.kiokuko/AGENTS.md`, relative to the repository root. Template upgrades and
-repository identity changes update that generated file without rewriting the
-root pointer. Keep custom instructions outside Kiokuko's managed markers.
-Existing versioned Kiokuko blocks migrate to the pointer on the next use/setup
-refresh; user text and other products' sections remain unchanged. A missing
-root instruction file is not recreated by routine setup; use `kiokuko doctor`
-to review a repair. Missing generated instructions can be restored by use/setup
-or an approved doctor repair. Uninstall removes only Kiokuko's managed regions
-from both files, preserving surrounding content.
-
-## Uninstall
-
-Stop clients using Kiokuko and any `kiokuko serve` process first.
-
-```bash
-kiokuko uninstall --dry-run
-kiokuko uninstall
-# After selecting all agents and completing cleanup, run the printed command:
-npm uninstall --global kiokuko
-```
-
-Use Up/Down to move, Space to toggle, Enter to submit, and Esc to cancel. All choices start unchecked.
-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.
-For scripts, use `kiokuko uninstall --clients opencode,claude` or `kiokuko uninstall --all` for complete cleanup.
-Use the same environment overrides as setup for custom locations. See [cleanup scope and failures](docs/cli-contract.md#uninstall).
-
-## Main features
-
-- **Interaction memory**: learns durable preferences, decisions, and corrections from ordinary conversation as untrusted candidates. [How it works](docs/interaction-memory.md).
-- **RAG memory**: lexical retrieval plus local semantic retrieval configured by `setup`.
-- **Akinator**: clarifies vague requests before work begins.
-- **Local Web UI**: review and curate saved memories.
-- **Reference-only Skills**: discovered external Skills are verified and never executed automatically.
-
-`kiokuko embeddings setup` remains a compatibility entrypoint for `kiokuko setup`.
-
-Managed MCP blocks are updated and registered-project instructions are refreshed.
-An unmanaged identity is replaced only after interactive confirmation; non-interactive
-and `--dry-run --json` invocations fail closed without changing it. See the
-[semantic retrieval guide](docs/semantic-retrieval.md) for runtime, offline, and
-fallback behavior.
-
-## Supported clients
-
-- Codex
-- OpenCode
-- Claude Code
-- Hermes Agent
-
-Client-specific setup, Web UI, and restart instructions are in
-[Getting started](docs/getting-started.md). The [documentation index](docs/README.md)
-links to conceptual and operational guides.
-
-Record sessions with [AgenticReplay](docs/agenticreplay.md) by wrapping the client
-using Kiokuko. AgenticReplay is optional and installed separately.
-
-## Use with ChatGPT (preview)
-
-Connect a personal plugin in Developer mode to save and recall memory. No store-distributed plugin is available.
-
-1. **Prepare Kiokuko.** Use a version whose `kiokuko mcp --help` lists `--profile` and `--access`; otherwise [install from source](docs/chatgpt.md). Run `kiokuko init` if you do not have a database.
-2. **Install the Tunnel client.** On macOS, use the [official Homebrew instructions](https://github.com/openai/tunnel-client#install-with-homebrew):
-
-   ```bash
-   brew install openai/tools/tunnel-client
-   tunnel-client --version
-   ```
-
-   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.
-
-3. **Start the connection on your computer.** Replace `<tunnel_id>` and `<runtime_api_key>` with your values.
-
-   ```bash
-   export CONTROL_PLANE_API_KEY="<runtime_api_key>"
-   tunnel-client init \
-     --sample sample_mcp_stdio_local \
-     --profile kiokuko-chatgpt \
-     --tunnel-id "<tunnel_id>" \
-     --mcp-command "kiokuko mcp --profile chatgpt-memory --access read-write"
-   tunnel-client doctor --profile kiokuko-chatgpt --explain
-   kiokuko chatgpt run --profile kiokuko-chatgpt
-   ```
-
-   Keep it running while using the connection. In a new terminal, set the API key again and execute the final `run` command.
-
-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)
-
-Try: “Save this information in Kiokuko” or “Search Kiokuko for memories about [topic].” Review and approve write requests when prompted.
-
-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](docs/chatgpt.md)
-
-## Safety and limitations
-
-Kiokuko does not store full conversations and rejects content that resembles secrets
-such as passwords, API keys, tokens, or private keys. Saved memories are advisory;
-verify them against the current repository and runtime.
-
-MCP use is client- and model-mediated. There is **no guarantee that Kiokuko is called
-on every turn**. If a client cannot initialize the required MCP connection, a client
-may stop rather than silently continue without policy. Trust boundaries and public
-error behavior are documented in [Security and trust](docs/security-and-trust.md).
-
-## More detail
-
-- [Documentation index](docs/README.md)
 - [Getting started](docs/getting-started.md)
-- [Concepts](docs/concepts.md)
-- [Semantic retrieval](docs/semantic-retrieval.md)
-- [Akinator profile memory](docs/akinator-memory.md)
-- [Security and trust](docs/security-and-trust.md)
-- [CLI contract](docs/cli-contract.md)
-
-Implementation-focused references remain in [architecture](docs/architecture.md),
-[database](docs/database.md), [execution ledger](docs/execution-ledger.md), and
-[client compatibility](docs/client-compatibility.md).
+- [Setup, troubleshooting, and uninstall](docs/setup-notes.md)
+- [Memory and search](docs/concepts.md)
+- [History and code evidence](docs/history-evidence.md)
+- [All documentation](docs/README.md)
+
+Saved memories can be wrong. Kiokuko rejects secret-like content and does not
+store full conversations. MCP calls depend on your client and model.
+[Security and trust](docs/security-and-trust.md).