@askdkc/kiokuko 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kiokuko contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,112 @@
+# Kiokuko
+
+[English](README.md) | 日本語 | [简体中文](README.zh-CN.md) | [한국어](README.ko.md)
+
+Kiokukoは、AIコーディングエージェント向けのモデル非依存な外部記憶です。npmでグローバルインストールすると、現在のOSユーザー用SQLiteデータベースに構造化された記憶を保存し、stdio MCP経由でCodexとOpenCodeに高水準のrecall/checkpointツールを提供します。
+
+## グローバルへのインストールと有効化
+
+```bash
+npm install --global @askdkc/kiokuko
+kiokuko setup
+```
+
+npmパッケージ名は`@askdkc/kiokuko`ですが、インストールされるCLIコマンド名は引き続き`kiokuko`です。
+
+セットアップ後にCodexとOpenCodeを再起動してください。それ以降は、グローバルな`AGENTS.md`が重要な作業の前後にKiokukoを呼び出すようエージェントへ指示し、ツールが必要になるとグローバル設定から`kiokuko mcp`が起動されます。
+
+`setup`は明示的に実行する冪等な処理です。npmの`postinstall`がAIクライアントの設定を変更することはありません。既存のTOML/JSONC設定、コメント、指示内容、改行コード、ファイルモードを維持し、Kiokukoは管理対象セクションだけを更新します。
+
+```bash
+# 書き込まずに変更対象ファイルと予定内容を確認
+kiokuko setup --dry-run --json
+
+# 一方のクライアントだけを設定
+kiokuko setup --clients codex
+kiokuko setup --clients opencode
+
+# クライアントプロセスがnpmのPATHを継承しない場合は絶対パスを指定
+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` |
+
+OpenCodeの`opencode.jsonc`がすでに存在する場合、Kiokukoはコメントを維持したままそのファイルを更新します。CodexにKiokuko管理外の`[mcp_servers.kiokuko]`テーブルが存在する場合、上書き対象を推測せずセットアップを停止します。
+
+## 記憶のスコープ
+
+データベースはOSユーザー全体で共有されますが、通常のrecallがデータベース全体を無条件に検索することはありません。
+
+- `project`記憶は、`.kiokuko.json`、既知の正規パス、またはGit remoteから自動解決されます。他のプロジェクトの記憶は除外されます。
+- `global`記憶は、本当にプロジェクト横断で利用する設定や教訓のために予約されています。
+- デフォルトの`auto` recallは、現在のプロジェクトとglobal記憶だけを返します。
+- remoteのないリポジトリには、パスから導出した安定した識別子を使用します。自動解決時にKiokukoがリポジトリ内へファイルを書き込むことはありません。
+
+MCPの公開インターフェースは意図的に小さくしています。
+
+- `memory_recall`: 上限付きのproject/globalコンテキストを読み取ります。結果には常にuntrustedマークが付きます。
+- `memory_checkpoint`: 上限付きの永続的な記憶を`candidate`かつ`untrusted`として保存します。シークレットに見える内容は拒否されます。
+
+これは指示による自動利用であり、プロンプトの横取りではありません。CodexやOpenCodeが特定のターンでツールを呼ばない可能性は残ります。Kiokukoはフックをインストールせず、会話全文を取得せず、記憶を暗黙にverifiedへ昇格させません。
+
+## 開発
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## 開発環境での実行
+
+```bash
+npm exec -- tsx src/bin/kiokuko.ts setup --dry-run --json
+npm exec -- tsx src/bin/kiokuko.ts mcp
+```
+
+`kiokuko use`は、移植可能な明示的バインディングが必要な場合の任意機能として残っています。`.kiokuko.json`と`AGENTS.md`内の管理ブロックを作成しますが、通常のMCP利用では不要です。
+
+## Akinator形式の知識取り込み
+
+重要な作業に対して、`guide`はタスク種別、対象、成功条件など、不足している価値の高い項目だけを質問します。その後、クエリとBot用途タグを使ってローカル記憶を選択します。
+
+```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
+```
+
+ローカル検索で関連エントリが見つからない場合、`guide context`は次の許可済み公開リポジトリに限って現在の`main`ツリーを取得し、選択したMarkdownスキルや参照情報を`candidate`エントリとして保存できます。
+
+- https://github.com/NousResearch/hermes-agent
+- https://github.com/obra/superpowers
+
+インポートされた各エントリには、リポジトリ、commit SHA、ソースパスが記録されます。これらは信頼されていない参照資料であり、自動的に`verified`へ昇格したり、コマンドとして実行されたりすることはありません。同期の再実行はコンテンツハッシュにより冪等です。
+
+## ローカルWeb UI
+
+ループバック専用HTTPサーバーを起動すると、Bot用途、記憶タイプ、横断タグで記憶エントリを閲覧し、ブラウザからcandidateエントリを編集できます。
+
+```bash
+kiokuko web
+# http://127.0.0.1:4173 を開く
+```
+
+`--port 0`で空いているポートを自動選択でき、`--json`で選択されたURLをJSONとして出力できます。Web UIが非ループバックインターフェースへサーバーを公開することはありません。verifiedおよびsupersededエントリは読み取り専用です。candidateの編集には楽観的リビジョン検査が使われ、監査履歴が維持されます。
+
+`bot:researcher`、`bot:builder`、`bot:reviewer`などのタグは、種類をまたいだフィルターとして使用できます。エントリまたはサイドバーのタグをクリックすると、記憶タイプに関係なく一致するすべてのエントリが表示されます。
+
+記憶エントリは信頼されていない保存データです。過去のエントリを利用する前に、現在のファイルとランタイム状態を確認してください。パスワード、APIキー、トークン、秘密鍵、セッションCookieを保存しないでください。
+
+このリポジトリは自動公開されません。`npm publish`、commit、pushにはユーザーによる明示的な許可が必要です。

