compound-memory 0.1.0__tar.gz

compound_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chinwe
+
+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.

compound_memory-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: compound-memory
+Version: 0.1.0
+Summary: Local multi-agent shared memory with compounding (MCP server + CLI)
+Author: chinwe
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/chinwe/compound-memory
+Project-URL: Issues, https://github.com/chinwe/compound-memory/issues
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML>=6; extra == "dev"
+Requires-Dist: sqlite-vec>=0.1.9; extra == "dev"
+Provides-Extra: vec
+Requires-Dist: onnxruntime==1.19.2; extra == "vec"
+Requires-Dist: tokenizers>=0.20; extra == "vec"
+Requires-Dist: numpy>=1.26; extra == "vec"
+Requires-Dist: sqlite-vec>=0.1.9; extra == "vec"
+Dynamic: license-file
+
+# compound-memory
+
+本地多 Agent 共享记忆系统——支持复利（越用越值钱）。Spec 见 `docs/specs/0001-compound-memory-spec.md`。
+
+## 架构
+
+```
+Agent (MCP 客户端 / CLI)
+  └─ memory_write | memory_search | memory_get | memory_link | memory_feedback
+       └─ MemoryStore (~/.agents/memory)
+            ├─ namespaces/_shared/{episode,fact,insight,skill}/*.md   共享区
+            ├─ namespaces/agent-*/...                                  私有区
+            ├─ archive/...                                             衰减归档（可复活）
+            ├─ index/tokens.json                                       可重建的检索缓存
+            ├─ review-queue.md                                         fact/insight 冲突队列
+            └─ .git/                                                   每次写入自动 commit
+```
+
+## 复利机制
+
+| 利息来源 | 实现 |
+|---|---|
+| ① 使用强化 | `memory_feedback`: uses+1, conf+0.1 |
+| ② 关联增值 | `memory_link` 双向关联；`memory_get` 带出一度邻居；`search` 命中自动内嵌精简邻居（上限 3、只召回活动记忆，`--no-neighbors` 可关） |
+| ③ 蒸馏提纯 | `distill-plan`（CLI，确定性候选+双信号去重标注）→ Agent 判断 → `distill-apply` 原子落库（产物 links 溯源，源归档可复活） |
+| ④ 跨 Agent 验证 | 与 source 不同的 agent 反馈时 conf 额外 +0.15 |
+
+评分公式（权重以 `src/compound_memory/scoring.py` 的 `W_*` 常量为准）：`0.70·相似度 + 0.15·置信度 + 0.10·新近度(0.5+0.5·e^(−Δt/τ)) + 0.05·类型权重`；双路（向量路启用）时改为 RRF 融合主序 + ε=0.04 先验 tie-break（见 spec「索引即缓存」）。
+
+## MCP 接入
+
+各宿主（WorkBuddy / ZCode / Claude Code / DeepSeek Harness）的完整接入配置与统一使用规范见 `docs/agent-integration.md`。5 个 tool 的 description 自带闭环铁律（命中采纳后必须回写 `memory_feedback`、只写稳定事实、复用既有 key），宿主不注入使用规范也能保持复利闭环——注入规范（agent-integration §6）仍推荐，用于收紧写入质量。
+
+```json
+{
+  "mcpServers": {
+    "compound-memory": {
+      "type": "stdio",
+      "command": "~/.local/bin/uv",
+      "args": ["run", "--directory", "<本目录>", "compound-memory-server"],
+      "env": { "COMPOUND_MEMORY_ROOT": "~/.agents/memory" }
+    }
+  }
+}
+```
+
+各宿主配置若不展开 `~` 占位写法，替换为本机绝对路径即可。向量召回路为可选（`uv sync --extra vec`）：未装 extra 或 HF 缓存缺模型时自动降级纯词面。embedding 模型与维度可经 `COMPOUND_MEMORY_EMBEDDING_MODEL`（默认 `Xenova/bge-small-zh-v1.5`）与 `COMPOUND_MEMORY_EMBEDDING_DIM`（默认 512）覆盖——换模型属运维动作，改后需显式 `rebuild-index`。
+
+## CLI
+
+```bash
+uv sync --extra dev              # 首次克隆后初始化 .venv（之后 uv run 自动使用）
+
+uv run compound-memory init               # 初始化空库
+uv run compound-memory write "Vercel Serverless 10s 超时" episode agent-workbuddy
+uv run compound-memory search "Vercel 超时"     # 命中内嵌一度邻居（上限3，--no-neighbors 关闭）
+uv run compound-memory feedback <id> agent-claude
+uv run compound-memory decay          # cron 定时跑
+uv run compound-memory revive <id>    # 复活归档记忆（CLI 唯一入口）
+uv run compound-memory distill-plan   # 蒸馏候选清单：merge_with（同 key 强信号）+ possible_dup_of（BM25 弱信号）+ promotion_candidate（高活性 episode）
+uv run compound-memory distill-apply "合并后的经验" insight agent-workbuddy --sources <id1>,<id2>  # 原子落库：产物(links 溯源, origin=distillation) + 源归档，一次 commit
+uv run compound-memory stats            # 健康度：uses/confidence 固定桶 + 活性 + 蒸馏产出量
+uv run compound-memory rebuild-index  # 索引可随时重建
+uv run compound-memory review-queue   # 冲突队列（CLI 唯一入口）
+uv run compound-memory git-log        # 审计轨迹
+```
+
+## 定时蒸馏准备（launchd / cron / systemd）
+
+ADR 0001：确定性准备定时跑，判断（摘要/合并）由 Agent 会话内按需完成。每天 09:00 把候选清单写到 `<root>/distill/last-plan.json`。调度器三选一：**launchd**（macOS 系统标准，睡眠错过的计划唤醒后补跑）、**systemd user timer**（`Persistent=true` 同样补跑）、**cron**（最通用但不补跑错过的计划）。三者都调用同一个平台无关的 `scripts/distill-prepare.sh`。
+
+**launchd（macOS）**：
+
+```bash
+REPO=$(pwd); UV="$HOME/.local/bin/uv"   # 项目环境由 uv 管理，脚本内经 UV_BIN 覆盖 launchd PATH
+sed -e "s|__REPO__|$REPO|g" -e "s|__UV__|$UV|g" -e "s|__ROOT__|$HOME/.agents/memory|g" \
+  scripts/com.compound-memory.distill-prepare.plist.tmpl \
+  > ~/Library/LaunchAgents/com.compound-memory.distill-prepare.plist
+launchctl load ~/Library/LaunchAgents/com.compound-memory.distill-prepare.plist
+launchctl list | grep compound-memory   # 验证已加载；日志在 <root>/distill/prepare.log
+```
+
+**systemd user（Linux）**：
+
+```bash
+REPO=$(pwd); UV="$HOME/.local/bin/uv"
+mkdir -p ~/.config/systemd/user
+for f in service timer; do
+  sed -e "s|__REPO__|$REPO|g" -e "s|__UV__|$UV|g" -e "s|__ROOT__|$HOME/.agents/memory|g" \
+    scripts/compound-memory-distill-prepare.$f.example \
+    > ~/.config/systemd/user/compound-memory-distill-prepare.$f
+done
+systemctl --user daemon-reload
+systemctl --user enable --now compound-memory-distill-prepare.timer
+systemctl --user list-timers | grep compound-memory   # 验证已加载
+```
+
+**cron（其他环境）**：`crontab -e` 加入（sed 填充占位符后）：
+
+```
+0 9 * * * UV_BIN=$HOME/.local/bin/uv COMPOUND_MEMORY_ROOT=$HOME/.agents/memory /bin/sh <仓库>/scripts/distill-prepare.sh >> $HOME/.agents/memory/distill/prepare.log 2>&1
+```
+
+失败要响亮：脚本 `set -eu`，任何一步失败以非 0 退出（`launchctl list` / `systemctl --user list-units` / cron 邮件可见，日志落 distill/prepare.log）。`distill/` 是运行时产物目录（自动加入库 .gitignore），不产生 commit 噪声——只有 Agent 判断后跑 `distill-apply` 才落一次原子 commit。
+
+## 开发
+
+```bash
+uv run pytest tests/ -q     # 85 tests（MCP tool 边界 + 蒸馏 + 生命周期/索引/CLI）
+uv run mypy src/compound_memory/
+```
+
+测试缝：MCP tool 边界（`mcp.Client(server)` 内存直连，无子进程）+ 核心模块单测（scoring / index / store 运维面）。CI 在 Python 3.11/3.12/3.13 矩阵上跑测试、类型检查与纯 wheel 安装冒烟。
+
+## 发布
+
+PyPI 版本不可重传，tag 必须与 `pyproject.toml` 的 `version` 一致（release workflow 有校验，不一致响亮失败）。发布走 GitHub Actions + PyPI Trusted Publisher（OIDC，免 token）：
+
+1. **一次性配置**（PyPI → 项目 → Publishing）：owner `chinwe`、repo `compound-memory`、workflow `release.yml`、environment `pypi`。首次发布时项目尚不存在，在 pypi.org 用"pending publisher"预注册即可。
+2. **发布**：`git tag v0.1.0 && git push origin v0.1.0` → `release.yml` 自动 build + `uv publish`。
+3. 发布后 `uvx compound-memory-server` 即为通用安装形态（MCP 配置里的 `command` 也可换成 `uvx`，不再依赖仓库克隆路径）。

