Kiokuko（记忆库）

1.0 不再支持旧数据库，请使用新数据库。参见破坏性变更与旧配置清理。

English | 日本語 | 简体中文 | 한국어

通过 MCP 连接，检索需要的记忆，并在工作后积累知识。

Kiokuko 是面向 AI 编程代理的本地外部记忆。它把知识保存在 SQLite 中，在下一次任务中检索相关上下文， 并保存可复用的工作结果。

请求 → MCP 连接 → 检索相关记忆 → 完成工作
                              ↓
                         保存可复用知识

记忆分为 Project、Ecosystem 和 Global。当前代码、配置和运行结果优先于历史记忆。

快速开始

需要 Node.js 24.16.0 或更高版本（也支持 Node.js 26.1.0 或更高版本）。

npm install --global kiokuko
kiokuko setup

setup 会初始化数据库、安装标准 Skill、配置 MCP 和本地 semantic 检索。 首次运行会安装嵌入运行时并下载模型。已运行的客户端请在设置后重启。 精确配置和恢复规则请参阅英文 Getting started。

只配置客户端，不安装嵌入运行时和模型：

kiokuko setup --no-embeddings

此选项跳过嵌入设置步骤，不更改已有的嵌入配置。

npm 提示与设置错误

install scripts not yet covered by allowScripts 表示 npm 尚未记录这些依赖脚本的执行许可。 esbuild 是构建工具，fsevents 用于 macOS 文件监控。仅出现此提示不代表设置失败。

在产生提示的包目录中运行：

npm install-scripts ls

如果列出了 esbuild 和 fsevents，并且你已检查脚本、决定允许执行，可运行：

npm install-scripts approve esbuild fsevents

许可会写入该目录的 package.json。在 macOS 上全局安装 Kiokuko 时，请在错误信息显示的 Kiokuko 安装目录中操作； 在其他项目中运行这些命令，查看和修改的是那个项目的许可设置。 详情请参阅 npm 脚本许可指南。

如果设置最终报出 Local semantic retrieval dependencies remain unavailable 和 Cannot find package ... @huggingface/hub/index.js， 说明嵌入运行时无法加载，semantic 检索尚未配置完成。尚未确认批准脚本能解决此导入错误。 寻求帮助时，请附上完整错误信息以及 kiokuko --version、node --version、npm --version 的输出。

卸载

先退出使用 Kiokuko 的客户端和 kiokuko serve。

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 相同的环境变量。 详见清理范围。

主要功能

• RAG 记忆（lexical 检索，以及通过 setup 配置的本地 semantic 检索）
• Akinator 让模糊请求先变得具体
• 本地 Web UI 用于检查和整理记忆
• 外部 Skill 仅作为经过验证的参考，绝不自动执行

kiokuko embeddings setup 保留为兼容入口，与 kiokuko setup 执行相同流程。

它会更新 managed MCP block 和项目 instructions。替换 unmanaged identity 需要交互确认；非交互或 --dry-run --json 执行会在不修改配置的情况下 fail closed。详见英文 semantic retrieval。

支持的客户端

Codex、OpenCode、Claude Code、Hermes Agent。

在 ChatGPT 中使用（预览）

通过 Developer mode 添加个人插件连接，保存和搜索记忆。目前没有商店分发版。

1. 准备 Kiokuko。 使用 kiokuko mcp --help 中包含 --profile 和 --access 的版本；否则从源码安装。尚无数据库时运行 kiokuko init。

2. 安装 Tunnel 客户端。 macOS 使用官方 Homebrew 安装方式：

   brew install openai/tools/tunnel-client
   tunnel-client --version

   其他系统参见官方发布页。在 Tunnel 设置中准备关联到 ChatGPT workspace 的 Tunnel ID，以及具有 Tunnels Read + Use 权限的运行用 API 密钥。

3. 在电脑上启动连接。 将 <tunnel_id> 和 <runtime_api_key> 替换为取得的值。

   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。官方界面步骤

使用示例：“把这些内容保存到 Kiokuko”或“在 Kiokuko 中查找关于[主题]的记忆”。出现写入确认时，检查内容后批准。

只需搜索时，将启动命令中的 read-write 改为 read。这不会更改 ChatGPT 内置记忆的保存位置。尚未在 ChatGPT 中实测连接。 故障排查

安全性与限制

Kiokuko 不保存完整对话，并拒绝看起来像密码、API key、token 或私钥的内容。记忆只是参考信息，应以当前代码和运行结果为准。

MCP 是否调用由客户端和模型决定，不保证每一轮都会调用 Kiokuko。详细安全边界请看英文 Security and trust。

详细文档

请从英文文档目录开始；其中链接到 Getting started、Concepts、Semantic retrieval、Security and trust， 以及实现者用的 architecture、database、execution-ledger 和 client-compatibility 文档。