compound-memory 0.1.0__py3-none-any.whl

compound_memory/__init__.py

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

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/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()

compound_memory/index.py

@@ -0,0 +1,203 @@
+"""Index: token→path 的可重建缓存（纯路径集合视图）。
+
+不变量在此唯一归属：活动记忆必被索引，归档记忆必不在索引。
+缓存文件缺失或损坏 ⇒ 经注入的 scan_pairs 全量重建——降级到慢，绝不报错。
+活性是 store 级而非进程级：读路径检测跨进程缓存更新（重载）与带外目录
+变更（增量对账，只应用 diff）；手编已有文件的内容不改目录 mtime，那条路走显式 rebuild。
+检索文本知识来自 scoring.doc_text（单一定义点）。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Callable
+
+from .model import Memory
+from .scoring import tokenize, doc_text
+
+
+class Index:
+    """Deep module: 三个动词 sync / candidates / rebuild，缓存机制全部在实现内。
+
+    调用方无需感知缓存何时加载、何时重建、archived 走哪条路，
+    也无需感知缓存是否被其他进程更新过——活性检测在读路径内部完成。
+    """
+
+    def __init__(self, root: Path, scan_pairs: Callable[[], list[tuple[Memory, str]]]) -> None:
+        self._root = root
+        self._scan_pairs = scan_pairs
+        self._dir = root / "index"
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._path = self._dir / "tokens.json"
+        self._data: dict[str, list[str]] | None = None  # None = 未加载
+        self._dead = False  # 落盘缓存缺失或损坏，待重建
+        self._loaded_stamp: int | None = None  # 缓存文件上次加载时的 mtime_ns
+
+    # ---------- 缓存活性（重建/重载协议在这里，调用方不可见） ----------
+
+    def _load(self) -> dict[str, list[str]]:
+        if self._data is None:
+            try:
+                self._data = json.loads(self._path.read_text(encoding="utf-8"))
+                self._loaded_stamp = self._cache_stamp()
+            except (OSError, json.JSONDecodeError):
+                self._data = {}
+                self._dead = True
+        return self._data
+
+    def _cache_stamp(self) -> int | None:
+        try:
+            return self._path.stat().st_mtime_ns
+        except OSError:
+            return None
+
+    def _ensure_live(self) -> None:
+        """写路径保活：缓存缺失/损坏 ⇒ 重建（随后的增量 upsert 基于活缓存）。"""
+        self._load()
+        if self._dead or not self._path.exists():
+            self.rebuild(self._scan_pairs())
+
+    def _ensure_fresh(self) -> None:
+        """读路径三级自愈（原 Q1-A 决策的跨进程扩展）：
+
+        1. 缺失/损坏 ⇒ 全量重建；
+        2. 缓存文件 mtime 变了（其他进程写过）⇒ 丢弃内存态重载；
+        3. 任一 ns/type 目录 mtime 晚于缓存文件（带外新增/删除 .md）
+           ⇒ 增量对账：scan 后只更新 diff 的条目（与 VectorIndex._reconcile
+           同构，perf-bench：千条库带外写后首查的大头）。
+        """
+        self._ensure_live()
+        stamp = self._cache_stamp()
+        if self._loaded_stamp is not None and stamp != self._loaded_stamp:
+            self._data = None
+            self._load()
+            if self._dead:
+                self.rebuild(self._scan_pairs())
+                return
+            stamp = self._loaded_stamp if self._loaded_stamp is not None else stamp
+        if stamp is not None and self._dirs_newer_than(stamp):
+            self._reconcile()
+
+    def _dirs_newer_than(self, cache_stamp: int) -> bool:
+        """活动区目录在缓存落盘后发生过增删（新增/删除文件会更新父目录 mtime）。"""
+        ns_root = self._root / "namespaces"
+        if not ns_root.is_dir():
+            return False
+        try:
+            ns_dirs = [d for d in ns_root.iterdir() if d.is_dir()]
+        except OSError:
+            return False
+        for ns_dir in ns_dirs:
+            try:
+                if ns_dir.stat().st_mtime_ns > cache_stamp:
+                    return True
+                type_dirs = [d for d in ns_dir.iterdir() if d.is_dir()]
+            except OSError:
+                continue
+        for t_dir in type_dirs:
+            try:
+                if t_dir.stat().st_mtime_ns > cache_stamp:
+                    return True
+            except OSError:
+                continue
+        return False
+
+    def _reconcile(self) -> None:
+        """带外增删的增量对账：反转缓存出 rel→tokens 基线，scan 后只应用 diff。
+
+        与 VectorIndex._reconcile 同构——带外写一条不再放大成全库重建
+        （scan + tokenize + tokens.json 全量重写，千条库秒级）。diff 应用在
+        内存态完成后一次落盘；缓存与全量重建是集合等价的（rels 列表顺序
+        不保证一致，candidates 的 sorted 输出不受影响）。
+        """
+        index = self._load()
+        known: dict[str, set[str]] = {}
+        for tok, rels in index.items():
+            for rel in rels:
+                known.setdefault(rel, set()).add(tok)
+        active: dict[str, set[str]] = {}
+        for mem, rel in self._scan_pairs():
+            if not mem.archived:
+                active[rel] = set(tokenize(doc_text(mem)))
+        changed = False
+        for rel, tokens in active.items():
+            if known.get(rel) == tokens:
+                continue
+            self._purge(rel)
+            for tok in tokens:
+                index.setdefault(tok, []).append(rel)
+            changed = True
+        for rel in known:
+            if rel not in active:
+                self._purge(rel)
+                changed = True
+        if changed:
+            self._save()
+
+    def _save(self) -> None:
+        # 目录可能被外部整体移走（测试模拟缓存丢失、或人为 rm -rf index/），写前确保存在
+        self._dir.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(self._data or {}, ensure_ascii=False, sort_keys=True), encoding="utf-8")
+        tmp.replace(self._path)
+        self._loaded_stamp = self._cache_stamp()  # 自己写盘后刷新基线，避免自触发重载
+
+    # ---------- interface ----------
+
+    def sync(self, mem: Memory, rel_path: str) -> None:
+        """使索引与 mem 一致：active ⇒ rel_path 已索引；archived ⇒ rel_path 已移除。
+
+        rel_path 指该记忆在活动区的路径；归档场景由调用方传入原活动路径。
+        """
+        self._ensure_live()
+        if mem.archived:
+            self._remove(rel_path)
+        else:
+            self._upsert(mem, rel_path)
+
+    def candidates(self, tokens: list[str]) -> list[str]:
+        """文档含任一 query token 的相对路径；[] 表示无匹配。
+
+        读路径三级自愈（跨进程重载 / 带外重建）在内部完成，调用方无感。
+        """
+        self._ensure_fresh()
+        index = self._load()
+        rels: set[str] = set()
+        for tok in tokens:
+            rels.update(index.get(tok, []))
+        return sorted(rels)
+
+    def rebuild(self, memories: list[tuple[Memory, str]]) -> dict[str, int]:
+        """以 (memory, rel_path) 序对全量重建；返回计数。"""
+        index: dict[str, list[str]] = {}
+        for mem, rel in memories:
+            for tok in set(tokenize(doc_text(mem))):
+                index.setdefault(tok, []).append(rel)
+        self._data = index
+        self._dead = False
+        self._save()
+        return {"memories": len(memories), "tokens": len(index)}
+
+    # ---------- 内部：变更原语 ----------
+
+    def _purge(self, rel_path: str) -> None:
+        """清除某条路径的全部词条残留（不落盘，由调用方决定后续写）。"""
+        index = self._load()
+        for tok in list(index):
+            if rel_path in index[tok]:
+                index[tok].remove(rel_path)
+                if not index[tok]:
+                    del index[tok]
+
+    def _upsert(self, mem: Memory, rel_path: str) -> None:
+        """加入/刷新一条记忆的词条；先移除其残留旧路径。"""
+        self._purge(rel_path)
+        index = self._load()
+        for tok in set(tokenize(doc_text(mem))):
+            index.setdefault(tok, []).append(rel_path)
+        self._save()
+
+    def _remove(self, rel_path: str) -> None:
+        self._purge(rel_path)
+        self._save()

compound_memory/model.py

@@ -0,0 +1,44 @@
+"""Domain model shared across modules (moved out of storage to break the cycle)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class TypeSpec:
+    """一种记忆类型的全套规格——全系统唯一的类型知识源（CONTEXT.md: memory type）。"""
+
+    ttl_days: int | None  # 归档 TTL；None = 永不衰减
+    weight: float  # 检索类型权重
+    tau_days: float  # 新近半衰期（天）
+
+
+TYPE_SPEC: dict[str, TypeSpec] = {
+    "episode": TypeSpec(ttl_days=90, weight=0.5, tau_days=30.0),
+    "fact": TypeSpec(ttl_days=None, weight=0.9, tau_days=365.0),
+    "insight": TypeSpec(ttl_days=180, weight=0.7, tau_days=90.0),
+    "skill": TypeSpec(ttl_days=None, weight=1.0, tau_days=365.0),
+}
+MEMORY_TYPES = tuple(TYPE_SPEC)
+TTL_DAYS: dict[str, int | None] = {t: s.ttl_days for t, s in TYPE_SPEC.items()}
+
+
+@dataclass
+class Memory:
+    id: str
+    ns: str
+    type: str
+    source: str
+    created: str
+    content: str
+    confidence: float = 0.5
+    uses: int = 0
+    last_used: str | None = None
+    links: list[str] = field(default_factory=list)
+    ttl: int | None = None
+    key: str | None = None
+    validated_by: list[str] = field(default_factory=list)
+    archived: bool = False
+    # 写入来源通道（frontmatter 可选字段）：普通写入不落盘，仅蒸馏产物为 "distillation"
+    origin: str | None = None