compound_memory-0.1.0/README.md

@@ -0,0 +1,121 @@
+# compound-memory
+
+本地多 Agent 共享记忆系统——支持复利（越用越值钱）。Spec 见 `docs/specs/0001-compound-memory-spec.md`。
+
+## 架构
+
+```
+Agent (MCP 客户端 / CLI)
+  └─ memory_write | memory_search | memory_get | memory_link | memory_feedback
+       └─ MemoryStore (~/.agents/memory)
+            ├─ namespaces/_shared/{episode,fact,insight,skill}/*.md   共享区
+            ├─ namespaces/agent-*/...                                  私有区
+            ├─ archive/...                                             衰减归档（可复活）
+            ├─ index/tokens.json                                       可重建的检索缓存
+            ├─ review-queue.md                                         fact/insight 冲突队列
+            └─ .git/                                                   每次写入自动 commit
+```
+
+## 复利机制
+
+| 利息来源 | 实现 |
+|---|---|
+| ① 使用强化 | `memory_feedback`: uses+1, conf+0.1 |
+| ② 关联增值 | `memory_link` 双向关联；`memory_get` 带出一度邻居；`search` 命中自动内嵌精简邻居（上限 3、只召回活动记忆，`--no-neighbors` 可关） |
+| ③ 蒸馏提纯 | `distill-plan`（CLI，确定性候选+双信号去重标注）→ Agent 判断 → `distill-apply` 原子落库（产物 links 溯源，源归档可复活） |
+| ④ 跨 Agent 验证 | 与 source 不同的 agent 反馈时 conf 额外 +0.15 |
+
+评分公式（权重以 `src/compound_memory/scoring.py` 的 `W_*` 常量为准）：`0.70·相似度 + 0.15·置信度 + 0.10·新近度(0.5+0.5·e^(−Δt/τ)) + 0.05·类型权重`；双路（向量路启用）时改为 RRF 融合主序 + ε=0.04 先验 tie-break（见 spec「索引即缓存」）。
+
+## MCP 接入
+
+各宿主（WorkBuddy / ZCode / Claude Code / DeepSeek Harness）的完整接入配置与统一使用规范见 `docs/agent-integration.md`。5 个 tool 的 description 自带闭环铁律（命中采纳后必须回写 `memory_feedback`、只写稳定事实、复用既有 key），宿主不注入使用规范也能保持复利闭环——注入规范（agent-integration §6）仍推荐，用于收紧写入质量。
+
+```json
+{
+  "mcpServers": {
+    "compound-memory": {
+      "type": "stdio",
+      "command": "~/.local/bin/uv",
+      "args": ["run", "--directory", "<本目录>", "compound-memory-server"],
+      "env": { "COMPOUND_MEMORY_ROOT": "~/.agents/memory" }
+    }
+  }
+}
+```
+
+各宿主配置若不展开 `~` 占位写法，替换为本机绝对路径即可。向量召回路为可选（`uv sync --extra vec`）：未装 extra 或 HF 缓存缺模型时自动降级纯词面。embedding 模型与维度可经 `COMPOUND_MEMORY_EMBEDDING_MODEL`（默认 `Xenova/bge-small-zh-v1.5`）与 `COMPOUND_MEMORY_EMBEDDING_DIM`（默认 512）覆盖——换模型属运维动作，改后需显式 `rebuild-index`。
+
+## CLI
+
+```bash
+uv sync --extra dev              # 首次克隆后初始化 .venv（之后 uv run 自动使用）
+
+uv run compound-memory init               # 初始化空库
+uv run compound-memory write "Vercel Serverless 10s 超时" episode agent-workbuddy
+uv run compound-memory search "Vercel 超时"     # 命中内嵌一度邻居（上限3，--no-neighbors 关闭）
+uv run compound-memory feedback <id> agent-claude
+uv run compound-memory decay          # cron 定时跑
+uv run compound-memory revive <id>    # 复活归档记忆（CLI 唯一入口）
+uv run compound-memory distill-plan   # 蒸馏候选清单：merge_with（同 key 强信号）+ possible_dup_of（BM25 弱信号）+ promotion_candidate（高活性 episode）
+uv run compound-memory distill-apply "合并后的经验" insight agent-workbuddy --sources <id1>,<id2>  # 原子落库：产物(links 溯源, origin=distillation) + 源归档，一次 commit
+uv run compound-memory stats            # 健康度：uses/confidence 固定桶 + 活性 + 蒸馏产出量
+uv run compound-memory rebuild-index  # 索引可随时重建
+uv run compound-memory review-queue   # 冲突队列（CLI 唯一入口）
+uv run compound-memory git-log        # 审计轨迹
+```
+
+## 定时蒸馏准备（launchd / cron / systemd）
+
+ADR 0001：确定性准备定时跑，判断（摘要/合并）由 Agent 会话内按需完成。每天 09:00 把候选清单写到 `<root>/distill/last-plan.json`。调度器三选一：**launchd**（macOS 系统标准，睡眠错过的计划唤醒后补跑）、**systemd user timer**（`Persistent=true` 同样补跑）、**cron**（最通用但不补跑错过的计划）。三者都调用同一个平台无关的 `scripts/distill-prepare.sh`。
+
+**launchd（macOS）**：
+
+```bash
+REPO=$(pwd); UV="$HOME/.local/bin/uv"   # 项目环境由 uv 管理，脚本内经 UV_BIN 覆盖 launchd PATH
+sed -e "s|__REPO__|$REPO|g" -e "s|__UV__|$UV|g" -e "s|__ROOT__|$HOME/.agents/memory|g" \
+  scripts/com.compound-memory.distill-prepare.plist.tmpl \
+  > ~/Library/LaunchAgents/com.compound-memory.distill-prepare.plist
+launchctl load ~/Library/LaunchAgents/com.compound-memory.distill-prepare.plist
+launchctl list | grep compound-memory   # 验证已加载；日志在 <root>/distill/prepare.log
+```
+
+**systemd user（Linux）**：
+
+```bash
+REPO=$(pwd); UV="$HOME/.local/bin/uv"
+mkdir -p ~/.config/systemd/user
+for f in service timer; do
+  sed -e "s|__REPO__|$REPO|g" -e "s|__UV__|$UV|g" -e "s|__ROOT__|$HOME/.agents/memory|g" \
+    scripts/compound-memory-distill-prepare.$f.example \
+    > ~/.config/systemd/user/compound-memory-distill-prepare.$f
+done
+systemctl --user daemon-reload
+systemctl --user enable --now compound-memory-distill-prepare.timer
+systemctl --user list-timers | grep compound-memory   # 验证已加载
+```
+
+**cron（其他环境）**：`crontab -e` 加入（sed 填充占位符后）：
+
+```
+0 9 * * * UV_BIN=$HOME/.local/bin/uv COMPOUND_MEMORY_ROOT=$HOME/.agents/memory /bin/sh <仓库>/scripts/distill-prepare.sh >> $HOME/.agents/memory/distill/prepare.log 2>&1
+```
+
+失败要响亮：脚本 `set -eu`，任何一步失败以非 0 退出（`launchctl list` / `systemctl --user list-units` / cron 邮件可见，日志落 distill/prepare.log）。`distill/` 是运行时产物目录（自动加入库 .gitignore），不产生 commit 噪声——只有 Agent 判断后跑 `distill-apply` 才落一次原子 commit。
+
+## 开发
+
+```bash
+uv run pytest tests/ -q     # 85 tests（MCP tool 边界 + 蒸馏 + 生命周期/索引/CLI）
+uv run mypy src/compound_memory/
+```
+
+测试缝：MCP tool 边界（`mcp.Client(server)` 内存直连，无子进程）+ 核心模块单测（scoring / index / store 运维面）。CI 在 Python 3.11/3.12/3.13 矩阵上跑测试、类型检查与纯 wheel 安装冒烟。
+
+## 发布
+
+PyPI 版本不可重传，tag 必须与 `pyproject.toml` 的 `version` 一致（release workflow 有校验，不一致响亮失败）。发布走 GitHub Actions + PyPI Trusted Publisher（OIDC，免 token）：
+
+1. **一次性配置**（PyPI → 项目 → Publishing）：owner `chinwe`、repo `compound-memory`、workflow `release.yml`、environment `pypi`。首次发布时项目尚不存在，在 pypi.org 用"pending publisher"预注册即可。
+2. **发布**：`git tag v0.1.0 && git push origin v0.1.0` → `release.yml` 自动 build + `uv publish`。
+3. 发布后 `uvx compound-memory-server` 即为通用安装形态（MCP 配置里的 `command` 也可换成 `uvx`，不再依赖仓库克隆路径）。

