Kirok Memory

Kirok

English | 日本語

通过 MCP 为 AI Agent 提供持久记忆。 Kirok（記録，“记录”）是一个 模型上下文协议 服务，为 Agent 提供持久、可搜索的记忆：保留重要内容，通过语义与关键词混合搜索来回忆，并通过反思将积累的记忆提炼为可重复使用的洞见。后台整合循环会自动将原始记忆转化为更高层次的观察。

为什么选择 Kirok

大多数“Agent 记忆”要么是扁平的向量存储（只能进行简单的余弦 top-k 检索，没有关键词依据，也不会遗忘），要么是一堆 Agent 每轮都必须重新阅读的 Markdown。Kirok 是一个小巧、可自托管的服务，能够妥善处理检索工程：

• 混合检索，而非只有向量。 语义 KNN 与 FTS5 BM25 通过倒数排名融合进行合并，使精确关键词匹配与语义匹配相互增强，而不是彼此竞争。
• 经过校准的相关性下限。 朴素的余弦阈值无法适用于真实的嵌入分布（参见搜索质量）；Kirok 的下限根据实时数据测量，并提供评估工具以确保其可靠。
• 自主整合。 记忆会定期综合为观察结果；对于具有破坏性的 LLM 决策，会进行软删除并保留审计记录，而不是盲目执行。
• 可靠性优先。 原子写入、软删除、启动时自动创建快照，以及永不丢失 retain 的故障开放式后台流水线。

**并非本地优先：**存储在你拥有的本地 SQLite 文件中，但嵌入和 LLM 推理会发送至 Google Gemini API。如果你要求所有内容都必须留在设备上，Kirok 暂时不适合你。

架构

flowchart TB
    client["MCP Client<br/>(Claude Desktop / Claude Code / Cursor / …)"]
    subgraph server["Kirok MCP Server (FastMCP)"]
        direction TB
        tools["19 MCP tools<br/>Retain · Recall · Reflect · consolidate · CRUD"]
        pipeline["Hybrid search (RRF) · Smart dedup<br/>Consolidation · Auto-refresh"]
    end
    subgraph storage["Local SQLite (WAL)"]
        direction LR
        fts["FTS5 trigram<br/>(BM25 keyword)"]
        vec["sqlite-vec<br/>(KNN, brute-force fallback)"]
        tables["memories · observations<br/>mental_models · banks · system_events"]
    end
    gemini["Google Gemini API<br/>gemini-embedding-001 (3072-d)<br/>gemini-2.5-flash-lite"]

    client <-->|"stdio (JSON-RPC 2.0)"| tools
    tools --> pipeline
    pipeline <--> storage
    pipeline <-->|embeddings · entity extraction<br/>reflection · consolidation| gemini

存储使用位于 ~/.kirok/memory.db 的单个 SQLite 数据库。sqlite-vec 提供按存储区划分的向量 KNN；如果无法加载原生扩展，Kirok 会回退到 NumPy 暴力扫描，结果完全相同。完整设计请参阅 docs/architecture.md。

🚀 快速开始

**要求：**Python 3.12+、uv（用于 uvx），以及一个 Gemini API 密钥（免费套餐完全够用）。

Kirok 已发布在 PyPI 上——无需克隆仓库。将密钥写入 ~/.kirok/.env（单行：GEMINI_API_KEY=AIza...），然后验证设置：

uvx --from kirok-mcp kirok-doctor   # offline sanity check

连接 MCP 客户端

Claude Code CLI：

claude mcp add kirok -s user -- uvx kirok-mcp

Claude Desktop——编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "kirok": { "command": "uvx", "args": ["kirok-mcp"] }
  }
}

然后重启客户端。服务会从 ~/.kirok/.env 读取 GEMINI_API_KEY；客户端配置中的 env 区块也可生效，并且优先级更高。

来自源代码（开发版）

git clone https://github.com/TadFuji/kirok-mcp.git
cd kirok-mcp
uv sync                       # installs deps, including sqlite-vec
cp .env.example .env          # then put your key in it: GEMINI_API_KEY=AIza...
uv run kirok-doctor           # offline sanity check of the whole setup

使用 uv run --directory /absolute/path/to/kirok-mcp kirok-mcp 将 MCP 客户端指向代码检出目录，而不是使用 uvx kirok-mcp。

提示

如果 uv run 无法启动服务（在 Windows 或云同步文件夹中很常见——uv run 每次启动都会重新同步，可能遇到被锁定的 .venv 文件或正在使用的入口点 .exe），可直接调用虚拟环境中的 Python，完全跳过同步：

{
  "mcpServers": {
    "kirok": {
      "command": "/absolute/path/to/kirok-mcp/.venv/bin/python",
      "args": ["-m", "kirok_mcp.server"],
      "env": { "PYTHONPATH": "/absolute/path/to/kirok-mcp/src" }
    }
  }
}

