cnb-agentic-memory 0.1.0__tar.gz

cnb_agentic_memory-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+node_modules/

cnb_agentic_memory-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# 贡献指南
+
+感谢你对 cnb-agentic-memory (cam) 的关注！欢迎提交 Issue 和 Pull Request。
+
+## 开发环境
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) 包管理（推荐）
+- 仓库：`cnb.cool/cnpc/cam`
+
+## 开发流程
+
+### 1. 安装依赖
+
+```bash
+uv sync --extra dev
+```
+
+### 2. 提交代码前
+
+运行全部质量检查：
+
+```bash
+# 代码风格
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+
+# 类型检查
+uv run mypy src tests
+
+# 单元测试
+uv run pytest tests/ -v
+
+# Markdown 文档校验（需 node 环境）
+npx markdownlint-cli2 '**/*.md'
+```
+
+目标：新增代码的测试覆盖率不低于 90%，所有检查必须通过。
+
+### 3. 提交规范
+
+- 提交信息使用中文，遵循 [Conventional Commits](https://www.conventionalcommits.org/) 风格：
+  - `feat:` 新功能
+  - `fix:` 缺陷修复
+  - `refactor:` 重构
+  - `docs:` 文档
+  - `ci:` 流水线 / CI 配置
+  - `test:` 测试
+  - `chore:` 杂项
+- 示例：`feat: 支持 memory_append 追加更新记录`
+
+## 代码规范
+
+### 约定
+
+- 代码注释与文档使用中文
+- 遵循现有文件命名与函数风格，不做风格重构
+- 新增参数必须有默认值或兼容旧行为
+- 可复用的逻辑必须抽离为独立函数，禁止在多处重复实现
+
+### 架构约束
+
+- **零 git 依赖**：存储操作全部走 CNB Open API，禁止引入 git 协议封装
+- **写路径显式校验**：写操作完成后 GET 回读确认，防范 CNB API 静默失败
+- 完整架构约束见 [AGENTS.md](./AGENTS.md)，设计方案见 [Issue #1](https://cnb.cool/cnpc/cam/-/issues/1)
+
+### 目录约定
+
+- `src/cam/` — 核心（API 客户端 / 工具语义层 / MCP Server / CLI）
+
+## 分支与发布
+
+- 开发在短生命周期分支进行，main 分支通过 PR 合并（保护分支）
+- 打 tag（`v*`）触发 CI：测试 → 发布 PyPI → code-wiki → git release
+
+## 测试注意事项
+
+- 单元测试使用 `respx` mock CNB API 请求，不依赖真实网络
+- 集成测试（真实 CNB API）不进入 CI，本地手动验证
+- 集成测试需要 `MEMORY_REPO` / `CNB_TOKEN` 环境变量

cnb_agentic_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cnb-agentic-memory Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cnb_agentic_memory-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: cnb-agentic-memory
+Version: 0.1.0
+Summary: cnb-agentic-memory (cam) — 通用智能体记忆工具：以 CNB Issue 为存储、知识库为检索的 MCP Server
+Project-URL: Homepage, https://cnb.cool/cnpc/cam
+Project-URL: Repository, https://cnb.cool/cnpc/cam
+Project-URL: Issues, https://cnb.cool/cnpc/cam/-/issues
+Author: cnb-agentic-memory Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agent,cnb,knowledge-base,llm,mcp,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mcp<2,>=1.2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# cnb-agentic-memory (cam)
+
+[![Latest Release](https://cnb.cool/cnpc/cam/-/badge/release)](https://cnb.cool/cnpc/cam/-/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)
+
+基于 CNB 平台构建的通用智能体记忆工具 —— 以 CNB Issue 为存储、CNB 知识库为语义检索，以 MCP Server 形式让任何智能体"记住"跨会话、跨任务的信息。
+
+> **核心思路**：完全依托 CNB 现成能力，不写一行存储/检索代码。存储、向量化、检索全部由 CNB 平台承担，cam 只是一个轻量适配层。设计文档见 [Issue #1](https://cnb.cool/cnpc/cam/-/issues/1)。
+
+## 工作原理
+
+```text
+智能体 ←MCP→ cam MCP Server ←纯 API→ CNB Issue 存储 + 知识库检索
+                     ↑
+        issue.open/update/comment/close 事件自动触发 knowledge:update 向量化
+```
+
+- **一条记忆 = 一个 Issue**：`number` 即记忆 id，天然唯一，并发写零冲突
+- **写入即入库**：Issue 变更事件自动触发知识库同步（约 1~2 分钟可检索）
+- **语义检索**：知识库向量召回，从 `metadata.path` 直接定位记忆原文
+- **软删除**：`state=closed` 归档可恢复，`activities` 免费审计日志
+
+## 安装
+
+```bash
+uvx cam-mcp                       # 免安装直接运行 MCP Server
+pip install "cnb-agentic-memory[mcp]"  # 含 MCP 支持
+uv tool install cnb-agentic-memory[mcp]
+```
+
+## MCP 接入
+
+```json
+{
+  "mcpServers": {
+    "cam": {
+      "command": "cam-mcp",
+      "env": {
+        "MEMORY_REPO": "group/memory-repo",
+        "CNB_TOKEN": "<你的 CNB 访问令牌>"
+      }
+    }
+  }
+}
+```
+
+环境变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `MEMORY_REPO` | 记忆仓库 slug，如 `group/memory-repo` |
+| `CNB_TOKEN` | 访问令牌，需 `repo-issue:rw`（Issue 读写）+ `repo-code:r`（知识库检索） |
+
+## 工具清单
+
+| 工具 | 说明 |
+| --- | --- |
+| `memory_write` | 新增记忆（自动生成关键词标题，两步写入标签） |
+| `memory_update` | 修改记忆内容/标签 |
+| `memory_append` | 追加更新记录（评论，可被语义检索） |
+| `memory_delete` | 软删除（归档，可恢复） |
+| `memory_get` | 按编号精确读取 |
+| `memory_list` | 按分类/标签列出 |
+| `memory_list_recent` | 最近 N 条记忆 |
+| `memory_search` | 语义检索（知识库向量召回为主通道） |
+
+## 记忆仓库初始化
+
+记忆仓库需配置 `.cnb.yml` 启用 Issue → 知识库同步（模板见 [Issue #1 §8](https://cnb.cool/cnpc/cam/-/issues/1)）。后续版本将提供 `cam init --repo <slug>` 一键初始化。
+
+## 文档
+
+- [设计方案与实测依据](https://cnb.cool/cnpc/cam/-/issues/1) — 完整设计 + 全量 PoC 实测结论
+- [贡献指南](CONTRIBUTING.md)
+- [安全策略](SECURITY.md)
+
+## 贡献指南
+
+欢迎参与贡献！请参考 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## 许可证
+
+[MIT](./LICENSE)

cnb_agentic_memory-0.1.0/README.md

@@ -0,0 +1,85 @@
+# cnb-agentic-memory (cam)
+
+[![Latest Release](https://cnb.cool/cnpc/cam/-/badge/release)](https://cnb.cool/cnpc/cam/-/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)
+
+基于 CNB 平台构建的通用智能体记忆工具 —— 以 CNB Issue 为存储、CNB 知识库为语义检索，以 MCP Server 形式让任何智能体"记住"跨会话、跨任务的信息。
+
+> **核心思路**：完全依托 CNB 现成能力，不写一行存储/检索代码。存储、向量化、检索全部由 CNB 平台承担，cam 只是一个轻量适配层。设计文档见 [Issue #1](https://cnb.cool/cnpc/cam/-/issues/1)。
+
+## 工作原理
+
+```text
+智能体 ←MCP→ cam MCP Server ←纯 API→ CNB Issue 存储 + 知识库检索
+                     ↑
+        issue.open/update/comment/close 事件自动触发 knowledge:update 向量化
+```
+
+- **一条记忆 = 一个 Issue**：`number` 即记忆 id，天然唯一，并发写零冲突
+- **写入即入库**：Issue 变更事件自动触发知识库同步（约 1~2 分钟可检索）
+- **语义检索**：知识库向量召回，从 `metadata.path` 直接定位记忆原文
+- **软删除**：`state=closed` 归档可恢复，`activities` 免费审计日志
+
+## 安装
+
+```bash
+uvx cam-mcp                       # 免安装直接运行 MCP Server
+pip install "cnb-agentic-memory[mcp]"  # 含 MCP 支持
+uv tool install cnb-agentic-memory[mcp]
+```
+
+## MCP 接入
+
+```json
+{
+  "mcpServers": {
+    "cam": {
+      "command": "cam-mcp",
+      "env": {
+        "MEMORY_REPO": "group/memory-repo",
+        "CNB_TOKEN": "<你的 CNB 访问令牌>"
+      }
+    }
+  }
+}
+```
+
+环境变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `MEMORY_REPO` | 记忆仓库 slug，如 `group/memory-repo` |
+| `CNB_TOKEN` | 访问令牌，需 `repo-issue:rw`（Issue 读写）+ `repo-code:r`（知识库检索） |
+
+## 工具清单
+
+| 工具 | 说明 |
+| --- | --- |
+| `memory_write` | 新增记忆（自动生成关键词标题，两步写入标签） |
+| `memory_update` | 修改记忆内容/标签 |
+| `memory_append` | 追加更新记录（评论，可被语义检索） |
+| `memory_delete` | 软删除（归档，可恢复） |
+| `memory_get` | 按编号精确读取 |
+| `memory_list` | 按分类/标签列出 |
+| `memory_list_recent` | 最近 N 条记忆 |
+| `memory_search` | 语义检索（知识库向量召回为主通道） |
+
+## 记忆仓库初始化
+
+记忆仓库需配置 `.cnb.yml` 启用 Issue → 知识库同步（模板见 [Issue #1 §8](https://cnb.cool/cnpc/cam/-/issues/1)）。后续版本将提供 `cam init --repo <slug>` 一键初始化。
+
+## 文档
+
+- [设计方案与实测依据](https://cnb.cool/cnpc/cam/-/issues/1) — 完整设计 + 全量 PoC 实测结论
+- [贡献指南](CONTRIBUTING.md)
+- [安全策略](SECURITY.md)
+
+## 贡献指南
+
+欢迎参与贡献！请参考 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## 许可证
+
+[MIT](./LICENSE)

cnb_agentic_memory-0.1.0/SECURITY.md

@@ -0,0 +1,47 @@
+# 安全策略
+
+cnb-agentic-memory (cam) 是基于 CNB 平台的智能体记忆工具，涉及 CNB API 凭据管理与智能体记忆读写。我们高度重视安全问题。
+
+## 支持版本
+
+仅最新稳定版本接收安全补丁，不对旧版本进行回溯修复。
+
+| 版本 | 支持状态 |
+| --- | --- |
+| 最新稳定版 | ✅ |
+| < 最新 | ❌ |
+
+请查看 [Releases](https://cnb.cool/cnpc/cam/-/releases) 获取当前版本信息。
+
+## 报告漏洞
+
+**请勿通过公开 Issue 报告安全漏洞。**
+
+请通过以下方式私下报告：
+
+- **CNB 私信**：在仓库页面发起私密讨论，标题注明 `[SECURITY]`
+- **邮件**：发送至项目维护者，主题行包含 `[SECURITY]`
+
+报告中请包含：
+
+- 漏洞描述及被利用后的影响
+- 复现步骤或概念验证代码
+- 受影响的版本和配置信息
+- 建议的缓解方案（可选）
+
+## 响应时间线
+
+| 阶段 | 目标时间 |
+| --- | --- |
+| 确认接收 | 收到报告后 48 小时内 |
+| 评估分类 | 5 个工作日内 — 评估严重程度、影响范围和修复方案 |
+| 补丁发布（严重） | 评估完成后 14 天内 |
+| 补丁发布（中等/低危） | 下一个功能版本发布或与维护者协商的时间线 |
+| 公开披露 | 补丁发布且用户有充分时间更新后 |
+
+## 安全设计原则
+
+- **凭据安全**：CNB 访问令牌通过环境变量（`CNB_TOKEN`）传入，绝不写入代码、日志或文档；工具对用户请求中的令牌类内容应拒绝存储（见 MCP 客户端交互规范）
+- **最小权限**：令牌仅需 `repo-issue:rw`（Issue 读写）+ `repo-code:r`（知识库检索），文档明确告知用户所需最小权限集
+- **软删除优先**：记忆删除为 Issue 归档（state=closed），保留完整审计链（activities），无物理删除
+- **输入校验**：记忆编号、标签命名严格校验，非法输入返回清晰错误

cnb_agentic_memory-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cnb-agentic-memory"
+version = "0.1.0"
+description = "cnb-agentic-memory (cam) — 通用智能体记忆工具：以 CNB Issue 为存储、知识库为检索的 MCP Server"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "cnb-agentic-memory Contributors" },
+]
+keywords = ["mcp", "memory", "agent", "cnb", "knowledge-base", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+# MCP server（upper bound 强制：mcp v2 移除 fastmcp 兼容路径）
+mcp = [
+  "mcp>=1.2.0,<2",
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.4",
+  "mypy>=1.10",
+  "mcp>=1.2.0,<2",
+]
+
+[project.scripts]
+cam-mcp = "cam.mcp_server:main"
+cam = "cam.cli:main"
+
+[project.urls]
+Homepage = "https://cnb.cool/cnpc/cam"
+Repository = "https://cnb.cool/cnpc/cam"
+Issues = "https://cnb.cool/cnpc/cam/-/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cam"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "docs", "README.md", "LICENSE", "CONTRIBUTING.md", "SECURITY.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 110
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+packages = ["src/cam"]
+ignore_missing_imports = true

cnb_agentic_memory-0.1.0/src/cam/__init__.py

@@ -0,0 +1,9 @@
+"""cnb-agentic-memory (cam) — 基于 CNB 平台的通用智能体记忆工具。
+
+以 CNB Issue 为存储、CNB 知识库为语义检索，以 MCP Server 形式
+让任何智能体"记住"跨会话、跨任务的信息。
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

cnb_agentic_memory-0.1.0/src/cam/cli.py

@@ -0,0 +1,6 @@
+"""cam CLI 入口（骨架）。"""
+
+
+def main() -> None:
+    """CLI 入口（子命令实现中）。"""
+    raise SystemExit("cam CLI 尚在开发中，设计方案见 https://cnb.cool/cnpc/cam/-/issues/1")

cnb_agentic_memory-0.1.0/src/cam/mcp_server.py

@@ -0,0 +1,6 @@
+"""cam-mcp 入口：MCP Server 启动（骨架，工具注册见设计文档 cnpc/cam#1 §3）。"""
+
+
+def main() -> None:
+    """启动 MCP Server（工具面实现中）。"""
+    raise SystemExit("cam MCP Server 尚在开发中，工具面设计见 https://cnb.cool/cnpc/cam/-/issues/1")

cnb_agentic_memory-0.1.0/tests/test_version.py

@@ -0,0 +1,7 @@
+"""包基础自检。"""
+
+from cam import __version__
+
+
+def test_version() -> None:
+    assert __version__ == "0.1.0"