compound_memory-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "compound-memory"
+version = "0.1.0"
+description = "Local multi-agent shared memory with compounding (MCP server + CLI)"
+readme = "README.md"
+# PEP 639 SPDX 表达式；与 License:: classifier 互斥，故后者已移除
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "chinwe"}]
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["mcp>=2", "PyYAML>=6"]
+
+[project.urls]
+Homepage = "https://github.com/chinwe/compound-memory"
+Issues = "https://github.com/chinwe/compound-memory/issues"
+
+[project.scripts]
+compound-memory = "compound_memory.cli:main"
+compound-memory-server = "compound_memory.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.10", "types-PyYAML>=6", "sqlite-vec>=0.1.9"]
+# 向量召回路（可选）：未安装时 search 自动降级纯词面（检索降级不报错）。
+# onnxruntime 钉 1.19.2：macOS x64 可装的最新版（1.20+ 的 wheel 标签要求 macOS 13+）
+vec = ["onnxruntime==1.19.2", "tokenizers>=0.20", "numpy>=1.26", "sqlite-vec>=0.1.9"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = false
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = ["onnxruntime.*", "onnxruntime", "tokenizers.*", "tokenizers", "sqlite_vec.*", "sqlite_vec", "numpy.*", "numpy"]
+ignore_missing_imports = true

compound_memory-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

compound_memory-0.1.0/src/compound_memory/__init__.py

@@ -0,0 +1,3 @@
+"""compound-memory: local multi-agent shared memory with compounding."""
+
+__version__ = "0.1.0"

compound_memory-0.1.0/src/compound_memory/cli.py

@@ -0,0 +1,190 @@
+"""CLI：不经 MCP 直接访问同一 store（脚本、定时蒸馏、衰减扫描等运维面）。"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .embedding import auto_encoder
+from .storage import DISTILL_DUP_SIM_THRESHOLD, MEMORY_TYPES, MemoryStore, PROMOTION_USES_THRESHOLD, default_root
+
+
+def _emit(payload: Any) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2, default=str))
+
+
+def _open_store(args: argparse.Namespace) -> MemoryStore:
+    # CLI 与 server 同权：vec extra + 模型就绪即启用向量路，否则自动降级纯词面
+    return MemoryStore(Path(args.root), embedder=auto_encoder())
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    store = _open_store(args)
+    _emit({"ok": True, "root": str(store.root)})
+
+
+def cmd_write(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).write(content=args.content, type=args.type, source=args.source, ns=args.ns, key=args.key))
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    _emit(
+        _open_store(args).search(
+            query=args.query, ns=args.ns, top_k=args.top_k, include_neighbors=args.include_neighbors
+        )
+    )
+
+
+def cmd_get(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).get(args.id))
+
+
+def cmd_link(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).link(args.a, args.b))
+
+
+def cmd_feedback(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).feedback(args.id, args.agent))
+
+
+def cmd_decay(args: argparse.Namespace) -> None:
+    # --now 经固定 clock 的 store 注入——时间接缝只有 clock 一条（store 不另设 now= 参数）
+    if args.now:
+        store = MemoryStore(Path(args.root), clock=lambda: dt.date.fromisoformat(args.now))
+    else:
+        store = _open_store(args)
+    _emit({"archived": store.decay_sweep()})
+
+
+def cmd_revive(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).revive(args.id))
+
+
+def cmd_stats(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).stats())
+
+
+def cmd_rebuild_index(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).rebuild_index())
+
+
+def cmd_review_queue(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).review_queue())
+
+
+def cmd_review_resolve(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).review_resolve(ids=args.ids, all=args.all))
+
+
+def cmd_distill_plan(args: argparse.Namespace) -> None:
+    _emit(
+        _open_store(args).distill_plan(
+            window_days=args.window,
+            min_uses=args.min_uses,
+            min_confidence=args.min_confidence,
+            ns=args.ns,
+        )
+    )
+
+
+def cmd_distill_apply(args: argparse.Namespace) -> None:
+    _emit(
+        _open_store(args).distill_apply(
+            content=args.content,
+            type=args.type,
+            source=args.source,
+            source_ids=[s.strip() for s in args.sources.split(",") if s.strip()],
+            ns=args.ns,
+            key=args.key,
+            confidence=args.confidence,
+        )
+    )
+
+
+def cmd_git_log(args: argparse.Namespace) -> None:
+    _emit(_open_store(args).git_log(limit=args.limit))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="compound-memory", description="local multi-agent shared memory")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--root", default=None, help="store root (default: $COMPOUND_MEMORY_ROOT or ~/.agents/memory)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init"); p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("write")
+    p.add_argument("content"); p.add_argument("type", choices=MEMORY_TYPES)
+    p.add_argument("source"); p.add_argument("--ns", default="_shared"); p.add_argument("--key", default=None)
+    p.set_defaults(func=cmd_write)
+
+    p = sub.add_parser("search")
+    p.add_argument("query"); p.add_argument("--ns", default="_shared"); p.add_argument("--top-k", type=int, default=5)
+    p.add_argument("--no-neighbors", dest="include_neighbors", action="store_false",
+                   help="omit embedded one-hop neighbors from hits")
+    p.set_defaults(func=cmd_search)
+
+    p = sub.add_parser("get"); p.add_argument("id"); p.set_defaults(func=cmd_get)
+    p = sub.add_parser("link"); p.add_argument("a"); p.add_argument("b"); p.set_defaults(func=cmd_link)
+    p = sub.add_parser("feedback"); p.add_argument("id"); p.add_argument("agent"); p.set_defaults(func=cmd_feedback)
+
+    p = sub.add_parser("decay"); p.add_argument("--now", default=None, help="ISO date override (testing)")
+    p.set_defaults(func=cmd_decay)
+
+    p = sub.add_parser("revive"); p.add_argument("id"); p.set_defaults(func=cmd_revive)
+    p = sub.add_parser(
+        "distill-plan",
+        help="scan distillation candidates and print a signal-annotated list",
+        description="Scan distillation candidates (deterministic half of distillation). Signals per candidate: "
+        f"merge_with (same ns/type/key, strong), possible_dup_of (BM25 normalized_similarity >= {DISTILL_DUP_SIM_THRESHOLD}, weak), "
+        f"promotion_candidate (episode uses >= {PROMOTION_USES_THRESHOLD}). Judgment (merge/summarize) stays with the calling agent.",
+    )
+    p.add_argument("--window", type=int, default=30, help="recency window in days (last_used first, created fallback)")
+    p.add_argument("--min-uses", type=int, default=1, help="activity gate: uses >= this")
+    p.add_argument("--min-confidence", type=float, default=0.5, help="activity gate: confidence >= this")
+    p.add_argument("--ns", default="_shared")
+    p.set_defaults(func=cmd_distill_plan)
+    p = sub.add_parser("distill-apply")
+    p.add_argument("content"); p.add_argument("type", choices=MEMORY_TYPES); p.add_argument("source")
+    p.add_argument("--sources", required=True, help="comma-separated source memory ids")
+    p.add_argument("--ns", default="_shared"); p.add_argument("--key", default=None)
+    p.add_argument("--confidence", type=float, default=None)
+    p.set_defaults(func=cmd_distill_apply)
+    p = sub.add_parser("stats"); p.set_defaults(func=cmd_stats)
+    p = sub.add_parser("rebuild-index"); p.set_defaults(func=cmd_rebuild_index)
+    p = sub.add_parser("review-queue"); p.set_defaults(func=cmd_review_queue)
+    p = sub.add_parser(
+        "review-resolve",
+        help="mark review-queue conflicts as resolved",
+        description="Clear review-queue entries after the caller has judged the conflict "
+        "(old/new trade-off stays with the calling agent or human). Pass memory ids to clear "
+        "matching rows (either the old or new id of a row counts), or --all to clear the queue. "
+        "Unknown ids are rejected atomically; the cleanup is auto-committed.",
+    )
+    p.add_argument("ids", nargs="*", metavar="ID")
+    p.add_argument("--all", action="store_true", help="clear the whole queue")
+    p.set_defaults(func=cmd_review_resolve)
+    p = sub.add_parser("git-log"); p.add_argument("--limit", type=int, default=5); p.set_defaults(func=cmd_git_log)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.root is None:
+        args.root = default_root()
+    try:
+        args.func(args)
+        return 0
+    except (ValueError, PermissionError) as exc:
+        # store 接口的调用方错误统一在这里翻译成 JSON（MCP 侧由框架转 is_error）
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

compound_memory-0.1.0/src/compound_memory/embedding.py

@@ -0,0 +1,96 @@
+"""BGE-small-zh 本地 embedding 编码器（向量召回路的模型缝）。
+
+- 模型：默认 Xenova/bge-small-zh-v1.5 ONNX int8（24MB，经 hf-mirror 下载到 HF 缓存，
+  本地推理全程无外发，spec story 17）。缓存缺失时构造即失败——不自动联网下载。
+  repo id 与输出维度可经环境变量覆盖（换模型属运维动作，改后需显式 rebuild-index）：
+  - COMPOUND_MEMORY_EMBEDDING_MODEL：HF repo id（默认 Xenova/bge-small-zh-v1.5）；
+  - COMPOUND_MEMORY_EMBEDDING_DIM：模型输出维度（默认 512，须与模型一致）。
+- 依赖：属可选 extra `vec`（onnxruntime/tokenizers/numpy）。本模块 import 任何
+  失败都置 VEC_AVAILABLE=False，由调用方降级为纯词面检索（检索降级不报错）。
+- 编码语义（与 vec-spike 验证一致）：[CLS] 表示 + L2 归一化，truncation 512。
+  单条长文档实测 ~400ms，查询短文本 ~15ms。
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+from pathlib import Path
+from typing import Callable
+
+# 模型与维度的单一定义点：vector_index 建表维度也从这里 import，勿另设常量
+MODEL_REPO_ID = os.environ.get("COMPOUND_MEMORY_EMBEDDING_MODEL", "Xenova/bge-small-zh-v1.5")
+EMBED_DIM = int(os.environ.get("COMPOUND_MEMORY_EMBEDDING_DIM", "512"))
+
+
+def _cache_glob(repo_id: str) -> str:
+    """HF 缓存目录 glob：repo id 的 "/" 替换为 "--"（如 a/b → models--a--b）。"""
+    return f".cache/huggingface/hub/models--{repo_id.replace('/', '--')}/snapshots/*"
+
+
+_MODEL_GLOB = _cache_glob(MODEL_REPO_ID)
+
+try:
+    import numpy as np
+    import onnxruntime as ort
+    from tokenizers import Tokenizer
+
+    VEC_AVAILABLE = True
+except ImportError:  # pragma: no cover - 取决于安装环境是否带 vec extra
+    VEC_AVAILABLE = False
+
+
+class ModelMissingError(RuntimeError):
+    """HF 缓存中找不到 BGE ONNX 模型（本地优先：不做自动下载，交调用方降级）。"""
+
+
+def auto_encoder() -> "Callable[[list[str]], list[list[float]]] | None":
+    """入口默认缝：依赖与模型都就绪才返回编码器（encode 绑定方法），否则 None（降级纯词面）。"""
+    if not VEC_AVAILABLE:
+        return None
+    try:
+        return BgeEncoder().encode
+    except (ModelMissingError, OSError):
+        return None
+
+
+class BgeEncoder:
+    """惰性加载的 ONNX 编码器；构造只解析模型路径，首次 encode 才建 session。"""
+
+    def __init__(self, home: Path | None = None) -> None:
+        if not VEC_AVAILABLE:
+            raise ModelMissingError("vec dependencies not installed (pip install 'compound-memory[vec]')")
+        base = home or Path.home()
+        snaps = sorted(glob.glob(str(base / _MODEL_GLOB)))
+        if not snaps:
+            raise ModelMissingError(
+                f"{MODEL_REPO_ID} ONNX model not found in HF cache; "
+                "download via hf-mirror.com (see docs/specs/0001-compound-memory-spec.md)"
+            )
+        snap = Path(snaps[-1])
+        self._onnx_path = snap / "onnx" / "model_quantized.onnx"
+        self._tokenizer_path = snap / "tokenizer.json"
+        if not self._onnx_path.exists() or not self._tokenizer_path.exists():
+            raise ModelMissingError(f"incomplete model snapshot: {snap}")
+        self._session: "ort.InferenceSession | None" = None
+        self._tokenizer: "Tokenizer | None" = None
+
+    def encode(self, texts: list[str]) -> list[list[float]]:
+        """批量编码；L2 归一化后的 [CLS] 表示（余弦可直接用作相似度）。"""
+        assert VEC_AVAILABLE  # 构造已保证；reassure 类型检查
+        if self._session is None or self._tokenizer is None:
+            self._tokenizer = Tokenizer.from_file(str(self._tokenizer_path))
+            self._tokenizer.enable_truncation(max_length=512)
+            self._tokenizer.enable_padding()
+            self._session = ort.InferenceSession(str(self._onnx_path), providers=["CPUExecutionProvider"])
+        encs = self._tokenizer.encode_batch(texts)
+        feed = {
+            "input_ids": np.array([e.ids for e in encs], dtype=np.int64),
+            "attention_mask": np.array([e.attention_mask for e in encs], dtype=np.int64),
+            "token_type_ids": np.array([e.type_ids for e in encs], dtype=np.int64),
+        }
+        names = {i.name for i in self._session.get_inputs()}
+        out = self._session.run(None, {k: v for k, v in feed.items() if k in names})[0]
+        cls = out[:, 0, :]
+        normed = cls / np.linalg.norm(cls, axis=1, keepdims=True)
+        return normed.tolist()