compound_memory/review_queue.py

@@ -0,0 +1,82 @@
+"""Review queue（冲突队列）：review-queue.md 的生成、解析与清除——行格式单一定义点。
+
+每行一条冲突记录，由 MemoryStore._write_new 在同 key fact/insight 内容冲突时 append；
+裁决（新旧取舍）归调用方，这里只登记、展示与清除，不做判断、不碰 git。
+
+行结构（append 生成，机器写入）：old/new 记忆 id 各在 "(` 与 " (" 边界；
+非贪婪到首个 " vs "——content 截断 40 字符，正则回溯保证内容含 " vs " 时仍取对 id。
+解析失败的行 fail-safe 保留：宁可不登记，不误删记录。
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from pathlib import Path
+from typing import Callable
+
+from .model import Memory
+
+_REVIEW_ROW_RE = re.compile(r"^- \S+ conflict `[^`]+`: (?P<old>\S+) \(.*?\) vs (?P<new>\S+) \(")
+
+
+class ReviewQueue:
+    """冲突队列 artifact 的所有者：append 写入、lines 展示、resolve 清除。"""
+
+    def __init__(self, path: Path, clock: Callable[[], dt.date]) -> None:
+        self.path = path
+        self._clock = clock
+
+    def append(self, old: Memory, new: Memory) -> None:
+        line = (
+            f"- {self._clock().isoformat()} conflict `{new.ns}/{new.type}/{new.key}`: "
+            f"{old.id} ({old.source}: {old.content[:40]}) vs {new.id} ({new.source}: {new.content[:40]})\n"
+        )
+        with self.path.open("a", encoding="utf-8") as fh:
+            fh.write(line)
+
+    def lines(self) -> list[str]:
+        """展示行（去 "- " 前缀，即 CLI review-queue 的输出）。"""
+        if not self.path.exists():
+            return []
+        return [
+            line[2:].rstrip("\n")
+            for line in self.path.read_text(encoding="utf-8").splitlines()
+            if line.startswith("- ")
+        ]
+
+    def resolve(self, ids: list[str] | None = None, all: bool = False) -> dict[str, int]:
+        """清除命中行，返回 {"resolved", "remaining"}；git commit 归调用方（MemoryStore）。
+
+        - all=True：清空整个队列（幂等，空队列返回 resolved=0）。
+        - 按 id：行内 old/new 任一命中即整行清除；任一 id 未命中任何行 ⇒
+          ValueError 原子拒绝（队列原样保留），避免半清状态让调用方误判。
+        """
+        if all and ids:
+            raise ValueError("pass either ids or --all, not both")
+        if not all and not ids:
+            raise ValueError("review-resolve needs memory ids or --all")
+        if self.path.exists():
+            lines = self.path.read_text(encoding="utf-8").splitlines(keepends=True)
+        else:
+            lines = []
+        if all:
+            keep = []
+            removed = sum(1 for line in lines if line.startswith("- "))
+        else:
+            wanted = set(ids or [])
+            covered: set[str] = set()
+            matched: list[bool] = []
+            for line in lines:
+                m = _REVIEW_ROW_RE.match(line)
+                matched.append(m is not None and bool(wanted & {m.group("old"), m.group("new")}))
+                if m is not None:
+                    covered |= {m.group("old"), m.group("new")}
+            missing = wanted - covered
+            if missing:
+                raise ValueError(f"ids not found in review queue: {', '.join(sorted(missing))}")
+            keep = [line for line, hit in zip(lines, matched) if not hit]
+            removed = sum(matched)
+        if removed:
+            self.path.write_text("".join(keep), encoding="utf-8")
+        return {"resolved": removed, "remaining": sum(1 for line in keep if line.startswith("- "))}