cnb-agentic-memory 2.0.2__tar.gz → 2.0.4__tar.gz

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/.gitignore

@@ -26,3 +26,5 @@ htmlcov/
 .DS_Store
 .Trash-*/
 node_modules/
+# 本地凭据/环境文件（集成测试用）
+.env*

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 ## 开发环境
 
-- Python 3.11+
+- Python 3.10+（下限对齐 EdgeOne Pages Python 运行时版本）
 - [uv](https://docs.astral.sh/uv/) 包管理（推荐）
 
 ## 开发流程

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: cnb-agentic-memory
-Version: 2.0.2
-Summary: CNB Agentic Memory 是基于 CNB 平台构建的通用记忆工具，把 CNB 的 issue、知识库、检索能力组合成一个开箱即用的智能体记忆层。
+Version: 2.0.4
+Summary: CNB Issue 智能体记忆系统（cnb-agentic-memory）是基于 CNB 平台构建的通用记忆工具，把 CNB 的 issue、知识库、检索能力组合成一个开箱即用的智能体记忆层。
 Project-URL: Homepage, https://cnb.cool/xqitw/cnb-agentic-memory
 Project-URL: Repository, https://cnb.cool/xqitw/cnb-agentic-memory
 Project-URL: Issues, https://cnb.cool/xqitw/cnb-agentic-memory/-/issues
@@ -12,13 +12,14 @@ Keywords: agent,cli,cnb,knowledge-base,llm,mcp,memory,skill
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: typer<1,>=0.27.2
@@ -34,12 +35,12 @@ Provides-Extra: mcp
 Requires-Dist: mcp<3,>=2.1.1; extra == 'mcp'
 Description-Content-Type: text/markdown
 
-# CNB Agentic Memory
+# CNB Issue 智能体记忆系统
 
 [![Latest Release](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/release)](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/release.link)
 [![PyPI](https://img.shields.io/pypi/v/cnb-agentic-memory.svg)](https://pypi.org/project/cnb-agentic-memory/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
-[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)](https://www.python.org)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](https://www.python.org)
 ![CI](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/git/latest/ci/pipeline-as-code?branch=main)
 ![git-clone-yyds](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/git/latest/ci/git-clone-yyds)
 [![Star](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/star)](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/star.link)
@@ -59,7 +60,7 @@ Description-Content-Type: text/markdown
 
 开始使用前需要准备三件事：
 
-1. **创建专用私有仓库**——作为记忆仓库。必须是专用仓库（全部 Issue 均为记忆），检索与列表不做记忆/普通 Issue 区分
+1. **创建专用的 [CNB 平台](https://cnb.cool)私有仓库**——作为记忆仓库。必须是专用仓库（全部 Issue 均为记忆），检索与列表不做记忆/普通 Issue 区分
 2. **获取 CNB 访问令牌**——在 CNB 个人设置中创建，需 `repo-issue:rw`（Issue 读写）+ `repo-code:r`（知识库检索）权限
 3. **配置知识库入库流水线**——在记忆仓库的 `.cnb.yml` 挂载 `knowledge:update` 流水线（`$` 键下），语义检索依赖它；**必须先配置再写入**，错过事件的记忆不会被补录
 

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/README.md

@@ -1,9 +1,9 @@
-# CNB Agentic Memory
+# CNB Issue 智能体记忆系统
 
 [![Latest Release](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/release)](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/release.link)
 [![PyPI](https://img.shields.io/pypi/v/cnb-agentic-memory.svg)](https://pypi.org/project/cnb-agentic-memory/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
-[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)](https://www.python.org)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](https://www.python.org)
 ![CI](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/git/latest/ci/pipeline-as-code?branch=main)
 ![git-clone-yyds](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/git/latest/ci/git-clone-yyds)
 [![Star](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/star)](https://cnb.cool/xqitw/cnb-agentic-memory/-/badge/star.link)
@@ -23,7 +23,7 @@
 
 开始使用前需要准备三件事：
 
-1. **创建专用私有仓库**——作为记忆仓库。必须是专用仓库（全部 Issue 均为记忆），检索与列表不做记忆/普通 Issue 区分
+1. **创建专用的 [CNB 平台](https://cnb.cool)私有仓库**——作为记忆仓库。必须是专用仓库（全部 Issue 均为记忆），检索与列表不做记忆/普通 Issue 区分
 2. **获取 CNB 访问令牌**——在 CNB 个人设置中创建，需 `repo-issue:rw`（Issue 读写）+ `repo-code:r`（知识库检索）权限
 3. **配置知识库入库流水线**——在记忆仓库的 `.cnb.yml` 挂载 `knowledge:update` 流水线（`$` 键下），语义检索依赖它；**必须先配置再写入**，错过事件的记忆不会被补录
 

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/docs/API.md

@@ -92,13 +92,13 @@ except ApiError as err:
 设计约定：
 
 - **title 撰写权在调用方**：keyword 检索只匹配标题，title 由智能体撰写（提炼高区分度关键词短语）；未提供时兜底为正文首行截取。工具保证不变量：无控制字符（C0/DEL，实测服务端不拦但会污染检索与知识库）+ 非空 + ≤60 字符。MCP 与 Skill 层需在工具描述中给智能体明确的 title 撰写指导
-- **重定向处理（实测沉淀）**：CNB API 当前未发现重定向场景（cam-test 实测口径，见 #68 评审记录）；httpx 客户端显式声明 `follow_redirects=True`，为网关层未来引入 3xx 预留健壮性
-- **标签字符白名单（实测沉淀，cam-test #78-#81）**：CNB 标签只允许汉字、字母、数字、下划线(_)、小数点(.)、冒号(:)、中划线(-)、正斜杠(/)、反斜杠(\\)、全角字符（U+FF00-FFEF 等宽字符）与中间空格（首尾不能为空格）；长度按 **UTF-8 字节**计数，上限 50 字节（1 汉字/全角字符占 3 字节）。注意："全角符号"不含省略号 …(U+2026) 与破折号 —(U+2014)，实测被服务端拒绝。写路径预检（fail-fast）在发起任何写请求前校验，不合法直接报错，避免孤儿分片
+- **重定向处理（实测沉淀）**：CNB API 当前未发现重定向场景；httpx 客户端显式声明 `follow_redirects=True`，为网关层未来引入 3xx 预留健壮性
+- **标签字符白名单（实测沉淀）**：CNB 标签只允许汉字、字母、数字、下划线(_)、小数点(.)、冒号(:)、中划线(-)、正斜杠(/)、反斜杠(\\)、全角字符（U+FF00-FFEF 等宽字符）与中间空格（首尾不能为空格）；长度按 **UTF-8 字节**计数，上限 50 字节（1 汉字/全角字符占 3 字节）。注意："全角符号"不含省略号 …(U+2026) 与破折号 —(U+2014)，实测被服务端拒绝。写路径预检（fail-fast）在发起任何写请求前校验，不合法直接报错，避免孤儿分片
 - **两步写入**：创建时不传 labels（服务端对新标签静默丢弃），创建后单独补打
 - **写后回读校验**：写操作 GET 回读确认，短重试（3 次 × 0.5s）后仍不一致才报错；`verify=False` 可跳过（仅测试）
 - **超长拆分**：正文超过 30KB 自动按段落拆为多条，title 带 `(i/n)` 序号关联；`WriteResult.parts` 携带全部分片供循迹
 - **软删除**：无硬删除接口（CNB DELETE 返回 404），`delete` 后可 `restore`
-- **标签约定**：`category` 自动补 `category:` 前缀（对齐 CNB 平台分类约定，选择器中单选），`tags` 为普通标签原样保留；记忆仓库须为专用仓库（全部 Issue 均为记忆）
+- **标签约定**：`category` 自动补 `category:` 前缀（对齐 CNB 平台分类约定，选择器中单选），`tags` 为普通标签原样保留；记忆仓库须为 CNB 平台私有仓库，且为专用仓库（全部 Issue 均为记忆）
 - **检索分层**：语义检索走知识库向量召回（相关度受语料规模、查询内容与切分策略影响，PoC 实测样例中可达 0.98+）；`keyword_search` 是与它并列的第二检索方法（标题检索，无需知识库），供 title 含确切关键词时精准直达
 - **分页参数钳制**：limit / top_k 统一钳制到 1~100（CNB 服务端分页上限），SDK 与 CLI / MCP 入口层口径一致
 
@@ -118,7 +118,7 @@ except ApiError as err:
 
 ## 记忆仓库前置条件
 
-**记忆仓库须为专用仓库**：仓库中全部 Issue 均为记忆，不与普通 Issue 混用（检索与列表不做记忆/非记忆区分）。
+**记忆仓库须为 CNB 平台私有仓库，且为专用仓库**：仓库中全部 Issue 均为记忆，不与普通 Issue 混用（检索与列表不做记忆/非记忆区分）。
 
 知识库检索依赖仓库已配置 Issue 事件同步流水线。`.cnb.yml` 事件必须挂在 `$` 键下（顶层写法静默无效），且**先配置流水线再写入记忆**——错过事件的 Issue 不会被补录：
 
@@ -156,4 +156,4 @@ $:
             issueSyncEnabled: true
 ```
 
-写入到可检索有 1~2 分钟同步时延，属平台预期行为。
+写入到可检索的时延取决于仓库流水线配置：事件触发（实时）通常秒级到分钟级；定时触发（如每小时/每日入库）需等下次流水线运行。实际时延还受网络、记忆数量等因素影响。需立即确认写入结果时，按写入返回的 number 用 `memory_get`（CLI `get`）回查。

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/docs/CLI.md

@@ -51,7 +51,7 @@ cnb-agentic-memory get 12
 cnb-agentic-memory append 12 "追加了 pg_partman 配置示例"
 cnb-agentic-memory delete 12   # 软删除，cnb-agentic-memory restore 12 可恢复
 
-# 语义检索（需仓库配置 knowledge:update 流水线，写入后约 1~2 分钟可检索）
+# 语义检索（需仓库配置 knowledge:update 流水线；实时同步通常秒级到分钟级可检索，定时入库需等下次运行，需立即确认用 get 回查）
 cnb-agentic-memory search "分区表 慢查询" --top-k 3
 
 # 关键词标题检索（与 search 并列，无需知识库；title 含确切关键词时更精准）

cnb_agentic_memory-2.0.4/docs/EdgeOne.md

@@ -0,0 +1,36 @@
+# EdgeOne Pages 部署指南
+
+以腾讯云 EdgeOne Pages（EdgeOne Makers）Python 运行时承载本项目的 MCP 服务器，streamable-http 形态，核心代码零改动、仅薄适配层。
+
+## 形态决策
+
+- **streamable-http + `json_response` + `stateless_http`**：EO Cloud Functions 执行时长上限 120s（`edgeone.json` 已配 `cloudFunctions.maxDuration`），SSE 长连接与有状态 session 会被平台切断，不适配
+- 适配层：`cloud-functions/mcp/[[default]].py`——EO 约定 `cloud-functions/` 目录文件即路由，`[[default]].py` 为 catch-all；EO 运行时剥掉函数目录前缀后把请求交给应用内挂载的 MCP ASGI 应用
+- Python 运行时为 3.10（平台硬编码），本项目 `requires-python >= 3.10` 与之兼容
+
+## 部署步骤
+
+1. EO 项目指向本仓库根（构建时自动扫描 `cloud-functions/`）
+2. EO 控制台配置环境变量（值均须 ≤500 字节）：
+
+   | 环境变量 | 必填 | 说明 |
+   | --- | --- | --- |
+   | `CNB_AGENTIC_MEMORY_REQUIRE_HEADERS` | 共享部署必填 | 置 `1` 强制凭据头：请求须带 `X-CNB-Token`/`X-CNB-Repo`（凭据由调用方传递），匿名请求在工具入口即拒绝。**服务端禁止配置 `CNB_AGENTIC_MEMORY_TOKEN`/`CNB_AGENTIC_MEMORY_REPO`**——服务端持凭据 + 漏配本开关时门禁形同虚设 |
+
+   注：EO 会把转发请求的 Host 头改写为平台内部源站域名（动态不可预知），应用层 Host/Origin 白名单不可行；恶意 Host 由 EO 边缘按路由键直接拒绝（未绑定域名 418），匿名与跨源滥用由凭据头门禁阻断，服务端无需配置域名类变量。
+
+3. 部署，二选一：
+   - **web 触发**（推荐）：CNB web 页面「一键部署」按钮（声明见 `.cnb/web_trigger.yml`），支持选择生产/预览环境与项目名
+   - 本地：`npx edgeone pages deploy`
+4. MCP 客户端连接 `https://<对外域名>/mcp`（streamable-http 形态），请求须携带 `X-CNB-Token` 与 `X-CNB-Repo` 请求头（多用户各自传递自己的凭据）
+
+## 依赖说明
+
+`cloud-functions/requirements.txt` 显式声明依赖（用户声明优先级最高，压过 import 自动检测），钉 PyPI 已发布版本。
+
+**发版时序**：升级依赖钉版前须先完成 PyPI 发版（合并 → 打 tag → CI 发布），否则 EO 构建解析失败。
+
+## 已知限制
+
+- 执行时长上限 120s，工具调用须在该窗口内完成；实例回收后冷启动有 import 与连接重建延迟
+- 默认域名 `*.edgeone.app` 实测函数路由 404，请绑定自定义域名访问

cnb_agentic_memory-2.0.4/docs/MCP.md

@@ -0,0 +1,203 @@
+# MCP Server 参考
+
+`cnb-agentic-memory-mcp` 把记忆语义层注册为 MCP 工具，供任何 MCP 客户端（Claude Desktop、CNB AI 助手等）调用。业务逻辑（两步写入、回读校验、title 不变量、超长拆分、软删除）全部在 SDK 层，MCP 是纯适配层。
+
+## 安装与配置
+
+```bash
+pip install "cnb-agentic-memory[mcp]"
+```
+
+配置走 `CNB_AGENTIC_MEMORY_` 前缀环境变量（与 SDK/CLI 一致）：
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `CNB_AGENTIC_MEMORY_TOKEN` | CNB API Token（需 `repo-issue:rw` + `repo-code:r`） |
+| `CNB_AGENTIC_MEMORY_REPO` | 记忆仓库 slug，如 `group/memory` |
+| `CNB_AGENTIC_MEMORY_BASE_URL` | API 地址，默认 `https://api.cnb.cool` |
+| `CNB_AGENTIC_MEMORY_TIMEOUT` | 请求超时秒数，默认 30 |
+
+### 请求头覆盖（多用户共享部署）
+
+HTTP transport（`streamable-http`/`sse`）模式下，各工具在**每次调用时**读取以下请求头，可逐请求覆盖 token/repo 等配置，实现多用户共用一个 MCP 服务实例、各用各的凭据与仓库、互不影响：
+
+| 请求头 | 覆盖的环境变量 | 说明 |
+| --- | --- | --- |
+| `X-CNB-Token` | `CNB_AGENTIC_MEMORY_TOKEN` | 调用方自己的 CNB API Token |
+| `X-CNB-Repo` | `CNB_AGENTIC_MEMORY_REPO` | 调用方自己的记忆仓库 slug |
+| `X-CNB-Base-URL` | `CNB_AGENTIC_MEMORY_BASE_URL` | API 地址（私有化部署场景） |
+
+- 头名大小写不敏感；空值/空白视为未提供；重复同名头取首值
+- **安全约定（全有或全无）**：`X-CNB-Token` 与 `X-CNB-Repo` 必须同时出现才启用头覆盖，否则全部头忽略、整体回落环境变量——防止调用方只改 `X-CNB-Base-URL` 时，服务端环境变量的凭据被发送到调用方指定的任意主机
+- 未携带头或凭据不齐时回落环境变量（与 stdio 行为一致）；stdio 下无请求头，永远走环境变量
+- MCP 框架的 stdio 客户端（Claude Desktop 等）不支持自定义请求头，此类客户端沿用环境变量配置
+
+> 安全提示：凭据经由请求头传输，请务必在 HTTPS/反向代理之后暴露服务，避免明文网络截获；头中的 Token 是调用方自己的凭据，服务端仅透传给 CNB API 用于访问对应仓库，不做存储。
+
+## 传输协议（transport）
+
+支持三种 MCP 传输协议，通过 CLI 参数或环境变量选择（CLI 参数优先）：
+
+| transport | 启动方式 | 端点 | 适用场景 |
+| --- | --- | --- | --- |
+| `stdio`（默认） | 无参数，客户端以子进程拉起 | 标准输入/输出 | 本地客户端（Claude Desktop、CNB AI 助手等） |
+| `streamable-http` | `--transport streamable-http` | `http://<host>:<port>/mcp` | 远程/共享接入（推荐） |
+| `sse` | `--transport sse` | `http://<host>:<port>/sse`（消息回传 `/messages/`） | 仅支持旧版 SSE 的远程客户端 |
+
+```bash
+# stdio（默认，历史行为不变）
+cnb-agentic-memory-mcp
+
+# streamable-http：监听 0.0.0.0:8000，端点 /mcp
+cnb-agentic-memory-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+
+# sse：监听 0.0.0.0:8000，端点 /sse
+cnb-agentic-memory-mcp --transport sse --host 0.0.0.0 --port 8000
+```
+
+| 参数 | 环境变量兜底 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `--transport` | `CNB_AGENTIC_MEMORY_MCP_TRANSPORT` | `stdio` | 传输协议：`stdio` / `sse` / `streamable-http` |
+| `--host` | `CNB_AGENTIC_MEMORY_MCP_HOST` | `127.0.0.1` | HTTP 监听地址，仅 sse/streamable-http 有效；接受域名 / IPv4 / IPv6 / `[IPv6]`；空值/空白回落默认；CLI 畸形地址直接报错，env 畸形值告警回落默认；不接受 `host:port` 与 `[IPv6]:port` 合并形态（端口由 `--port` 指定）；对外暴露时用 `0.0.0.0`（须置于反代之后） |
+| `--port` | `CNB_AGENTIC_MEMORY_MCP_PORT` | `8000` | HTTP 监听端口，仅 sse/streamable-http 有效；CLI 传非法/越界值直接报错退出（环境变量异常值静默回落默认） |
+| `--require-headers` | `CNB_AGENTIC_MEMORY_REQUIRE_HEADERS` | 关闭 | 强制要求凭据头：HTTP 模式下凭据头（`X-CNB-Token`/`X-CNB-Repo`）不齐的请求直接拒绝，不回落服务端环境变量凭据——多用户共享部署防匿名调用间接使用服务端凭据；stdio 不受影响（无请求头是常态）；env 值 `1`/`true`/`yes`/`on` 开启 |
+
+> 安全提示：HTTP transport 无内置鉴权，务必配合反向代理/网关做访问控制与
+> Token 校验后再对外暴露，避免 `CNB_AGENTIC_MEMORY_TOKEN` 凭据被任意调用方
+> 间接使用。多用户共享部署（每请求凭据头隔离）建议加 `--require-headers`
+> 强制凭据头，杜绝匿名请求回落服务端环境变量凭据。
+>
+> **对外部署（反代）**：程序端 DNS rebinding 防护白名单固定为本机地址
+> （localhost 族 + `--host` 监听地址），不提供扩展入口（原 `--allowed-host`
+> 已移除）。反代部署须同时处理 Host 与 Origin 两侧——只改写 Host 不够：
+> 程序端 Origin 白名单同样只有本机 `http://` 条目，浏览器经反代发出的
+> `Origin: https://对外域名` 会被 403。二选一：
+>
+> **方案 A（推荐，改写 Host + 剥离 Origin）**：适用于 MCP 客户端不带
+> Origin 头的典型部署；若确有浏览器直连需求，须在代理层把 Origin 一并
+> 校验后剥离或改写为本机形式：
+>
+> ```nginx
+> proxy_set_header Host localhost;
+> proxy_set_header Origin "";
+> ```
+>
+> **方案 B（代理层白名单）**：代理层完成访问控制与 Host/Origin 白名单
+> 校验——这些本属代理层职责。注意程序端防护常开，校验后**仍须把
+> Host/Origin 改写为本机白名单形式再转发**（如 `Host localhost` +
+> `Origin ""`），原样透传对外域名会被 421/403。
+
+## 客户端接入
+
+**stdio（本地子进程）——推荐：uvx 方式运行**（无需预装，uv 自动拉取包并执行）。`--from` 用于声明 `[mcp]` extra（MCP 依赖在 extra 中，无法随默认安装带上）：
+
+```json
+{
+  "mcpServers": {
+    "cnb-agentic-memory": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "cnb-agentic-memory[mcp]",
+        "cnb-agentic-memory-mcp"
+      ],
+      "env": {
+        "CNB_AGENTIC_MEMORY_TOKEN": "<token>",
+        "CNB_AGENTIC_MEMORY_REPO": "group/memory"
+      }
+    }
+  }
+}
+```
+
+已安装包的环境也可直接用入口命令：
+
+```json
+{
+  "mcpServers": {
+    "cnb-agentic-memory": {
+      "command": "cnb-agentic-memory-mcp",
+      "env": {
+        "CNB_AGENTIC_MEMORY_TOKEN": "<token>",
+        "CNB_AGENTIC_MEMORY_REPO": "group/memory"
+      }
+    }
+  }
+}
+```
+
+**streamable-http（远程/多用户共享接入，推荐）**：服务端先以 HTTP transport 启动，客户端按 URL 接入；凭据与仓库可经请求头逐请求携带（见上文「请求头覆盖」），无需在服务端配置：
+
+```bash
+# 注意：0.0.0.0 为通配监听，必须置于反向代理/网关之后（访问控制 + HTTPS）再对外暴露
+# 启动时若监听通配地址，服务会向 stderr 打印提醒
+cnb-agentic-memory-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+客户端配置示例（`headers` 字段为 Cursor/VS Code/Claude Code 等主流 MCP 客户端通用写法，随每次工具调用发送）：
+
+```json
+{
+  "mcpServers": {
+    "cnb-agentic-memory": {
+      "url": "http://127.0.0.1:8000/mcp",
+      "headers": {
+        "X-CNB-Token": "<调用方自己的token>",
+        "X-CNB-Repo": "group/memory"
+      }
+    }
+  }
+}
+```
+
+同一服务实例上不同用户各配各的 `headers`（token 与 repo 都可以不同），互不影响；不配置 `headers` 的客户端则使用服务端环境变量。
+
+用 Python MCP 客户端接入时，通过自定义 `httpx2.AsyncClient` 携带请求头（示例已实测）：
+
+```python
+import httpx2
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+headers = {"X-CNB-Token": "<token>", "X-CNB-Repo": "group/memory"}
+async with httpx2.AsyncClient(headers=headers) as http_client:
+    async with streamable_http_client("http://127.0.0.1:8000/mcp", http_client=http_client) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            result = await session.call_tool("memory_get", {"number": 1})
+```
+
+原始 HTTP 调用（curl 等）同理：`X-CNB-*` 就是普通 HTTP 请求头，按 MCP 协议流程
+（initialize 获取 `Mcp-Session-Id` 后携带调用）发送即可。
+
+**sse（旧版远程客户端）**：服务端以 `--transport sse` 启动，客户端 URL 为 `http://<host>:<port>/sse`，headers 配置方式与 streamable-http 相同。
+
+## 工具清单（10 个）
+
+| 工具 | 对应 SDK 方法 | 说明 |
+| --- | --- | --- |
+| `memory_write` | `Memory.write` | 写入记忆。**title 由智能体撰写：提炼 3~8 个高区分度关键词短语**（keyword 检索只匹配标题）；超长自动拆分，返回 `parts` 含全部分片 |
+| `memory_get` | `Memory.get` | 按编号读取记忆原文 |
+| `memory_update` | `Memory.update` | 更新记忆。`content` 为**全量替换**；追加内容用 `memory_append` |
+| `memory_append` | `Memory.append` | 追加更新记录（进知识库可被语义检索） |
+| `memory_delete` | `Memory.delete` | 软删除记忆（可 `memory_restore` 恢复） |
+| `memory_restore` | `Memory.restore` | 恢复软删除的记忆 |
+| `memory_list` | `Memory.list` | 按分类/标签过滤列表（`state` 仅支持 `open/closed`） |
+| `memory_list_recent` | `Memory.list_recent` | 最近更新的记忆 |
+| `memory_search` | `Memory.search` | 语义检索（知识库召回 + 回读补齐元信息，默认过滤已删除） |
+| `memory_keyword_search` | `Memory.keyword_search` | 关键词标题检索（仅匹配标题；title 含确切关键词时更精准） |
+
+## 使用指导（写给调用智能体）
+
+- **写入时务必写好 title**：keyword 标题检索只匹配 title，它是无需知识库的独立检索通道（`memory_keyword_search`）。好的 title 是「高区分度关键词的短语」，不是句子
+- **检索按需选路**：按内容模糊查找用 `memory_search`（PoC 实测样例中相关度可达 0.98+）；
+  title 含确切关键词（技术名词/编号/命令）用 `memory_keyword_search` 更精准
+- **`memory_update` 的 content 是全量替换**：只想追加信息时用 `memory_append`
+- **`memory_delete` 是软删除**：可随时 `memory_restore` 恢复；仅从默认检索与
+  列表中隐藏，内容仍留在知识库向量中（`include_closed` 可召回），不是内容
+  清除。修正/补充记忆请用 `memory_update`，删除仅用于真正废弃
+- **错误处理**：工具返回的错误文本携带 CNB 原始信息（状态码/原因），请据此自行决策重试、换参数或放弃；仓库未配置知识库流水线时 `memory_search` 会失败，错误文本提示可改用 `memory_keyword_search`（标题检索，无需知识库）
+
+## 记忆仓库前置条件
+
+`memory_search` 依赖仓库配置 Issue 事件同步流水线（`.cnb.yml` 的 `$` 键，见 [SDK 参考](API.md#记忆仓库前置条件)），且**先配置流水线再写入**——错过事件的记忆不会被补录。写入到可检索的时延取决于流水线配置：事件触发（实时）通常秒级到分钟级，定时入库（如每小时/每日）需等下次运行，还受网络、记忆数量影响；需立即确认时用 `memory_get` 按 number 回查。

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cnb-agentic-memory"
-version = "2.0.2"
-description = "CNB Agentic Memory 是基于 CNB 平台构建的通用记忆工具，把 CNB 的 issue、知识库、检索能力组合成一个开箱即用的智能体记忆层。"
+version = "2.0.4"
+description = "CNB Issue 智能体记忆系统（cnb-agentic-memory）是基于 CNB 平台构建的通用记忆工具，把 CNB 的 issue、知识库、检索能力组合成一个开箱即用的智能体记忆层。"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [{ name = "cnb-agentic-memory Contributors" }]
 keywords = [
@@ -24,6 +24,7 @@ classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -87,18 +88,23 @@ addopts = "--cov=cnb_agentic_memory --cov-report=term-missing --cov-fail-under=9
 
 [tool.ruff]
 line-length = 110
-target-version = "py311"
+target-version = "py310"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "W", "UP", "B"]
+# PLC0415（import-outside-top-level）为 AGENTS.md「禁止函数内 import」的机器护栏
+select = ["E", "F", "I", "W", "UP", "B", "PLC0415"]
 ignore = ["E501"]
 
 [tool.ruff.lint.per-file-ignores]
 # typer 官方模式即 Option() 作为参数默认值，B008 在 CLI 模块中不适用
 "src/cnb_agentic_memory/cli.py" = ["B008"]
+# 函数内 import 的全项目唯一保留点：mcp 依赖延迟加载，未装 [mcp] extra 时给安装指引
+"src/cnb_agentic_memory/mcp_main.py" = ["PLC0415"]
+# 测试内函数内 import 属测试组织惯例（用例自包含），不在禁令范围
+"tests/**" = ["PLC0415"]
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.10"
 packages = ["cnb_agentic_memory"]
 mypy_path = "src"
 ignore_missing_imports = true

cnb_agentic_memory-2.0.4/skills/SKILL.md

@@ -0,0 +1,9 @@
+# Skills 索引
+
+根据用户的需求，匹配并调用最合适的子技能。
+
+## 技能列表
+
+### 智能体记忆
+
+- **cnb-agentic-memory** — CNB Issue 智能体记忆系统（基于 CNB 平台，跨会话长期记忆）。把重要信息写入记忆仓库（一条记忆 = 一个 Issue），之后用语义检索（知识库向量，高相关度）、关键词标题检索（`cnb-agentic-memory keyword`，无需知识库）或分类/标签浏览找回。**写入时必须自己撰写 title**——提炼 3~8 个高区分度关键词短语，keyword 标题检索只匹配 title，title 质量决定记忆能否被找回。支持追加更新记录、全量替换正文、软删除与恢复。适合回答"记住这个"、"帮我记一下"、"之前说过什么"、"上次是怎么解决的"、"查一下我们的记忆库"这类跨会话请求。当用户提到记忆、记住、想起、之前、上次、经验、教训、备忘时使用，详见 [cnb-agentic-memory](./cnb-agentic-memory/SKILL.md)。

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/skills/cnb-agentic-memory/SKILL.md

@@ -3,14 +3,14 @@ name: cnb-agentic-memory
 description: 基于 CNB 平台的智能体记忆工具：跨会话写入/检索/管理记忆。写入时必须自己撰写 title（提炼 3~8 个高区分度关键词短语，keyword 检索只匹配 title）。当用户提到记忆、记住、之前、上次、经验、教训时使用。用法：cnb-agentic-memory CLI（write/get/append/update/delete/restore/list/recent/search/keyword）。
 slug: cnb-agentic-memory
 displayName: CNB Issue 智能体记忆系统
-version: 2.0.2
-summary: 基于 CNB 平台的智能体记忆工具：以 Issue 为存储、知识库为语义检索，CLI/MCP/SDK 三入口跨会话记忆。
+version: 2.0.4
+summary: CNB Issue 智能体记忆系统：以 Issue 为存储、知识库为语义检索，CLI/MCP/SDK 三入口跨会话记忆。
 license: MIT
 homepage: https://cnb.cool/xqitw/cnb-agentic-memory
 tags: [记忆, 智能体, MCP, 知识库, CLI]
 ---
 
-# cnb-agentic-memory — 智能体记忆系统
+# CNB Issue 智能体记忆系统（cnb-agentic-memory）
 
 基于 CNB 平台的跨会话记忆：一条记忆 = 一个 Issue，`number` 是记忆唯一标识。写入即持久化，读取走语义检索（知识库向量，高相关度）。记忆仓库中全部 Issue 均为记忆，检索与列表结果不区分记忆与普通 Issue。
 
@@ -35,8 +35,10 @@ tags: [记忆, 智能体, MCP, 知识库, CLI]
    append 续写 > delete 废弃（最后手段）。delete 是软删除——仅从默认检索
    隐藏，内容仍留在知识库向量中（`--include-closed` 可召回），不是内容
    清除；误删重建还会让向量库多一份重复内容。
-5. **写入后约 1~2 分钟才能被语义检索到**（知识库同步时延），这是平台预期，
-   不是故障。写入成功返回的 number 就是永久凭据，可先记录。
+5. **写入后不能立即语义检索不代表失败**：能否/何时可检索取决于仓库流水线
+   配置（实时同步通常秒级到分钟级；定时入库如每小时/每日需等下次运行），
+   还受网络、记忆数量影响。写入成功返回的 number 就是永久凭据，可先记录；
+   需立即确认用 `get` 按 number 回查。
 
 ## 安装与调用
 

{cnb_agentic_memory-2.0.2 → cnb_agentic_memory-2.0.4}/src/cnb_agentic_memory/__init__.py

@@ -1,14 +1,20 @@
-"""cnb-agentic-memory：基于 CNB 平台的通用智能体记忆工具。
+"""cnb-agentic-memory（CNB Issue 智能体记忆系统）：基于 CNB 平台的通用智能体记忆工具。
 
 以 CNB Issue 为存储、知识库为语义检索，SDK / CLI / MCP / Skill 多形态对外服务。
 一记忆 = 一 Issue，number 是记忆唯一标识。
 """
 
+from importlib.metadata import PackageNotFoundError, version
+
 from .api import ApiError, CNBApiClient, ConfigError
 from .memory import Memory, MemoryRuleError, SearchResult, WriteResult, normalize_title
 from .models import Comment, Issue, KbChunk, Label
 
-__version__ = "2.0.2"
+try:
+    # pyproject [project].version 为单一来源（手工硬编码会在发版时漂移，实测翻车）
+    __version__ = version("cnb-agentic-memory")
+except PackageNotFoundError:  # 源码直用未安装时兜底，保持可导入
+    __version__ = "0+unknown"
 
 __all__ = [
     "__version__",