# https://github.com/h-wata/kioku-mesh 项目说明书 生成时间：2026-06-24 06:35:09 UTC ## 目录 - [Overview and System Architecture](#page-1) - [Memory Store: Storage, Replication, and Visibility Tiers](#page-2) - [Security, Identity, and Configuration](#page-3) - [MCP Integration, CLI, Messaging, and Operations](#page-4) ## Overview and System Architecture ### 相关页面 相关主题：[Memory Store: Storage, Replication, and Visibility Tiers](#page-2), [Security, Identity, and Configuration](#page-3), [MCP Integration, CLI, Messaging, and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/h-wata/kioku-mesh/blob/main/README.md) - [src/mesh_mem/__main__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/__main__.py) - [src/mesh_mem/core/__init__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/__init__.py) - [src/mesh_mem/core/config.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/config.py) - [src/mesh_mem/core/models.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/models.py) - [src/mesh_mem/messaging/__init__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/__init__.py) - [src/mesh_mem/messaging/keyspace.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/keyspace.py) - [src/mesh_mem/messaging/models.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/models.py) - [src/mesh_mem/memory/replication.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/replication.py) - [src/mesh_mem/memory/purge.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/purge.py) - [src/mesh_mem/backend.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/backend.py)
# Overview and System Architecture ## 项目定位与设计目标 kioku-mesh 是一个面向 AI 编程代理（Claude Code、Codex CLI、Gemini CLI 等）的**跨主机、跨工具共享记忆层**。它把分散在每台机器、每个 CLI 工作目录中的上下文沉淀到一个可被多端复用的持久存储里，从而让下一个代理能够继承前一个代理留下的笔记、项目历史和参考资料 资料来源：[README.md:1-120]()。 整个系统的设计围绕三条原则展开： - **本地优先、远端补齐**：每台主机保留一份本地的 SQLite 索引用于快速读取，远端变更通过 Zenoh mesh 异步复制过来 资料来源：[README.md:60-110]()。 - **网络层与传输层分离**：Tailscale / WireGuard / 可信 LAN 负责网络准入，Zenoh mTLS（v0.4.0 引入）负责传输层身份认证 资料来源：[README.md:90-130]()。 - **层化、低耦合**：ADR-0023 把代码拆成 `core` / `memory` / `messaging` 三层，`memory` 与 `messaging` 都以 `core` 为共享底座，但二者互不依赖 资料来源：[src/mesh_mem/core/__init__.py:1-10]()。 ## 分层架构（ADR-0023） 按照 ADR-0023 的规划，单仓库被划分为三个职责清晰的子模块： ```mermaid flowchart TB subgraph CORE["core/（共享底座）"] SESSION["Zenoh 会话 / mTLS"] IDENTITY["identity / presence"] KEYSPACE["keyspace 工具"] CFG["~/.config/kioku-mesh/"] end subgraph MEM["memory/（长期记忆）"] BACKEND["backend.py（读 / 写 / 搜索）"] REPL["replication.py（rebuild 策略）"] PURGE["purge.py（tomb + GC）"] end subgraph MSG["messaging/（短期消息，ADR-0022）"] KEYS["keyspace.py（msg/team/... 等）"] MODELS["models.py（Message / Ack）"] end CORE --> MEM CORE --> MSG MEM -.->|"bridge 预留"| MSG ``` - `core` 提供共享的 Zenoh 会话生命周期、mTLS 身份、keyspace 解析工具与配置加载 资料来源：[src/mesh_mem/core/__init__.py:1-10]()。 - `memory` 是 `core` 的消费者，承担观测值的写入、检索、复制协调与回收 资料来源：[src/mesh_mem/memory/replication.py:1-50]()。 - `messaging` 是 ADR-0022 引入的实验层，承载 direct 1:1 投递与 TTL inbox spool；它的 keyspace 模块明确声明「不直接 import memory 模块」 资料来源：[src/mesh_mem/messaging/keyspace.py:1-15]()。 后端入口 `src/mesh_mem/backend.py` 已迁移到 `mesh_mem.memory.backend`，原文件仅以 `sys.modules` 替换的方式保留向后兼容 资料来源：[src/mesh_mem/backend.py:1-10]()。 ## 部署拓扑与运行模式 CLI `kioku-mesh init --mode` 提供了三种部署形态，覆盖从单机到多主机的完整路径 资料来源：[src/mesh_mem/__main__.py:init 段]()： | 模式 | 是否启动 zenohd | 持久化 | 典型场景 | |---|---|---|---| | `local` | 否 | SQLite | 单机快速试用，零守护进程 | | `hub` | 是 + RocksDB | RocksDB + 监听端口 | 多主机拓扑中的中心节点 | | `spoke` | 是 + RocksDB | RocksDB + 拨号 hub | 笔记本电脑、CI 从端 | README 推荐的星形拓扑是「一个 hub + 若干 spoke」：hub 常驻并监听 LAN / Tailscale / VPN，spoke 只拨号到 hub，不再相互直连 资料来源：[README.md:80-130]()。v0.4.1 起，旧的 `init --mode localhost` 被移除，因为它既非持久化也被 `--mode local` 与 `kioku-mesh mesh start` 完全覆盖 资料来源：[README.md release notes v0.4.1]()。 ## 关键子系统与数据流 **本地读路径**：每次 `save` / `search` 调用首先落在本地 SQLite 索引上，从而保持 sub-second 响应；写入会同步发往 Zenoh，由远端 hub 或 spoke 复制到对端 资料来源：[src/mesh_mem/memory/replication.py:1-60]()。 **复制策略**：`replication.py` 通过 `_should_rebuild_on_init()` 与 `_empty_index_rebuild_allowed()` 决定新连接的 spoke 是否需要从 Zenoh 反向重建本地索引；这正是 v0.3.2 修复「fresh spoke reports `count: 0`」问题的关键逻辑 资料来源：[src/mesh_mem/memory/replication.py:30-90]()。 **消息通道**：ADR-0022 设计了六类 key 形状，覆盖 mesh 广播、team / user 作用域以及 session / agent 直投 inbox 与显式 ack 资料来源：[src/mesh_mem/messaging/keyspace.py:1-60]()。`Message` 与 `Ack` 数据模型在序列化时保留未知字段以便向前兼容 资料来源：[src/mesh_mem/messaging/models.py:1-90]()。 **回收与 tomb**：`memory/purge.py` 在收到 tomb 时会校验 key 后缀与 body `observation_id` 是否一致，避免被错路由的 tomb 误删无关观测；同时触发一次跨命名空间的清扫以兼容 rolling upgrade 场景 资料来源：[src/mesh_mem/memory/purge.py:tomb 段]()。 ## 配置、身份与可见性 全局配置位于 `~/.config/kioku-mesh/config.yaml`，存放 `default_visibility`、`team_id` 等运行时参数 资料来源：[src/mesh_mem/core/config.py:1-60]()。项目级默认值可放在仓库根的 `.kioku-mesh.yaml`，CLI 会沿父目录向上查找；`user_id` **不会**从该文件读取——按 ADR-0019 的原则，提交进仓库的文件不应设定个人命名空间 资料来源：[src/mesh_mem/core/config.py:PROJECT_CONFIG_NAME]()。 可见性分层（mesh / team / user）由 v0.5.0 起开始贯穿所有 reader；`Observation` 模型在反序列化时对未知的 `memory_type` 静默 clamp 为 `note`，以保证前向兼容 资料来源：[src/mesh_mem/core/models.py:from_json 段]()。messaging 层后续将把 mTLS 证书 subject 与 Zenoh ACL 绑定，以实现 `msg/team/...` 与 `msg/user/...` 的硬授权（ADR-0014 + 正在讨论的 #191） 资料来源：[src/mesh_mem/messaging/keyspace.py:1-30]()。 ## See Also - [MCP Clients 与多代理接入](docs/mcp-clients.md) - [多主机 mesh 部署 walkthrough](README.md#multi-host-mesh) - [ADR-0022：消息流层设计](docs/adr/0022-zenoh-agent-messaging-flow-layer.md) - [ADR-0023：单仓库 core / memory / messaging 层化](docs/adr/0023-single-repo-core-memory-messaging-layering.md) - [ADR-0024：mesh_mem → kioku_mesh 包名迁移](docs/adr/0024-rename-package-mesh-mem-to-kioku-mesh.md) --- ## Memory Store: Storage, Replication, and Visibility Tiers ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Security, Identity, and Configuration](#page-3), [MCP Integration, CLI, Messaging, and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/mesh_mem/memory/store.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/store.py) - [src/mesh_mem/memory/backend.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/backend.py) - [src/mesh_mem/memory/local_index.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/local_index.py) - [src/mesh_mem/memory/replication.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/replication.py) - [src/mesh_mem/memory/pending_queue.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/pending_queue.py) - [src/mesh_mem/memory/purge.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/purge.py) - [src/mesh_mem/core/models.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/models.py) - [src/mesh_mem/core/__init__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/__init__.py) - [src/mesh_mem/memory/__init__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/__init__.py) - [src/mesh_mem/backend.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/backend.py) - [src/mesh_mem/__main__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/__main__.py) - [README.md](https://github.com/h-wata/kioku-mesh/blob/main/README.md)
# Memory Store：存储、复制与可见性分级 ## 概述与分层定位 Memory Store 是 kioku-mesh 的核心子系统，负责把 AI 编码 agent 产生的 observation（观察记录）持久化到 Zenoh mesh，并提供跨主机、跨 agent 的统一读取与回收路径。系统采用 ADR-0023 定义的"core / memory / messaging / bridge"四层结构。`core` 层封装 Zenoh 会话、mTLS、identity 与 keyspace 等共享基础设施，被其余三层依赖；`memory` 层在 `core` 之上提供 store、local_index、pending_queue、purge、backend 等模块，本身不依赖 `messaging` 或 `bridge` 资料来源：[src/mesh_mem/memory/__init__.py:1-7]()、资料来源：[src/mesh_mem/core/__init__.py:1-5]()。 `mesh_mem.backend` 在历史代码中曾被直接 import；按 ADR-0023 已迁移至 `src/mesh_mem/memory/backend.py`，旧路径仅以模块别名方式保留以保持后向兼容 资料来源：[src/mesh_mem/backend.py:1-7]()。 ## 存储模型：Zenoh 为主，SQLite 为旁路 存储采用"双层真相"模型。**Zenoh-RocksDB 是 source of truth**：每一次 `put_observation` 都先写入 Zenoh 存储后端，由 Zenoh 自身的 mesh 复制协议在多机之间同步 资料来源：[README.md:8-22]()。**SQLite LocalIndex 是 fast-read sidecar**：每个进程维护一份 `obs_index` 镜像，`store.search_observations` 自 Phase 3 起直接读取该索引以满足 sub-200ms 的查询目标；当 SQLite 异常时，写入路径仅记录 WARNING 并吞掉错误，确保不会因旁路索引损坏而把一次成功的 Zenoh 写入变成失败 资料来源：[src/mesh_mem/memory/local_index.py:7-19]()。 删除采用"逻辑墓碑"（Tombstone）模式：在镜像 key `mem/tomb/...` 下放置 `Tombstone` 记录，搜索层据此隐藏对应 observation；`mark_deleted` 在索引行上打 `deleted_at` 时间戳而不真正物理删除，物理删除由 `gc` / `purge` 通过 `session.delete` 发起并依赖 Zenoh 复制协议把删除传播给对端 资料来源：[src/mesh_mem/core/models.py:38-52]()、资料来源：[src/mesh_mem/memory/local_index.py:36-58]()。 CLI 层把上述原语以 `save`、`search`、`get`、`delete`、`gc`、`mesh start/join` 等子命令暴露给外部调用，并共用与 MCP server 相同的 store 原子操作 资料来源：[src/mesh_mem/__main__.py:6-12]()。 ## 复制拓扑与可见性分级（ADR-0019） 推荐拓扑是"一 hub、多 spoke"：hub 持续运行并监听 LAN / Tailscale / VPN 可达地址，spoke 仅主动 dial hub，依靠 Zenoh 自带的 TCP 7447 复制完成数据同步 资料来源：[README.md:24-32]()。在 v0.4.0 起，mesh 端到端可启用 mTLS（ADR-0014）作为网络准入之上的传输层对等认证 资料来源：[https://github.com/h-wata/kioku-mesh/releases/tag/v0.4.0]()。 可见性分级是 v0.5.0（ADR-0019 Phase A）引入的关键演进：所有读路径在继续识别旧 `mem/obs/...` 命名空间的同时，**预适配**即将到来的 `mem/mesh/...`、`mem/user/{user_id}/...`、`mem/team/{team_id}/...` 键形，从而为不同范围（mesh 全网 / 单用户 / 单团队）的复制隔离做准备 资料来源：[https://github.com/h-wata/kioku-mesh/releases/tag/v0.5.0]()、`Observation` 与 `Tombstone` 各自在 keyspace 层按 `(visibility, scope_id, ...)` 派生键 资料来源：[src/mesh_mem/core/models.py:14-19]()。 ```mermaid flowchart LR subgraph A["Host A"] A1["Claude/Codex save"] --> AZ["zenohd · RocksDB
source of truth"] AZ --> AS["SQLite LocalIndex
sidecar fast read"] end subgraph B["Host B"] BZ["zenohd · RocksDB"] --> BS["SQLite LocalIndex"] B1["Codex/Gemini save"] --> BZ end AZ <==>|"Zenoh replication
TCP 7447 · mTLS opt."| BZ A1 -.->|"fast read"| AS B1 -.->|"fast read"| BS ``` ## 已知问题与在途重构 社区追踪中的主要技术债包括：(1) `src/mesh_mem/store.py` 已膨胀到 1,608 行 / 59 个函数，承载 Zenoh 会话生命周期、TransportStatus、retry、query 迭代、写入/读取/批量删除等多种职责，#167 计划在 ADR-0019 可见性工作前先做拆分 资料来源：[https://github.com/h-wata/kioku-mesh/issues/167]()；(2) `mesh_mem` → `kioku_mesh` 的包级重命名（ADR-0024，#187）正在进行，需同步更新 `pyproject.toml` 的 package / console_scripts，并保留 import shim 资料来源：[https://github.com/h-wata/kioku-mesh/issues/187]()；(3) 在 `msg/team/{team_id}/**` 与 `msg/user/{user_id}/**` 等范围上，MVP 仍依赖客户端 scope 过滤；mTLS 证书 subject 与 Zenoh ACL 的硬绑定（#191）以及多 session 并行下的 agent 级 ack 聚合（#193）仍是开放设计问题 资料来源：[https://github.com/h-wata/kioku-mesh/issues/191]()、资料来源：[https://github.com/h-wata/kioku-mesh/issues/193]()。 ## See Also - [ADR-0019 Visibility-tiered namespace](https://github.com/h-wata/kioku-mesh/blob/main/docs/adr/) - [ADR-0023 Single-repo core/memory/messaging layering](https://github.com/h-wata/kioku-mesh/blob/main/docs/adr/) - [ADR-0024 Rename package mesh_mem → kioku_mesh](https://github.com/h-wata/kioku-mesh/blob/main/docs/adr/) - [v0.5.0 Release Notes — Visibility-tiered namespace readers](https://github.com/h-wata/kioku-mesh/releases/tag/v0.5.0) - [v0.4.0 Release Notes — Mutual TLS for the mesh](https://github.com/h-wata/kioku-mesh/releases/tag/v0.4.0) --- ## Security, Identity, and Configuration ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Memory Store: Storage, Replication, and Visibility Tiers](#page-2), [MCP Integration, CLI, Messaging, and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/mesh_mem/core/__init__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/__init__.py) - [src/mesh_mem/core/tls.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/tls.py) - [src/mesh_mem/core/config.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/config.py) - [src/mesh_mem/core/models.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/models.py) - [src/mesh_mem/messaging/__init__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/__init__.py) - [src/mesh_mem/messaging/keyspace.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/keyspace.py) - [src/mesh_mem/messaging/models.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/models.py) - [src/mesh_mem/memory/purge.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/memory/purge.py) - [src/mesh_mem/__main__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/__main__.py) - [README.md](https://github.com/h-wata/kioku-mesh/blob/main/README.md)
# Security, Identity, and Configuration ## 1. 概述：三层信任模型 `kioku-mesh` 的安全体系建立在 **网络准入 → 传输层 mTLS 认证 → 应用层作用域（scope）过滤** 的纵深防御之上。第一层依赖 Tailscale / WireGuard / 可信 LAN 这样的网络层隔离；第二层通过 v0.4.0 引入的可选 mTLS 在 Zenoh 传输层验证对端身份；第三层在应用层通过 `visibility` 字段（`mesh` / `team` / `user`）和 key 前缀（`mem/mesh/...`、`mem/team/{team_id}/...`、`mem/user/{user_id}/...`）对写入与读取进行作用域隔离 资料来源：[README.md](README.md)。 按照 ADR-0023 的分层设计，Zenoh 会话、mTLS、identity、keyspace 与 config 基础设施被统一收敛到 `core/` 层，作为 `memory/` 与 `messaging/` 的公共底座 资料来源：[src/mesh_mem/core/__init__.py](src/mesh_mem/core/__init__.py)。这种分层避免了上层模块各自重复实现 TLS、配置解析与身份识别逻辑。 ```mermaid flowchart LR subgraph L7["应用层 (memory / messaging)"] A1[visibility=mesh/team/user] A2[Keyspace 解析] end subgraph L4["传输层 (core/tls.py)"] T1[CA 私钥
ca.key + ca.crt] T2[对端 CSR
→ 签名 → 证书] T3[Zenoh mTLS 握手] end subgraph L3["网络层"] N1[Tailscale / WireGuard / LAN] end L7 --> L4 --> L3 ``` ## 2. 身份与作用域（Identity & Scope） `kioku-mesh` 在三个粒度上识别写入者与命名空间： | 维度 | 字段 | 解析优先级 | 用途 | |------|------|-----------|------| | 全局用户 | `user_id` | `MESH_MEM_USER_ID` 环境变量 → `~/.config/kioku-mesh/config.yaml` | 写入 `mem/user/{user_id}/**` 命名空间 | | 团队 | `team_id` | `MESH_MEM_TEAM_ID` 环境变量 → 项目级 `.kioku-mesh.yaml` → 全局 config | 写入 `mem/team/{team_id}/**` | | 默认可见性 | `default_visibility` | `MESH_MEM_DEFAULT_VISIBILITY` → 项目级 → 全局 | 控制新写入的命名空间 | `user_id` 被刻意 **不** 暴露为 MCP 工具参数，理由与 ADR-0004 中关于 identity 的设计哲学一致：LLM 提供的值会污染 `mem/user/{user_id}/**` 命名空间 资料来源：[src/mesh_mem/core/config.py](src/mesh_mem/core/config.py)。`.kioku-mesh.yaml` 项目级配置遵循 `.editorconfig` 风格，从当前目录向上递归搜索 资料来源：[src/mesh_mem/core/config.py](src/mesh_mem/core/config.py)。需要注意的是，提交到仓库的项目配置文件只能写 `default_visibility` 与 `team_id`，**永远不能写 `user_id`**——这能防止个人信息随代码泄露 资料来源：[README.md](README.md)。 messaging 模块在 keyspace 中也镜像了这一设计：`msg/mesh/{msg_id}`、`msg/team/{team_id}/{msg_id}` 与 `msg/user/{user_id}/{msg_id}` 三种 scope 决定谁能拉取该消息体；收件箱则进一步细化为 `msg/{scope}/inbox/session/{recipient_session_id}/{msg_id}` 与 `msg/{scope}/inbox/agent/{recipient_agent_id}/{msg_id}` 资料来源：[src/mesh_mem/messaging/keyspace.py](src/mesh_mem/messaging/keyspace.py)。 ## 3. mTLS 证书与入网流程 v0.4.0 引入的可选 mTLS 走的是 **CSR 模式的小型私有 PKI**，避免了“CA 直接 mint 一切再 scp 私钥”的反模式 资料来源：[src/mesh_mem/core/tls.py](src/mesh_mem/core/tls.py)。规则如下： - **CA 私钥永远不离开签发主机**，是唯一需要长期保密的密钥； - **每台对端的私钥在本机生成**，通过 CSR（公钥信息）交给 CA 签名； - CSR 与签名后的证书都以 ARMOR 包裹的 base64 文本块传输（标签 `KIOKU-MESH CSR` / `KIOKU-MESH CERT BUNDLE`），方便通过聊天、便笺等任何通道复制粘贴，绕开 `scp` 路径管理 资料来源：[src/mesh_mem/core/tls.py](src/mesh_mem/core/tls.py)。 CLI 层（`__main__.py`）将这套核心能力封装为 `tls init-ca` / `tls request` / `tls sign` / `tls install` / `tls info` 子命令 资料来源：[src/mesh_mem/core/tls.py](src/mesh_mem/core/tls.py)。这套设计也是 #191 议题中“hard authorization——mTLS cert subject ↔ Zenoh ACL for team/user scope”的基础：当前 MVP 阶段只做客户端 scope 过滤，未来要把证书 subject 绑定到 Zenoh ACL 实现真正的硬授权 资料来源：[src/mesh_mem/core/tls.py](src/mesh_mem/core/tls.py)。 ## 4. 配置层（Configuration） `kioku-mesh` 维护两套独立配置： 1. **zenohd JSON5 配置文件**：由 `kioku-mesh init --mode {local,hub,spoke}` 生成，描述监听端点、对端连接、mTLS 证书路径与 RocksDB 存储后端。`hub` 模式提供 LAN 监听，`spoke` 模式必须通过 `--connect` 指向 hub 资料来源：[src/mesh_mem/__main__.py](src/mesh_mem/__main__.py)。 2. **kioku-mesh YAML 配置**（`~/.config/kioku-mesh/config.yaml`）：仅存放 kioku-mesh 自身的运行时设置，如选择哪个后端、`user_id` / `team_id` / `default_visibility` 等 资料来源：[src/mesh_mem/core/config.py](src/mesh_mem/core/config.py)。 为保持 OSS 用户的低运维门槛，CLI 提供 `kioku-mesh mcp install --client {claude-code,codex-cli}` 一键注册 MCP 客户端；多主机场景下，每台 host 都同时跑本地 SQLite 读索引与一台 Zenoh 路由器，路由器之间通过 LAN/VPN/Tailscale 上的 TCP 7447 端口复制 `mem/**` 数据 资料来源：[README.md](README.md)。 ## 5. 数据模型的前向兼容 `Observation` 在 `from_json` 中对未知 `memory_type` / `visibility` 字段采取 **clamp + DEBUG 日志** 策略：把未知枚举值降级为合法值后仍允许写入，原始值丢弃 资料来源：[src/mesh_mem/core/models.py](src/mesh_mem/core/models.py)。`messaging.Message` 走相反策略——把未知字段收纳到 `_extras` 中随序列化往返，保留前向扩展空间 资料来源：[src/mesh_mem/messaging/models.py](src/mesh_mem/messaging/models.py)。`memory/purge.py` 则对 tombstone 的 key 后缀与 body 字段做一致性校验，防御错位的删除请求误删不相关 obs 资料来源：[src/mesh_mem/memory/purge.py](src/mesh_mem/memory/purge.py)。 ## See Also - [ADR-0019 可见性分层命名空间](https://github.com/h-wata/kioku-mesh/blob/main/docs/adr/0019-visibility-tiered-namespace.md) - [ADR-0023 core/memory/messaging 分层](https://github.com/h-wata/kioku-mesh/blob/main/docs/adr/0023-single-repo-core-memory-messaging-layering.md) - [mTLS 入网与 Zenoh 部署](README.md) - [messaging keyspace 解析](src/mesh_mem/messaging/keyspace.py) --- ## MCP Integration, CLI, Messaging, and Operations ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Memory Store: Storage, Replication, and Visibility Tiers](#page-2), [Security, Identity, and Configuration](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/mesh_mem/__main__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/__main__.py) - [src/mesh_mem/mcp_install.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/mcp_install.py) - [src/mesh_mem/messaging/keyspace.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/keyspace.py) - [src/mesh_mem/messaging/models.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/messaging/models.py) - [src/mesh_mem/messaging/spool.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/spool.py) - [src/mesh_mem/core/__init__.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/__init__.py) - [src/mesh_mem/core/tls.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/tls.py) - [src/mesh_mem/core/config.py](https://github.com/h-wata/kioku-mesh/blob/main/src/mesh_mem/core/config.py) - [README.md](https://github.com/h-wata/kioku-mesh/blob/main/README.md)
# MCP Integration, CLI, Messaging, and Operations ## 概述 kioku-mesh 对外暴露三层操作面：用于人工与脚本的 CLI、供 AI 编码代理调用的 MCP stdio 服务、以及面向代理间通信的 messaging 层（ADR-0022）。CLI 在 [src/mesh_mem/__main__.py](src/mesh_mem/__main__.py) 中以 argparse 实现，是同一套 store 原语的薄包装，与 MCP 服务器共享底层函数。社区近期工作集中在 ADR-0022 messaging MVP（[issues/185](https://github.com/h-wata/kioku-mesh/issues/185)）与 ADR-0023 将 core / memory / messaging 三层分离的重构（[issues/186](https://github.com/h-wata/kioku-mesh/issues/186)）。 ## CLI 入口与部署模式 `kioku-mesh init --mode` 选择部署形态，三种取值在 CLI 帮助文本中有完整描述（资料来源：[src/mesh_mem/__main__.py:117-160]()）： | 模式 | 持久化 | 额外服务 | 适用场景 | |---|---|---|---| | `local`（默认） | SQLite | 无 | 单机持久化，最简启动 | | `hub` | RocksDB | zenohd | 长期在线的中心节点 | | `spoke` | RocksDB | zenohd | 拨号到 hub 的边缘节点 | v0.4.1 已移除曾作为烟测路径的 `localhost` 模式（[v0.4.1 release notes](https://github.com/h-wata/kioku-mesh/releases/tag/v0.4.1)）。`kioku-mesh mesh start` 提供无 zenohd 二进制的进程内路由器，适合短期 demo 或跨主机烟测；其文档明确指出路由器重启后跨主机的写入不会被重放（资料来源：[src/mesh_mem/__main__.py:160-200]()）。主程序退出前会以 `try/finally` 顺序调用 `stop_pending_drain_background()`、`reset_backend()`、`_reset_session()`，避免 Zenoh 复制订阅线程使解释器无法正常退出——这是 CLI 必须显式关闭会话的具体原因（资料来源：[src/mesh_mem/__main__.py:700-720]()）。 ## MCP 集成 PyPI 包安装后会产生两个命令： - `kioku-mesh`：上文描述的 CLI。 - `kioku-mesh-mcp`：由 Claude Code、Codex CLI 等代理拉起的 stdio MCP 服务器（[README.md](README.md)）。 `kioku-mesh mcp install` 子命令负责为常见客户端写入注册块，`--client` 支持 `claude-code`、`codex-cli` 等选项；`--env KEY=VALUE` 可重复传入额外环境变量，覆盖每客户端的默认值，`--force` 用于替换同名注册，`--dry-run` 仅打印待执行的命令/配置块（资料来源：[src/mesh_mem/__main__.py:90-120]()）。多客户端的 JSON/TOML 示例与会话钩子配方见 [docs/mcp-clients.md](docs/mcp-clients.md) 与 [docs/multi-agent.md](docs/multi-agent.md)。ADR-0022 messaging MVP 中，MCP 被指定为消息接收的正路径——具体为 `check_messages` 与 `ack_message` 两个 poll 工具（[issues/185](https://github.com/h-wata/kioku-mesh/issues/185)）。 ## Messaging 层（ADR-0022） ### 键空间与作用域 messaging 模块的 Zenoh key 由 [src/mesh_mem/messaging/keyspace.py](src/mesh_mem/messaging/keyspace.py) 集中构造，并遵守 ADR-0023 的依赖规则——不直接 import memory 模块（资料来源：[src/mesh_mem/messaging/keyspace.py:1-12]()）。Phase 1 支持的 key 形态（资料来源：[src/mesh_mem/messaging/keyspace.py:15-30]()）： ```text msg/mesh/{msg_id} — mesh 范围广播（Phase 2+） msg/team/{team_id}/{msg_id} — team 范围 msg/user/{user_id}/{msg_id} — user 范围 msg/{scope}/inbox/session/{recipient_session_id}/{msg_id} — 按 session 投递 msg/{scope}/inbox/agent/{recipient_agent_id}/{msg_id} — 按 agent 投递 msg/{scope}/ack/{msg_id}/{recipient_session_id} — 接收方显式 ack ``` `{scope}` 段即 `mesh | team | user`，决定消息的可见域。社区正在跟踪的几条设计线：[issues/191](https://github.com/h-wata/kioku-mesh/issues/191) 讨论 mTLS cert subject 与 Zenoh ACL 的硬绑定；[issues/192](https://github.com/h-wata/kioku-mesh/issues/192) 评估 mesh-scope presence 的默认开/关 UX；[issues/193](https://github.com/h-wata/kioku-mesh/issues/193) 解决同一 agent 多 session 的 ack 聚合。 ### 数据模型与 TTL spool `Message` 与 `Ack` 定义在 [src/mesh_mem/messaging/models.py](src/mesh_mem/messaging/models.py)，字段覆盖 `sender`、`recipient`、`body`、`content_type`、`requires_ack`、`delivery_adapters`、`correlation_id`、`ttl_sec`、`expires_at`、`sender_seq`、`schema_version` 等；`from_json` 将未知字段收入 `_extras` 以保持前向兼容（资料来源：[src/mesh_mem/messaging/models.py:60-120]()）。 短期收件箱由 [src/mesh_mem/messaging/spool.py](src/mesh_mem/messaging/spool.py) 提供，是纯内存字典实现：`put()` 在 `msg_id` 上幂等，使重试天然安全；`get()` 与 `list_active()` 按 `expires_at` 在客户端过滤过期消息而不删除，需主动 `purge_expired()` 回收内存（资料来源：[src/mesh_mem/messaging/spool.py:10-40]()）。Phase 2 会将 spool 后端换成 Zenoh 存储订阅（[spool.py](src/mesh_mem/messaging/spool.py) 顶部 TODO 标注）。 ## 运维：mTLS、配置与进程收尾 mTLS 由 [src/mesh_mem/core/tls.py](src/mesh_mem/core/tls.py) 实现一套自管的私有 PKI：CA 仅存在于签发主机且私钥不离开该主机；每个 peer 在本地生成私钥，把 CSR（公开信息）发给 CA 签名；中间传输以 base64 + `-----BEGIN KIOKU-MESH CSR/BUNDLE-----` 形式的「可复制粘贴块」代替 scp，免去路径追踪与 SSH 前置（资料来源：[src/mesh_mem/core/tls.py:1-40]()）。CSR 仅含公钥、BUNDLE 仅含已签证书与 CA 证书；`ca.key` 与每个 `peer.key` 始终保留在各自主机。 全局配置写入 `~/.config/kioku-mesh/config.yaml`（受 `XDG_CONFIG_HOME` 覆盖），项目级默认从 `.kioku-mesh.yaml` 读取，按目录向上逐层搜索（`.editorconfig` 风格）；`user_id` 故意不从项目文件读取，以防误提交个人命名空间（资料来源：[src/mesh_mem/core/config.py:20-60]()）。 `core/` 目录是 ADR-0023 拆分出的共享基础设施层，承载 Zenoh 会话、mTLS、identity、keyspace、config；`memory` 与 `messaging` 都作为其消费者，`messaging` 不得反向依赖 `memory`（资料来源：[src/mesh_mem/core/__init__.py](src/mesh_mem/core/__init__.py) 与 [src/mesh_mem/messaging/keyspace.py:1-12]()）。CLI 的会话清理顺序（资料来源：[src/mesh_mem/__main__.py:700-720]()）正是 `core/` 提供的幂等关闭原语的典型组合用法。 ## See Also - [Mesh Architecture and Storage](mesh-architecture.md) - [Identity and Visibility](identity-visibility.md) - [mTLS Enrollment Guide](mtls-enrollment.md) - 相关 ADR：`docs/adr/0022-zenoh-agent-messaging-flow-layer.md`、`docs/adr/0023-single-repo-core-memory-messaging-layering.md`、`docs/adr/0024-rename-package-mesh-mem-to-kioku-mesh.md` --- --- ## Doramagic 踩坑日志 项目：h-wata/kioku-mesh 摘要：发现 23 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: mesh-mem v0.2.4。 ## 1. 安装坑 · 失败模式：installation: mesh-mem v0.2.4 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: mesh-mem v0.2.4 - 对用户的影响：Upgrade or migration may change expected behavior: mesh-mem v0.2.4 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.2.4 | mesh-mem v0.2.4 ## 2. 安装坑 · 失败模式：installation: mesh-mem v0.2.5 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: mesh-mem v0.2.5 - 对用户的影响：Upgrade or migration may change expected behavior: mesh-mem v0.2.5 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.2.5 | mesh-mem v0.2.5 ## 3. 安装坑 · 失败模式：installation: mesh-mem v0.3.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: mesh-mem v0.3.0 - 对用户的影响：Upgrade or migration may change expected behavior: mesh-mem v0.3.0 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.0 | mesh-mem v0.3.0 ## 4. 安装坑 · 失败模式：installation: v0.3.1 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.3.1 - 对用户的影响：Upgrade or migration may change expected behavior: v0.3.1 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.1 | v0.3.1 ## 5. 安装坑 · 失败模式：installation: v0.3.2 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.3.2 - 对用户的影响：Upgrade or migration may change expected behavior: v0.3.2 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.2 | v0.3.2 ## 6. 安装坑 · 失败模式：installation: v0.3.3 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.3.3 - 对用户的影响：Upgrade or migration may change expected behavior: v0.3.3 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.3 | v0.3.3 ## 7. 安装坑 · 失败模式：installation: v0.4.0 — Mutual TLS for the mesh - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.4.0 — Mutual TLS for the mesh - 对用户的影响：Upgrade or migration may change expected behavior: v0.4.0 — Mutual TLS for the mesh - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.4.0 | v0.4.0 — Mutual TLS for the mesh ## 8. 安装坑 · 来源证据：refactor: split store.py monolith before ADR-0019 visibility work - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：refactor: split store.py monolith before ADR-0019 visibility work - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/h-wata/kioku-mesh/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。 ## 9. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/h-wata/kioku-mesh | host_targets=mcp_host, claude_code, claude, gemini_cli, codex ## 10. 配置坑 · 失败模式：configuration: design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up) - 证据：failure_mode_cluster:github_issue | https://github.com/h-wata/kioku-mesh/issues/191 | design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up) ## 11. 配置坑 · 失败模式：configuration: feat(messaging): ADR-0022 messaging MVP の実装（direct 1:1 + MCP poll + TTL inbox spool） - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: feat(messaging): ADR-0022 messaging MVP の実装（direct 1:1 + MCP poll + TTL inbox spool） - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat(messaging): ADR-0022 messaging MVP の実装（direct 1:1 + MCP poll + TTL inbox spool） - 证据：failure_mode_cluster:github_issue | https://github.com/h-wata/kioku-mesh/issues/185 | feat(messaging): ADR-0022 messaging MVP の実装（direct 1:1 + MCP poll + TTL inbox spool） ## 12. 配置坑 · 失败模式：configuration: v0.4.1 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.4.1 - 对用户的影响：Upgrade or migration may change expected behavior: v0.4.1 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.4.1 | v0.4.1 ## 13. 配置坑 · 来源证据：refactor: パッケージ mesh_mem → kioku_mesh リネーム（ADR-0024） - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：refactor: パッケージ mesh_mem → kioku_mesh リネーム（ADR-0024） - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/h-wata/kioku-mesh/issues/187 | 来源类型 github_issue 暴露的待验证使用条件。 ## 14. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/h-wata/kioku-mesh | README/documentation is current enough for a first validation pass. ## 15. 维护坑 · 失败模式：migration: kioku-mesh v0.5.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this migration risk before relying on the project: kioku-mesh v0.5.0 - 对用户的影响：Upgrade or migration may change expected behavior: kioku-mesh v0.5.0 - 证据：failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.5.0 | kioku-mesh v0.5.0 ## 16. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/h-wata/kioku-mesh | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/h-wata/kioku-mesh | no_demo; severity=medium ## 18. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/h-wata/kioku-mesh | no_demo; severity=medium ## 19. 安全/权限坑 · 来源证据：design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/h-wata/kioku-mesh/issues/191 | 来源类型 github_issue 暴露的待验证使用条件。 ## 20. 能力坑 · 失败模式：conceptual: refactor: split store.py monolith before ADR-0019 visibility work - 严重度：low - 证据强度：source_linked - 发现：Developers should check this conceptual risk before relying on the project: refactor: split store.py monolith before ADR-0019 visibility work - 对用户的影响：Developers may hit a documented source-backed failure mode: refactor: split store.py monolith before ADR-0019 visibility work - 证据：failure_mode_cluster:github_issue | https://github.com/h-wata/kioku-mesh/issues/167 | refactor: split store.py monolith before ADR-0019 visibility work ## 21. 能力坑 · 失败模式：conceptual: refactor: パッケージ mesh_mem → kioku_mesh リネーム（ADR-0024） - 严重度：low - 证据强度：source_linked - 发现：Developers should check this conceptual risk before relying on the project: refactor: パッケージ mesh_mem → kioku_mesh リネーム（ADR-0024） - 对用户的影响：Developers may hit a documented source-backed failure mode: refactor: パッケージ mesh_mem → kioku_mesh リネーム（ADR-0024） - 证据：failure_mode_cluster:github_issue | https://github.com/h-wata/kioku-mesh/issues/187 | refactor: パッケージ mesh_mem → kioku_mesh リネーム（ADR-0024） ## 22. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/h-wata/kioku-mesh | issue_or_pr_quality=unknown ## 23. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/h-wata/kioku-mesh | release_recency=unknown