在 Windows 上使用 .venv\\Scripts\\python.exe，并在 JSON 中使用双反斜杠路径。

skills/kirok/ 中附带的 Agent 技能会教 Agent 何时以及如何自行使用记忆工具——将客户端指向 skills/kirok/SKILL.md 即可启用。

🛠️ 工具

共 19 个 MCP 工具。下方为单行摘要；完整参数表见 docs/tools-reference.md。

核心

工具	用途
KIROK_retain	存储记忆：提取实体/关键词 + 生成嵌入 + 智能 ADD/UPDATE/NOOP 去重
KIROK_recall	混合语义 + 关键词搜索（RRF），优先显示观察结果
KIROK_reflect	将记忆综合为心智模型（洞见），可选择自动刷新
KIROK_smart_retain	先评估重要性（1–10），仅在达到阈值时保留
KIROK_consolidate	手动对记忆库运行观察整合

记忆管理

工具	用途
KIROK_get_memory / KIROK_list_memories	获取一条记忆 / 分页浏览记忆库
KIROK_update_memory	编辑内容或上下文（内容更改时会重新提取并生成嵌入）
KIROK_forget	删除一条记忆（不可撤销）

心智模型

工具	用途
KIROK_list_mental_models / KIROK_get_mental_model	列出 / 检查 Reflect 生成的洞见
KIROK_refresh_mental_model	根据当前记忆重新分析
KIROK_delete_mental_model	删除一个心智模型（不可撤销）

记忆库

工具	用途
KIROK_list_banks / KIROK_stats	列出记忆库及其数量 / 查看各记忆库的详细统计信息，包括后台失败情况
KIROK_clear_bank	删除记忆库中的记忆和观察结果（需要 confirm=true；否则仅预览）
KIROK_delete_bank	完全删除一个记忆库（需要 confirm=true；否则仅预览）

配置

工具	用途
KIROK_set_bank_config / KIROK_get_bank_config	设置 / 查看记忆库的保留和观察“任务”（关注内容）

⚙️ 配置

所有设置均通过环境变量配置（通常位于 .env 中）。只有 GEMINI_API_KEY 是必需的。

变量	默认值	描述
GEMINI_API_KEY	—	必需。 Google Gemini API 密钥。
KIROK_DB_PATH	~/.kirok/memory.db	SQLite 数据库位置。
KIROK_DEDUP_THRESHOLD	0.85	余弦相似度高于此值时，retain 会调用 LLM 执行去重决策（ADD/UPDATE/NOOP）。
KIROK_RECALL_MIN_SIMILARITY	0.62	recall 中语义记忆命中的相似度下限。关键词/FTS 命中不受此限制。
KIROK_OBS_MIN_SIMILARITY	0.62	recall 中观察结果命中的相似度下限。
KIROK_CONSOLIDATION_BATCH_SIZE	5	仅当待处理记忆达到此数量时才运行自动整合（1 = 每次 retain 都运行）。
KIROK_CONSOLIDATION_TIMEOUT	120	整合超时时间，单位为秒。
KIROK_REFLECT_TIMEOUT	300	Reflect 超时时间，单位为秒。
KIROK_AUTO_SNAPSHOT_HOURS	24	启动时自动快照的最小间隔小时数（0 表示禁用）。
KIROK_SNAPSHOT_KEEP	5	自动快照保留的版本数，超出时轮换删除最旧版本。

🔍 搜索质量

Recall 会并行运行语义 KNN 和 FTS5 BM25，并使用 Reciprocal Rank Fusion（k=60）融合结果。简短的日语关键词查询会得到特殊处理：1–2 个字符的汉字／片假名词元短于三元词元分析器的 3 字符窗口，因此永远无法 MATCH；系统会在 BM25 命中结果后追加精确子串 LIKE 补充结果，将它们找回（仅由平假名组成的短词元仍会被排除——功能词会匹配到半个知识库；词元之间使用 OR 连接，与 MATCH 一侧一致）。

三个细节确保混合检索可靠：每个数据源获取的结果都多于最终页面所需数量（max(limit*3, 30)），这样 RRF 就能提升在两个列表中都刚好排在截断位置之外的条目；所有 FTS 文本在索引和查询两侧都会进行 NFKC 规范化，因此全角与半角变体（ＭＣＰ 与 MCP、ﾊﾞｸﾞ 与 バグ）确实能够匹配；观察记录也会像记忆一样采用相同的混合处理方式——语义命中受相似度下限约束，关键词命中则不受下限限制——而不是只能通过语义下限找到。

