kiokuko 1.0.43 → 1.0.44

package/docs/setup-notes.md

@@ -0,0 +1,133 @@
+# Setup and troubleshooting
+
+<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). Generated instructions live in `.kiokuko/AGENTS.md`.
+Template and repository identity updates refresh that generated file; older
+versioned blocks migrate to the pointer on the next use/setup refresh. Keep custom
+instructions outside Kiokuko's managed markers; user text and other products'
+sections are preserved.
+
+Routine setup skips a missing root instruction file. Ordinary `kiokuko doctor`
+automatically creates missing registered root/generated instruction files, in both
+TTY and non-TTY use, without a confirmation prompt or an extra repair flag.
+Recovery requires a matching registered repository ID, workspace, binding and
+canonical path. It creates only absent files, preserves existing custom content,
+and cannot restore deleted custom instructions. Permission failures, unsafe
+symlinks and concurrent changes are reported for each target while other targets
+continue. Missing/conflicting bindings are diagnosed rather than guessed.
+
+```bash
+kiokuko doctor
+kiokuko doctor --json
+kiokuko doctor --fix --repair-root /absolute/path/to/project
+```
+
+`kiokuko doctor --json` diagnoses without creating missing instructions. `--fix`
+is the explicit registered-binding repair mode; `--repair-root` requires `--fix`.
+Combining `--fix` with `--json` still permits that binding repair. Existing section
+updates remain a separate interactive confirmation; non-TTY use does not approve
+them. Missing generated instructions can also be restored by use/setup. Uninstall
+removes only Kiokuko's managed regions from both files. See
+[the CLI contract](cli-contract.md) for repair details.
+
+## 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](cli-contract.md#uninstall).
+
+<a id="chatgpt"></a>
+
+## 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](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](chatgpt.md)
+

package/docs/setup-notes.zh-CN.md

@@ -0,0 +1,107 @@
+# 设置与故障排查
+
+<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 use`在仓库的`AGENTS.md`（或配置的指令文件）中保留简短、稳定的引用，
+生成的指令存放在`.kiokuko/AGENTS.md`。模板及仓库身份更新会刷新生成文件；
+旧的带版本管理块会在下次use/setup更新时迁移为引用。请将自定义指令放在Kiokuko管理标记之外；
+用户文本和其他产品的内容会保留。
+
+常规setup会跳过缺失的根指令文件。普通`kiokuko doctor`在交互式和非TTY运行中，
+都会自动创建已注册仓库缺失的根指令及生成指令文件，无需确认或额外修复标志。
+前提是注册仓库ID、workspace、binding及规范路径一致。恢复只创建缺失文件，保留已有自定义内容，
+无法恢复已删除的自定义指令。权限不足、不安全的符号链接和并发修改会按目标报告，
+并继续处理其他目标。缺失或冲突的binding仅被诊断，不会凭猜测替换。
+
+```bash
+kiokuko doctor
+kiokuko doctor --json
+kiokuko doctor --fix --repair-root /absolute/path/to/project
+```
+
+`kiokuko doctor --json`只诊断，不创建缺失指令。`--fix`是显式修复已注册binding的模式；
+`--repair-root`必须配合`--fix`使用。`--fix --json`仍会执行binding修复。
+更新现有管理部分仍需单独的交互确认，非TTY运行不视为批准。
+缺失的生成指令也可通过use/setup恢复。卸载只移除两个文件中的Kiokuko管理部分。
+详见[CLI契约（英文）](cli-contract.md)。
+
+## 卸载
+
+先退出使用 Kiokuko 的客户端和 `kiokuko serve`。
+
+```bash
+kiokuko uninstall --dry-run
+kiokuko uninstall
+# 选中全部代理并完成清理后，执行最后显示的命令：
+npm uninstall --global kiokuko
+```
+
+↑↓ 移动，Space 切换选择，Enter 确认，Esc 取消。默认全部未选中。
+仅删除所选代理的受管理配置和 Skill。**选中全部四个代理时，还会删除共享记忆数据库、嵌入模型和项目绑定**，最后显示 npm 卸载命令。部分选择会保留共享数据和 npm 包。用户内容保持不变。
+脚本中使用 `kiokuko uninstall --clients opencode,claude`，完全清理使用 `kiokuko uninstall --all`。自定义路径需要使用与 setup 相同的环境变量。
+详见[清理范围](cli-contract.md#uninstall)。
+
+<a id="chatgpt"></a>
+
+## 在 ChatGPT 中使用（预览）
+
+通过 Developer mode 添加个人插件连接，保存和搜索记忆。目前没有商店分发版。
+
+1. **准备 Kiokuko。** 使用 `kiokuko mcp --help` 中包含 `--profile` 和 `--access` 的版本；否则[从源码安装](chatgpt.md)。尚无数据库时运行 `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
+   ```
+
+   其他系统参见[官方发布页](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 中实测连接。** [故障排查](chatgpt.md)
+

package/migrations/014_code_version_evidence.sql

@@ -0,0 +1,26 @@
+-- Raw code evidence is operational history, never an approved memory or execution permission.
+CREATE TABLE code_version_evidence (
+ version_id TEXT PRIMARY KEY,
+ evidence_id TEXT NOT NULL UNIQUE REFERENCES ledger_evidence(evidence_id) ON DELETE CASCADE,
+ run_id TEXT NOT NULL REFERENCES ledger_runs(run_id) ON DELETE CASCADE,
+ entry_id TEXT REFERENCES entries(id) ON DELETE CASCADE,
+ workspace TEXT NOT NULL,
+ repository_id TEXT NOT NULL REFERENCES repositories(repository_id) ON DELETE CASCADE,
+ owner_id TEXT NOT NULL,
+ branch TEXT,
+ parent_version_id TEXT,
+ path TEXT NOT NULL,
+ reported_outcome TEXT NOT NULL CHECK(reported_outcome IN ('accepted','rejected','failed','unknown')),
+ reason TEXT NOT NULL,
+ environment_json TEXT NOT NULL CHECK(json_valid(environment_json)),
+ required_environment_json TEXT CHECK(required_environment_json IS NULL OR json_valid(required_environment_json)),
+ diff_text TEXT NOT NULL,
+ diff_digest TEXT NOT NULL CHECK(length(diff_digest)=64),
+ binding_digest TEXT NOT NULL CHECK(length(binding_digest)=64),
+ created_at TEXT NOT NULL
+) STRICT;
+CREATE INDEX code_version_recall ON code_version_evidence(owner_id,repository_id,workspace,branch,entry_id,created_at DESC,version_id ASC);
+CREATE TRIGGER code_version_immutable BEFORE UPDATE ON code_version_evidence
+BEGIN SELECT RAISE(ABORT,'Code version evidence is immutable'); END;
+
+CREATE INDEX entry_supersession_history ON entries(workspace,superseded_by,id) WHERE status='superseded';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiokuko",
-  "version": "1.0.43",
+  "version": "1.0.44",
   "description": "Model-agnostic external memory for AI coding agents",
   "type": "module",
   "bin": {