package/README.ko.md

@@ -0,0 +1,112 @@
+# Kiokuko
+
+[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | 한국어
+
+Kiokuko는 AI 코딩 에이전트를 위한 모델 독립적인 외부 메모리 도구입니다. npm으로 한 번 전역 설치하면 현재 운영체제 사용자의 SQLite 데이터베이스에 구조화된 메모리를 저장하고, stdio MCP를 통해 Codex와 OpenCode에 고수준 recall/checkpoint 도구를 제공합니다.
+
+## 전역 설치 및 활성화
+
+```bash
+npm install --global @askdkc/kiokuko
+kiokuko setup
+```
+
+npm 패키지 이름은 `@askdkc/kiokuko`이지만 설치되는 CLI 명령 이름은 계속 `kiokuko`입니다.
+
+설정 후 Codex와 OpenCode를 다시 시작하십시오. 이후 전역 `AGENTS.md`가 중요한 작업 전과 지속성 있는 작업 후에 Kiokuko를 호출하도록 에이전트에 지시하며, 도구가 필요할 때 전역 설정에서 `kiokuko mcp`를 시작합니다.
+
+`setup`은 명시적으로 실행하는 멱등 작업입니다. npm `postinstall`은 AI 클라이언트 설정을 수정하지 않습니다. 기존 TOML/JSONC 설정, 주석, 지침 내용, 줄바꿈 형식 및 파일 모드는 유지되며 Kiokuko는 관리 구역만 수정합니다.
+
+```bash
+# 아무것도 쓰지 않고 정확한 대상 파일과 예정된 변경 사항 확인
+kiokuko setup --dry-run --json
+
+# 클라이언트 하나만 설정
+kiokuko setup --clients codex
+kiokuko setup --clients opencode
+
+# 클라이언트 프로세스가 npm의 PATH를 상속하지 않는 경우 절대 경로 사용
+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` |
+
+OpenCode의 `opencode.jsonc`가 이미 있으면 Kiokuko는 주석을 유지하면서 해당 파일을 수정합니다. Codex에 Kiokuko가 관리하지 않는 `[mcp_servers.kiokuko]` 테이블이 이미 있으면 어떤 설정을 덮어쓸지 추측하지 않고 설정을 중단합니다.
+
+## 메모리 범위
+
+데이터베이스는 운영체제 사용자 전체에서 공유되지만 일반 recall은 전역 데이터베이스 전체를 검색하지 않습니다.
+
+- `project` 메모리는 `.kiokuko.json`, 알려진 정규 경로 또는 Git remote에서 자동으로 확인됩니다. 다른 프로젝트의 메모리는 제외됩니다.
+- `global` 메모리는 실제로 여러 프로젝트에 적용되는 선호 사항과 교훈을 위해 예약됩니다.
+- 기본 `auto` recall은 현재 프로젝트와 global 메모리만 반환합니다.
+- remote가 없는 저장소에는 경로에서 파생된 안정적인 식별자가 할당됩니다. 자동 확인 중 Kiokuko는 저장소에 어떤 파일도 쓰지 않습니다.
+
+MCP 인터페이스는 의도적으로 작게 유지됩니다.
+
+- `memory_recall`: 제한된 project/global 컨텍스트를 읽으며 항상 untrusted로 표시합니다.
+- `memory_checkpoint`: 제한된 지속성 항목을 `candidate` 및 `untrusted`로 저장합니다. 비밀 정보로 보이는 내용은 거부됩니다.
+
+이는 지침에 기반한 자동 사용이며 프롬프트 가로채기가 아닙니다. Codex와 OpenCode가 특정 턴에서 도구를 호출하지 않을 가능성은 여전히 있습니다. Kiokuko는 훅을 설치하거나 전체 대화를 수집하거나 메모리를 조용히 verified 상태로 승격하지 않습니다.
+
+## 개발
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## 개발 환경에서 사용
+
+```bash
+npm exec -- tsx src/bin/kiokuko.ts setup --dry-run --json
+npm exec -- tsx src/bin/kiokuko.ts mcp
+```
+
+`kiokuko use`는 이식 가능한 명시적 바인딩이 필요한 경우를 위한 선택 기능으로 유지됩니다. `.kiokuko.json`과 `AGENTS.md`의 관리 블록을 생성하지만 일반적인 MCP 사용에는 더 이상 필요하지 않습니다.
+
+## Akinator 방식 지식 수집
+
+중요한 작업에서 `guide`는 작업 유형, 대상 및 성공 조건과 같이 누락된 고가치 필드만 질문합니다. 그런 다음 쿼리와 Bot 목적 태그를 사용하여 로컬 메모리를 선택합니다.
+
+```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
+```
+
+로컬 검색에서 관련 항목을 찾지 못하면 `guide context`는 다음 허용 목록의 공개 저장소에서만 현재 `main` 트리를 가져와 선택한 Markdown 스킬이나 참조 자료를 `candidate` 항목으로 저장할 수 있습니다.
+
+- https://github.com/NousResearch/hermes-agent
+- https://github.com/obra/superpowers
+
+가져온 각 항목에는 저장소, commit SHA 및 소스 경로가 기록됩니다. 신뢰되지 않은 참조 자료이므로 자동으로 `verified`로 승격되거나 명령으로 실행되지 않습니다. 반복 동기화는 콘텐츠 해시를 통해 멱등성을 유지합니다.
+
+## 로컬 Web UI
+
+루프백 전용 HTTP 서버를 시작하면 Bot 목적, 메모리 유형 및 교차 태그별로 메모리 항목을 탐색하고 브라우저에서 candidate 항목을 편집할 수 있습니다.
+
+```bash
+kiokuko web
+# http://127.0.0.1:4173 열기
+```
+
+`--port 0`을 사용하면 사용 가능한 포트를 자동으로 선택하고, `--json`을 사용하면 선택된 URL을 JSON으로 출력합니다. Web UI는 루프백이 아닌 인터페이스에 서버를 노출하지 않습니다. verified 및 superseded 항목은 읽기 전용이며 candidate 편집에는 낙관적 리비전 검사를 사용하고 감사 기록을 유지합니다.
+
+`bot:researcher`, `bot:builder`, `bot:reviewer` 같은 태그를 유형 간 필터로 사용할 수 있습니다. 항목 또는 사이드바의 태그를 클릭하면 메모리 유형과 관계없이 일치하는 모든 항목을 표시합니다.
+
+메모리 항목은 신뢰되지 않은 저장 데이터입니다. 과거 항목을 사용하기 전에 현재 파일과 런타임 상태를 확인하십시오. 비밀번호, API 키, 토큰, 개인 키 또는 세션 쿠키를 저장하지 마십시오.
+
+이 저장소는 자동으로 게시되지 않습니다. `npm publish`, commit 및 push에는 사용자의 명시적 승인이 필요합니다.

package/README.md

@@ -0,0 +1,147 @@
+# Kiokuko
+
+English | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | [한국어](README.ko.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 high-level recall/checkpoint tools to Codex and OpenCode over stdio MCP.
+
+## Install and enable globally
+
+```bash
+npm install --global @askdkc/kiokuko
+kiokuko setup
+```
+
+The npm package name is `@askdkc/kiokuko`; the installed CLI command remains
+`kiokuko`.
+
+Restart Codex and OpenCode after setup. From then on, their global `AGENTS.md`
+instructs the agent to call Kiokuko before non-trivial work and after durable
+work, and their global config starts `kiokuko mcp` when the tools are needed.
+
+`setup` is explicit and idempotent. npm `postinstall` never edits AI-client
+configuration. Existing TOML/JSONC settings, comments, instruction content,
+line endings, and file modes are preserved; Kiokuko owns only its managed
+sections.
+
+```bash
+# Preview exact target files without writing anything
+kiokuko setup --dry-run --json
+
+# Configure only one client
+kiokuko setup --clients codex
+kiokuko setup --clients opencode
+
+# Use an absolute executable path if the client process does not inherit npm's PATH
+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` |
+
+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.
+
+## Memory scope
+
+The database is global to the OS user, but ordinary recall is not a global
+full-database search:
+
+- `project` memory is resolved automatically from `.kiokuko.json`, the known
+  canonical path, or the Git remote. Another project's memory is excluded.
+- `global` memory is reserved for genuinely cross-project preferences and
+  lessons.
+- default `auto` recall returns only the current project plus global memory.
+- a repository without a remote gets a stable path-derived identity. Kiokuko
+  does not write anything into the repository during automatic resolution.
+
+The MCP surface is deliberately small:
+
+- `memory_recall`: read bounded project/global context, always marked untrusted.
+- `memory_checkpoint`: store bounded durable entries as `candidate` and
+  `untrusted`; secret-like content is rejected.
+
+This is instruction-driven automatic use, not prompt interception. Codex and
+OpenCode can still choose not to call a tool on a particular turn. Kiokuko does
+not install hooks, capture full transcripts, or silently promote memory to
+verified status.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## Development usage
+
+```bash
+npm exec -- tsx src/bin/kiokuko.ts setup --dry-run --json
+npm exec -- tsx src/bin/kiokuko.ts mcp
+```
+
+`kiokuko use` remains optional for a portable explicit binding. It creates
+`.kiokuko.json` and a managed block in `AGENTS.md`; normal MCP use no longer
+requires it.
+
+## Akinator-style knowledge intake
+
+For non-trivial work, `guide` asks only for missing high-value fields such as
+the task type, target, and success condition. It then selects local memory by
+query and Bot-purpose tags:
+
+```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
+```
+
+If local retrieval produces no relevant entries, `guide context` can fetch the
+current `main` tree from only these allowlisted public repositories and store
+the selected Markdown skills or references as `candidate` entries:
+
+- https://github.com/NousResearch/hermes-agent
+- https://github.com/obra/superpowers
+
+Each imported entry records its repository, commit SHA, and source path. It is
+untrusted reference material and is never auto-promoted to `verified` or
+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,
+memory type, and cross-cutting tags, and edit candidate entries from the browser:
+
+```bash
+kiokuko web
+# open http://127.0.0.1:4173
+```
+
+Use `--port 0` to select an available port, or `--json` to print the selected
+URL as JSON. The web UI does not expose the server on non-loopback interfaces.
+Verified and superseded entries are read-only; editing a candidate uses an
+optimistic revision check and preserves the audit trail.
+Tags such as `bot:researcher`, `bot:builder`, and `bot:reviewer` can be used as
+cross-genre filters. Clicking a tag in an entry or in the sidebar shows every
+matching entry regardless of its memory type.
+
+Memory entries are untrusted stored data. Verify current files and runtime
+state before relying on historical entries. Never store passwords, API keys,
+tokens, private keys, or session cookies.
+
+This repository is not published automatically. `npm publish`, commits, and
+pushes require explicit user authorization.

package/README.zh-CN.md

@@ -0,0 +1,112 @@
+# Kiokuko
+
+[English](README.md) | [日本語](README.ja.md) | 简体中文 | [한국어](README.ko.md)
+
+Kiokuko 是面向 AI 编程智能体、与模型无关的外部记忆工具。通过一次 npm 全局安装，它会将结构化记忆保存在当前操作系统用户的 SQLite 数据库中，并通过 stdio MCP 向 Codex 和 OpenCode 提供高层级的 recall/checkpoint 工具。
+
+## 全局安装与启用
+
+```bash
+npm install --global @askdkc/kiokuko
+kiokuko setup
+```
+
+npm 包名是 `@askdkc/kiokuko`，安装后的 CLI 命令名仍然是 `kiokuko`。
+
+设置完成后，请重启 Codex 和 OpenCode。此后，全局 `AGENTS.md` 会指示智能体在处理重要工作之前调用 Kiokuko，并在产生持久性成果后写入检查点；需要工具时，全局配置会启动 `kiokuko mcp`。
+
+`setup` 是显式且幂等的操作。npm 的 `postinstall` 永远不会修改 AI 客户端配置。现有 TOML/JSONC 设置、注释、指令内容、换行符和文件权限都会保留；Kiokuko 只管理自己的区块。
+
+```bash
+# 不写入任何内容，预览确切的目标文件和计划变更
+kiokuko setup --dry-run --json
+
+# 只配置一个客户端
+kiokuko setup --clients codex
+kiokuko setup --clients opencode
+
+# 如果客户端进程未继承 npm 的 PATH，请使用可执行文件绝对路径
+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` |
+
+如果 OpenCode 的 `opencode.jsonc` 已存在，Kiokuko 会保留注释并更新该文件。如果 Codex 中已存在不受 Kiokuko 管理的 `[mcp_servers.kiokuko]` 表，设置程序不会猜测应该覆盖哪项配置，而是直接停止。
+
+## 记忆作用域
+
+数据库由当前操作系统用户全局共享，但普通 recall 不会搜索整个全局数据库：
+
+- `project` 记忆会根据 `.kiokuko.json`、已知规范路径或 Git remote 自动解析。其他项目的记忆会被排除。
+- `global` 记忆仅用于真正跨项目适用的偏好和经验。
+- 默认的 `auto` recall 只返回当前项目与 global 记忆。
+- 没有 remote 的仓库会获得由路径派生的稳定标识。自动解析时，Kiokuko 不会向仓库写入任何文件。
+
+MCP 接口被有意保持为最小范围：
+
+- `memory_recall`：读取有界的 project/global 上下文，并始终标记为 untrusted。
+- `memory_checkpoint`：将有界的持久性条目保存为 `candidate` 和 `untrusted`；疑似密钥的内容会被拒绝。
+
+这种自动使用由指令驱动，并不会拦截提示词。Codex 和 OpenCode 仍可能决定在某个回合不调用工具。Kiokuko 不会安装钩子、捕获完整对话，也不会静默地将记忆提升为 verified 状态。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## 开发环境用法
+
+```bash
+npm exec -- tsx src/bin/kiokuko.ts setup --dry-run --json
+npm exec -- tsx src/bin/kiokuko.ts mcp
+```
+
+`kiokuko use` 仍可作为可选功能，用于创建可移植的显式绑定。它会创建 `.kiokuko.json` 和 `AGENTS.md` 中的托管区块；普通 MCP 使用不再需要它。
+
+## Akinator 式知识采集
+
+对于重要工作，`guide` 只会询问任务类型、目标和成功条件等缺失的高价值字段。随后，它会根据查询和 Bot 用途标签选择本地记忆：
+
+```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
+```
+
+如果本地检索没有产生相关条目，`guide context` 只能从以下白名单公开仓库获取当前 `main` 分支树，并将选中的 Markdown 技能或参考资料保存为 `candidate` 条目：
+
+- https://github.com/NousResearch/hermes-agent
+- https://github.com/obra/superpowers
+
+每个导入条目都会记录其仓库、commit SHA 和源路径。这些内容是不受信任的参考资料，永远不会自动提升为 `verified`，也不会作为命令执行。重复同步通过内容哈希保持幂等。
+
+## 本地 Web UI
+
+启动仅限回环地址的 HTTP 服务器，即可按 Bot 用途、记忆类型和跨类别标签浏览记忆条目，并在浏览器中编辑 candidate 条目：
+
+```bash
+kiokuko web
+# 打开 http://127.0.0.1:4173
+```
+
+使用 `--port 0` 可自动选择可用端口，使用 `--json` 可将所选 URL 以 JSON 输出。Web UI 不会在非回环接口上公开服务器。verified 和 superseded 条目为只读；编辑 candidate 时会使用乐观修订检查，并保留审计记录。
+
+`bot:researcher`、`bot:builder` 和 `bot:reviewer` 等标签可以作为跨类型筛选器。点击条目或侧边栏中的标签，会显示所有匹配条目，而不受记忆类型限制。
+
+记忆条目是未经信任的存储数据。依赖历史条目前，请验证当前文件和运行时状态。切勿存储密码、API 密钥、令牌、私钥或会话 Cookie。
+
+本仓库不会自动发布。执行 `npm publish`、commit 和 push 均需要用户明确授权。

package/dist/agent-file/atomic-write.d.ts

@@ -0,0 +1,6 @@
+export declare function readRegularFile(filePath: string): Promise<{
+    content: string;
+    mode: number;
+} | undefined>;
+export declare function atomicWriteText(filePath: string, content: string, mode?: number): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/agent-file/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../../src/agent-file/atomic-write.ts"],"names":[],"mappings":"AAKA,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAU9G;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAcpG"}

package/dist/agent-file/atomic-write.js

@@ -0,0 +1,36 @@
+import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { KiokukoError } from '../errors.js';
+export async function readRegularFile(filePath) {
+    try {
+        const info = await lstat(filePath);
+        if (info.isSymbolicLink())
+            throw new KiokukoError('SECURITY_REJECTION', `Refusing to follow symlink: ${filePath}`);
+        if (!info.isFile())
+            throw new KiokukoError('VALIDATION_ERROR', `Expected a regular file: ${filePath}`);
+        return { content: await readFile(filePath, 'utf8'), mode: info.mode & 0o777 };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function atomicWriteText(filePath, content, mode = 0o644) {
+    const directory = path.dirname(filePath);
+    await mkdir(directory, { recursive: true });
+    const temporaryPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporaryPath, content, { encoding: 'utf8', mode });
+        await chmod(temporaryPath, mode);
+        await rename(temporaryPath, filePath);
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        throw new KiokukoError('PARTIAL_FAILURE', `Unable to atomically write ${filePath}`, {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/agent-file/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../src/agent-file/atomic-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,cAAc,EAAE;YAAE,MAAM,IAAI,YAAY,CAAC,oBAAoB,EAAE,+BAA+B,QAAQ,EAAE,CAAC,CAAC;QACnH,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,4BAA4B,QAAQ,EAAE,CAAC,CAAC;QACvG,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;IAChF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACtH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB,EAAE,OAAe,EAAE,IAAI,GAAG,KAAK;IACnF,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IAC9F,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,MAAM,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACjC,MAAM,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,IAAI,YAAY,CAAC,iBAAiB,EAAE,8BAA8B,QAAQ,EAAE,EAAE;YAClF,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/agent-file/managed-block.d.ts

@@ -0,0 +1,12 @@
+export declare const BEGIN_MARKER = "<!-- BEGIN KIOKUKO MANAGED BLOCK -->";
+export declare const END_MARKER = "<!-- END KIOKUKO MANAGED BLOCK -->";
+type ManagedBlockState = 'absent' | 'balanced';
+export interface ManagedBlockResult {
+    content: string;
+    action: 'created' | 'updated' | 'unchanged';
+    state: ManagedBlockState;
+}
+export declare function upsertManagedBlock(existing: string, managedBlock: string): ManagedBlockResult;
+export declare function assertNotSymlink(filePath: string, isSymbolicLink: boolean): void;
+export {};
+//# sourceMappingURL=managed-block.d.ts.map

package/dist/agent-file/managed-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-block.d.ts","sourceRoot":"","sources":["../../src/agent-file/managed-block.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,yCAAyC,CAAC;AACnE,eAAO,MAAM,UAAU,uCAAuC,CAAC;AAE/D,KAAK,iBAAiB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/C,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC5C,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAiCD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAgB7F;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,IAAI,CAEhF"}

package/dist/agent-file/managed-block.js

@@ -0,0 +1,56 @@
+import { KiokukoError } from '../errors.js';
+export const BEGIN_MARKER = '<!-- BEGIN KIOKUKO MANAGED BLOCK -->';
+export const END_MARKER = '<!-- END KIOKUKO MANAGED BLOCK -->';
+function markerPositions(content, marker) {
+    const positions = [];
+    let from = 0;
+    for (;;) {
+        const index = content.indexOf(marker, from);
+        if (index < 0)
+            return positions;
+        positions.push(index);
+        from = index + marker.length;
+    }
+}
+function validateMarkers(content) {
+    const starts = markerPositions(content, BEGIN_MARKER);
+    const ends = markerPositions(content, END_MARKER);
+    if (starts.length === 0 && ends.length === 0)
+        return undefined;
+    const start = starts[0];
+    const end = ends[0];
+    if (starts.length !== 1 || ends.length !== 1 || start === undefined || end === undefined || start >= end) {
+        throw new KiokukoError('VALIDATION_ERROR', 'AGENTS.md contains malformed Kiokuko managed markers');
+    }
+    return { start, end: end + END_MARKER.length };
+}
+function newlineFor(content) {
+    return content.includes('\r\n') ? '\r\n' : '\n';
+}
+function normalizeBlock(block, newline) {
+    return block.replaceAll('\r\n', '\n').replaceAll('\n', newline);
+}
+export function upsertManagedBlock(existing, managedBlock) {
+    const markers = validateMarkers(existing);
+    const newline = newlineFor(existing);
+    const normalizedBlock = normalizeBlock(managedBlock, newline);
+    if (!markers) {
+        if (existing.length === 0)
+            return { content: normalizedBlock, action: 'created', state: 'absent' };
+        const separator = existing.endsWith('\n') || existing.endsWith('\r') ? `${newline}${newline}` : `${newline}${newline}${newline}`;
+        return { content: `${existing}${separator}${normalizedBlock}`, action: 'created', state: 'absent' };
+    }
+    const currentBlock = existing.slice(markers.start, markers.end);
+    if (currentBlock === normalizedBlock)
+        return { content: existing, action: 'unchanged', state: 'balanced' };
+    return {
+        content: `${existing.slice(0, markers.start)}${normalizedBlock}${existing.slice(markers.end)}`,
+        action: 'updated',
+        state: 'balanced',
+    };
+}
+export function assertNotSymlink(filePath, isSymbolicLink) {
+    if (isSymbolicLink)
+        throw new KiokukoError('SECURITY_REJECTION', `Refusing to modify symlink: ${filePath}`);
+}
+//# sourceMappingURL=managed-block.js.map

package/dist/agent-file/managed-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-block.js","sourceRoot":"","sources":["../../src/agent-file/managed-block.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,14 @@
+export declare const AGENT_TEMPLATE_VERSION = 3;
+export interface AgentTemplateValues {
+    repositoryId: string;
+    workspace: string;
+    cliCommand: 'kiokuko' | 'npm exec -- kiokuko' | 'npx --no-install kiokuko';
+    templateVersion?: number;
+}
+export interface RenderedAgentFile {
+    content: string;
+    action: 'created' | 'updated' | 'unchanged';
+}
+export declare function renderManagedBlock(values: AgentTemplateValues): string;
+export declare function renderAgentFile(existing: string | undefined, values: AgentTemplateValues): RenderedAgentFile;
+//# sourceMappingURL=render.d.ts.map