相似度下限依据真实数据校准。 这里简单的余弦阈值并不适用：在实际的 gemini-embedding-001 向量上，分数分布很集中——不相关查询对无关知识库的得分为 0.55–0.62，而真正的命中得分为 0.66–0.73。因此，可用的下限设在略高于无关结果上限的位置，即 0.62。如果没有这个下限，无关查询仍会从任何非空知识库中返回整页记忆（造成上下文污染）；如果设得低得多，下限则不会过滤任何内容（旧的硬编码值 0.4 甚至低于无关结果的分数）。FTS 关键词命中完全不受下限限制——字面词项匹配是独立的证据，并非较弱的向量分数。

搜索参数不是凭感觉调出来的。scripts/search_eval.py 会使用服务器实际采用的同一套 Recall 流程（提取为 hybrid_search_memories，确保测试工具与生产环境保持一致）运行一组黄金查询，并报告 hit@1/hit@5/hit@k 和 MRR：

cp scripts/search_eval.example.json my_golden.json   # add 30–50 real cases
uv run python scripts/search_eval.py my_golden.json --limit 10

🛡️ 可靠性

• 原子式整合。 每次创建／更新所需的嵌入都会在任何数据库写入之前生成；所有观察记录变更与“已整合”标记都会在单个事务中提交。任何步骤发生故障，数据库都会保持原样，源记忆仍处于待处理状态，可供之后重试——绝不会出现只应用了一半的批次。
• 故障会明确报告，绝不伪装成功。 整合 LLM 发生故障时会抛出异常并记录到 system_events——该批次会保持待处理状态，供之后重试，而不会在未生成任何内容的情况下被悄悄标记为已整合。每个知识库的运行都会串行执行，因此即使同时到达两次 retain，也不会重复处理同一批次并生成重复的观察记录。
• 软删除并保留审计记录。 如果整合 LLM 决定移除某条观察记录，系统会为其标记 deprecated_at（从搜索／列表／统计结果中排除），而不是将其销毁；去重 UPDATE 会在合并事务中记录合并前的内容——两者都会记录到 system_events，因此错误的 LLM 决策可以恢复，不会导致无声的数据丢失。
• 启动时自动创建快照。 启动时，如果最新的自动快照已超过 KIROK_AUTO_SNAPSHOT_HOURS，系统会通过 VACUUM INTO + integrity_check 在 ~/.kirok/backups/ 下创建快照，并保留最新的 KIROK_SNAPSHOT_KEEP 个版本。如果快照创建过程中途失败，不会留下损坏文件；手动备份永远不会被轮换删除。
• 并发控制。 连接会设置 PRAGMA busy_timeout=30000，因此第二个 MCP 客户端会等待正在忙碌的写入操作，而不是因 database is locked 而失败。
• 后台任务失败时不阻断主流程。 自动整合和心智模型刷新在 retain 后台运行，绝不会导致 retain 失败——错误会被吞掉并记录到 system_events，同时通过 KIROK_stats 提供，确保系统性能悄然退化时仍能被发现。

💾 备份与恢复

所有状态都存储在一个 SQLite 文件中。离线 kirok-backup CLI 无需 API 密钥：

uv run kirok-backup snapshot        # byte-level DB copy (safe while server runs)
uv run kirok-backup export          # portable JSON of all banks + memories + observations + models
uv run kirok-backup import ~/.kirok/backups/kirok-export-YYYYMMDD-HHMMSS.json

snapshot 和 export 会在 ~/.kirok/backups/ 下写入带时间戳的文件，并且不会覆盖现有文件。import 会在一个事务中运行（要么全部成功，要么全部失败），跳过已存在的 ID，而不覆盖它们，并重建 FTS + 向量索引，以便立即使用搜索。使用 --db 指定其他数据库文件。

🩺 诊断

uv run kirok-doctor            # offline: Python version, .env, key presence (never printed),
                               # required modules, FTS5, sqlite-vec, DB writability
uv run kirok-doctor --json     # machine-readable, for automation
uv run kirok-doctor --online   # adds one live embedding call to verify Gemini connectivity

🧑‍💻 开发

uv sync
uv run --no-sync pytest        # 164 offline tests; no API key or network needed

整个测试套件完全离线运行——导入 kirok_mcp.server 不会产生副作用（API 密钥会在启动时检查，而不是在导入时检查），且测试会替换为伪造的 Gemini 客户端。每次推送时，CI 都会在 Ubuntu 和 Windows 上运行同一套测试（.github/workflows/test.yml）。提交 PR 前，请先阅读 CONTRIBUTING.md。

📚 文档

• docs/architecture.md — 内部设计、数据模型、整合引擎
• docs/tools-reference.md — 全部 19 个工具的完整参数参考
• CHANGELOG.md — 版本历史（当前版本：1.4.2）

📄 许可证

MIT — 详见 LICENSE。

致谢

• Model Context Protocol 和官方 MCP Python SDK（FastMCP）
• 用于嵌入和大模型的 Google Gemini API
• Mem0 — 智能去重和知识层的灵感来源
• 倒数排名融合（Cormack 等，2009）