kioku-mesh 项目说明书

Doramagic 项目包 · 项目说明书

kioku-mesh 项目

面向 AI 编程 Agent 的跨工具、跨机器共享内存，本地优先使用 SQLite，可选用 Zenoh 加 RocksDB 组成网络，基于 MCP 协议。

Overview and System Architecture

kioku-mesh 是一个面向 AI 编程代理（Claude Code、Codex CLI、Gemini CLI 等）的跨主机、跨工具共享记忆层。它把分散在每台机器、每个 CLI 工作目录中的上下文沉淀到一个可被多端复用的持久存储里，从而让下一个代理能够继承前一个代理留下的笔记、项目历史和参考资料资料来源：[README.md:1-120]()。

章节 相关页面

继续阅读本节完整说明和来源证据。

项目定位与设计目标

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 的规划，单仓库被划分为三个职责清晰的子模块：

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。

Memory Store: Storage, Replication, and Visibility Tiers

Memory Store 是 kioku-mesh 的核心子系统，负责把 AI 编码 agent 产生的 observation（观察记录）持久化到 Zenoh mesh，并提供跨主机、跨 agent 的统一读取与回收路径。系统采用 ADR-0023 定义的"core / memory / messaging / bridge"四层结构。core 层封装 Zenoh 会话、...

章节 相关页面

继续阅读本节完整说明和来源证据。

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。

flowchart LR
  subgraph A["Host A"]
    A1["Claude/Codex save"] --> AZ["zenohd · RocksDB<br/>source of truth"]
    AZ --> AS["SQLite LocalIndex<br/>sidecar fast read"]
  end
  subgraph B["Host B"]
    BZ["zenohd · RocksDB"] --> BS["SQLite LocalIndex"]
    B1["Codex/Gemini save"] --> BZ
  end
  AZ <==>|"Zenoh replication<br/>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。

Security, Identity, and Configuration

kioku-mesh 的安全体系建立在网络准入 → 传输层 mTLS 认证 → 应用层作用域（scope）过滤的纵深防御之上。第一层依赖 Tailscale / WireGuard / 可信 LAN 这样的网络层隔离；第二层通过 v0.4.0 引入的可选 mTLS 在 Zenoh 传输层验证对端身份；第三层在应用层通过 visibility 字段（mesh / team...

章节 相关页面

继续阅读本节完整说明和来源证据。

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。

按照 ADR-0023 的分层设计，Zenoh 会话、mTLS、identity、keyspace 与 config 基础设施被统一收敛到 core/ 层，作为 memory/ 与 messaging/ 的公共底座资料来源：src/mesh_mem/core/__init__.py。这种分层避免了上层模块各自重复实现 TLS、配置解析与身份识别逻辑。

flowchart LR
  subgraph L7["应用层 (memory / messaging)"]
    A1[visibility=mesh/team/user]
    A2[Keyspace 解析]
  end
  subgraph L4["传输层 (core/tls.py)"]
    T1[CA 私钥<br/>ca.key + ca.crt]
    T2[对端 CSR<br/>→ 签名 → 证书]
    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。.kioku-mesh.yaml 项目级配置遵循 .editorconfig 风格，从当前目录向上递归搜索资料来源：src/mesh_mem/core/config.py。需要注意的是，提交到仓库的项目配置文件只能写 default_visibility 与 team_id，永远不能写 user_id**——这能防止个人信息随代码泄露资料来源：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。

3. mTLS 证书与入网流程

v0.4.0 引入的可选 mTLS 走的是 CSR 模式的小型私有 PKI，避免了“CA 直接 mint 一切再 scp 私钥”的反模式资料来源：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。

CLI 层（__main__.py）将这套核心能力封装为 tls init-ca / tls request / tls sign / tls install / tls info 子命令资料来源：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。

4. 配置层（Configuration）

kioku-mesh 维护两套独立配置：

zenohd JSON5 配置文件：由 kioku-mesh init --mode {local,hub,spoke} 生成，描述监听端点、对端连接、mTLS 证书路径与 RocksDB 存储后端。hub 模式提供 LAN 监听，spoke 模式必须通过 --connect 指向 hub 资料来源：src/mesh_mem/__main__.py。
kioku-mesh YAML 配置（~/.config/kioku-mesh/config.yaml）：仅存放 kioku-mesh 自身的运行时设置，如选择哪个后端、user_id / team_id / default_visibility 等资料来源：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。

5. 数据模型的前向兼容

Observation 在 from_json 中对未知 memory_type / visibility 字段采取 clamp + DEBUG 日志 策略：把未知枚举值降级为合法值后仍允许写入，原始值丢弃资料来源：src/mesh_mem/core/models.py。messaging.Message 走相反策略——把未知字段收纳到 _extras 中随序列化往返，保留前向扩展空间资料来源：src/mesh_mem/messaging/models.py。memory/purge.py 则对 tombstone 的 key 后缀与 body 字段做一致性校验，防御错位的删除请求误删不相关 obs 资料来源：src/mesh_mem/memory/purge.py。

MCP Integration, CLI, Messaging, and Operations

kioku-mesh 对外暴露三层操作面：用于人工与脚本的 CLI、供 AI 编码代理调用的 MCP stdio 服务、以及面向代理间通信的 messaging 层（ADR-0022）。CLI 在 src/meshmem/main.py 中以 argparse 实现，是同一套 store 原语的薄包装，与 MCP 服务器共享底层函数。社区近期工作集中在 ADR-0022 m...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 键空间与作用域

继续阅读本节完整说明和来源证据。

章节 数据模型与 TTL spool

继续阅读本节完整说明和来源证据。

概述

kioku-mesh 对外暴露三层操作面：用于人工与脚本的 CLI、供 AI 编码代理调用的 MCP stdio 服务、以及面向代理间通信的 messaging 层（ADR-0022）。CLI 在 src/mesh_mem/__main__.py 中以 argparse 实现，是同一套 store 原语的薄包装，与 MCP 服务器共享底层函数。社区近期工作集中在 ADR-0022 messaging MVP（issues/185）与 ADR-0023 将 core / memory / messaging 三层分离的重构（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）。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）。

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/multi-agent.md。ADR-0022 messaging MVP 中，MCP 被指定为消息接收的正路径——具体为 check_messages 与 ack_message 两个 poll 工具（issues/185）。

Messaging 层（ADR-0022）

键空间与作用域

messaging 模块的 Zenoh key 由 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）：

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 讨论 mTLS cert subject 与 Zenoh ACL 的硬绑定；issues/192 评估 mesh-scope presence 的默认开/关 UX；issues/193 解决同一 agent 多 session 的 ack 聚合。

数据模型与 TTL spool

Message 与 Ack 定义在 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 提供，是纯内存字典实现：put() 在 msg_id 上幂等，使重试天然安全；get() 与 list_active() 按 expires_at 在客户端过滤过期消息而不删除，需主动 purge_expired() 回收内存（资料来源：src/mesh_mem/messaging/spool.py:10-40）。Phase 2 会将 spool 后端换成 Zenoh 存储订阅（spool.py 顶部 TODO 标注）。

运维：mTLS、配置与进程收尾

mTLS 由 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/messaging/keyspace.py:1-12）。CLI 的会话清理顺序（资料来源：src/mesh_mem/__main__.py:700-720）正是 core/ 提供的幂等关闭原语的典型组合用法。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 失败模式：installation: mesh-mem v0.2.4

Upgrade or migration may change expected behavior: mesh-mem v0.2.4

medium 失败模式：installation: mesh-mem v0.2.5

Upgrade or migration may change expected behavior: mesh-mem v0.2.5

medium 失败模式：installation: mesh-mem v0.3.0

Upgrade or migration may change expected behavior: mesh-mem v0.3.0

medium 失败模式：installation: v0.3.1

Upgrade or migration may change expected behavior: v0.3.1

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录