neobot-memory 1.0.0__tar.gz

neobot_memory-1.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: neobot-memory
+Version: 1.0.0
+Summary: Add your description here
+Author: wsrsq, tangtian
+Author-email: wsrsq <wsrsq001@163.com>, tangtian <a14b@126.com>
+Requires-Dist: neobot-contracts
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

neobot_memory-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "neobot-memory"
+version = "1.0.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["neobot-contracts"]
+
+[[project.authors]]
+name = "wsrsq"
+email = "wsrsq001@163.com"
+
+[[project.authors]]
+name = "tangtian"
+email = "a14b@126.com"
+
+[tool.uv.sources.neobot-contracts]
+workspace = true
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_memory-1.0.0/pyproject.toml.orig

@@ -0,0 +1,18 @@
+[project]
+name = "neobot-memory"
+version = "1.0.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "wsrsq", email = "wsrsq001@163.com" },
+    { name = "tangtian", email = "a14b@126.com" },
+]
+requires-python = ">=3.13"
+dependencies = ["neobot-contracts"]
+
+[tool.uv.sources]
+neobot-contracts = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_memory-1.0.0/src/neobot_memory/__init__.py

@@ -0,0 +1,25 @@
+"""neobot_memory — 记忆包公共 API"""
+
+from neobot_memory.archive_service import ArchiveMemoryService
+from neobot_memory.defaults import (
+    InMemoryArchiveMemoryAccess,
+    InMemoryImageAnalysisAccess,
+    InMemoryMemoryRepository,
+    NullLogger,
+    SystemClock,
+)
+from neobot_memory.image_service import ImageAnalysisService
+from neobot_memory.reader import MemoryReader
+from neobot_memory.service import MemoryService
+
+__all__ = [
+    "ArchiveMemoryService",
+    "ImageAnalysisService",
+    "MemoryService",
+    "MemoryReader",
+    "InMemoryMemoryRepository",
+    "InMemoryArchiveMemoryAccess",
+    "InMemoryImageAnalysisAccess",
+    "NullLogger",
+    "SystemClock",
+]

neobot_memory-1.0.0/src/neobot_memory/archive_service.py

@@ -0,0 +1,718 @@
+"""归档记忆服务。
+
+本模块同时是「档案容量治理」的唯一收口点：save_archive、patch_archive 与自动总结
+计数器三条写入路径最终都走 ArchiveMemoryService.set()，超限判定放在这里才能保证
+绕过 skill 的写入同样受保护（D1-B）。
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from neobot_contracts.errors import NeoBotError
+from neobot_contracts.models.memory import ArchiveMemory
+from neobot_contracts.ports.logging import Logger
+from neobot_contracts.ports.unit_of_work import UnitOfWorkFactory
+
+#: 超限动作默认值：写库成功后异步压缩。
+DEFAULT_OVERFLOW_ACTION = "summarize"
+#: 同一 (table_name, key) 两次自动压缩之间的默认最小间隔（秒）。
+DEFAULT_OVERFLOW_COOLDOWN_SECONDS = 600.0
+#: 超限清单一次最多返回多少条（防止把大表整块塞进面板响应体）。
+_MAX_OVER_LIMIT_PAGE_SIZE = 500
+#: 超限清单里的内容预览字符数。
+_OVER_LIMIT_PREVIEW_CHARS = 200
+#: 同一 (table_name, key) 只保留最近多少份「压缩前快照」（spec(4) §4.10.4 / D15）。
+MAX_ARCHIVE_SNAPSHOTS_PER_KEY = 10
+#: 压缩前快照的全局兜底上限（防止大量不同 key 无限累积）。
+MAX_ARCHIVE_SNAPSHOTS = 2000
+
+#: 不参与容量治理的内部表（默认豁免名单）。
+#: ⚠️ 与 agent.memory.archive.allowed_tables 语义完全不同：那个是「限制模型能访问
+#: 哪些表」，这里是「哪些表不做长度上限拦截」，两者绝不可复用。
+#: memory_counter 存的是「待总结消息 JSON」，group_interval=500 时天然超过任何上限：
+#:   - 若对它 reject：自动总结连计数都写不进去，整条管线直接断掉；
+#:   - 若对它 summarize：压缩器会去「压缩」待总结消息队列，把尚未总结的消息吃掉。
+#: 因此它必须无条件豁免；一旦误伤，表现是「档案自动总结整体失效」，比长度超限严重得多。
+DEFAULT_EXEMPT_TABLES: frozenset[str] = frozenset({"memory_counter"})
+
+#: 超限压缩的调度回调签名：(table_name, key) -> 是否已调度。
+#: 必须立即返回（同步）：写路径要求「先落库、再异步压缩」，不能等一次完整的 AI 调用。
+OverflowSummaryTrigger = Callable[[str, str], bool]
+
+
+class ArchiveOverflowRejected(NeoBotError, ValueError):
+    """overflow_action="reject" 时拒绝写入（交由模型自行压缩后重试）。"""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        table_name: str = "",
+        key: str = "",
+        chars: int = 0,
+        max_total_chars: int = 0,
+        hint: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.table_name = table_name
+        self.key = key
+        self.chars = chars
+        self.max_total_chars = max_total_chars
+        self.hint = hint
+
+
+class ArchiveVersionConflictError(NeoBotError, ValueError):
+    """档案乐观锁版本冲突（服务层公开异常，面板据此返回 409）。
+
+    仓库层（neobot_storage）在版本不一致时抛出它自己的同名异常，
+    服务层统一翻译成本类，面板只需要依赖 neobot_memory。
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        table_name: str = "",
+        key: str = "",
+        expected_version: int = 0,
+        actual_version: int = 0,
+    ) -> None:
+        super().__init__(message)
+        self.table_name = table_name
+        self.key = key
+        self.expected_version = expected_version
+        self.actual_version = actual_version
+
+
+@dataclass(frozen=True)
+class ArchiveWriteOutcome:
+    """一次档案写入的结果，附带容量治理信息。
+
+    item 为 None 表示写入被拒绝（只在 overflow_action="reject" 时出现）。
+    """
+
+    item: Optional[ArchiveMemory] = None
+    over_limit: bool = False
+    action: str = "none"  # none | summarize | reject
+    scheduled: bool = False  # 是否已把后台压缩交给触发方
+    chars: int = 0
+    max_total_chars: int = 0
+    hint: str = ""
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        """写入是否真的落库。"""
+        return self.item is not None
+
+
+def _normalize_max_total_chars(value: Any) -> int:
+    """把配置读成非负整数上限；None/非法值/负数一律视为 0（禁用）。"""
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 0
+    return parsed if parsed > 0 else 0
+
+
+def _normalize_overflow_action(value: Any) -> str:
+    """把配置读成 summarize / reject；未知值回落到 summarize。"""
+    action = str(value or "").strip().lower()
+    return action if action in {"summarize", "reject"} else DEFAULT_OVERFLOW_ACTION
+
+
+def _normalize_cooldown(value: Any) -> float:
+    """把配置读成非负冷却秒数；None/非法值回落默认值。"""
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_OVERFLOW_COOLDOWN_SECONDS
+    return parsed if parsed > 0 else 0.0
+
+
+class ArchiveMemoryService:
+    """归档记忆的增删改查与查询操作服务。"""
+
+    def __init__(
+        self,
+        uow_factory: UnitOfWorkFactory,
+        logger: Logger,
+        *,
+        max_total_chars: Any = 0,
+        overflow_action: Any = DEFAULT_OVERFLOW_ACTION,
+        overflow_summary_cooldown_seconds: Any = DEFAULT_OVERFLOW_COOLDOWN_SECONDS,
+        exempt_tables: Iterable[str] | None = None,
+    ) -> None:
+        self._uow_factory = uow_factory
+        self._logger = logger
+        # 容量治理默认关闭：只有外部（bootstrap / 自动总结服务）显式配置后才会生效，
+        # 从而保证「不接线 = 与现状完全一致」。
+        self._max_total_chars = _normalize_max_total_chars(max_total_chars)
+        self._overflow_action = _normalize_overflow_action(overflow_action)
+        self._overflow_cooldown_seconds = _normalize_cooldown(overflow_summary_cooldown_seconds)
+        self._exempt_tables: frozenset[str] = (
+            frozenset(str(name) for name in exempt_tables)
+            if exempt_tables is not None
+            else DEFAULT_EXEMPT_TABLES
+        )
+        self._overflow_trigger: Optional[OverflowSummaryTrigger] = None
+        #: (table_name, key) -> 冷却到期时刻（time.monotonic()）
+        self._overflow_cooldown_until: dict[tuple[str, str], float] = {}
+
+    # ── 容量治理配置 ────────────────────────────────────────────────
+
+    def configure_overflow_policy(
+        self,
+        *,
+        max_total_chars: Any = None,
+        overflow_action: Any = None,
+        cooldown_seconds: Any = None,
+        exempt_tables: Iterable[str] | None = None,
+    ) -> None:
+        """配置单条档案的存储上限与超限动作；参数为 None 表示保持当前值。
+
+        max_total_chars=0 表示禁用容量治理（行为回落到现状）。
+        """
+        if max_total_chars is not None:
+            self._max_total_chars = _normalize_max_total_chars(max_total_chars)
+        if overflow_action is not None:
+            self._overflow_action = _normalize_overflow_action(overflow_action)
+        if cooldown_seconds is not None:
+            self._overflow_cooldown_seconds = _normalize_cooldown(cooldown_seconds)
+        if exempt_tables is not None:
+            self._exempt_tables = frozenset(str(name) for name in exempt_tables)
+
+    def set_overflow_trigger(self, trigger: Optional[OverflowSummaryTrigger]) -> None:
+        """注入「档案超限 → 调度一次自动压缩」的回调（None 表示卸载）。"""
+        self._overflow_trigger = trigger
+
+    @property
+    def max_total_chars(self) -> int:
+        """单条档案的存储硬上限；0 表示禁用。"""
+        return self._max_total_chars
+
+    @property
+    def overflow_action(self) -> str:
+        """超限动作：summarize / reject。"""
+        return self._overflow_action
+
+    @property
+    def exempt_tables(self) -> frozenset[str]:
+        """不参与容量治理的内部表集合。"""
+        return self._exempt_tables
+
+    def clear_overflow_cooldown(self, table_name: str, key: str) -> None:
+        """清除某个条目的压缩冷却。
+
+        压缩失败时由触发方调用：失败不应该被冷却窗口掩盖成 600 秒的静默，
+        清掉冷却后「下次写入再试」才成立（是否真的重试仍由触发方的失败退避决定）。
+        """
+        self._overflow_cooldown_until.pop((table_name, key), None)
+
+    # ── 基本读写（签名语义保持不变，面板直接转调） ──────────────────
+
+    async def get(self, table_name: str, key: str) -> Optional[ArchiveMemory]:
+        async with self._uow_factory() as uow:
+            item = await uow.archive.get(table_name, key)
+        self._logger.debug("存档记忆已获取", table_name=table_name, key=key, found=item is not None)
+        return item
+
+    async def exists(self, table_name: str, key: str) -> bool:
+        async with self._uow_factory() as uow:
+            exists = await uow.archive.exists(table_name, key)
+        self._logger.debug("存档记忆存在检查", table_name=table_name, key=key, exists=exists)
+        return exists
+
+    async def list(
+        self,
+        table_name: str,
+        *,
+        tags: Optional[list[str]] = None,
+        key_query: Optional[str] = None,
+        value_query: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ArchiveMemory]:
+        async with self._uow_factory() as uow:
+            items = await uow.archive.list(
+                table_name,
+                tags=tags,
+                key_query=key_query,
+                value_query=value_query,
+                limit=limit,
+                offset=offset,
+            )
+        self._logger.debug(
+            "存档记忆列表已获取",
+            table_name=table_name,
+            count=len(items),
+            limit=limit,
+            offset=offset,
+        )
+        return items
+
+    async def set(self, table_name: str, key: str, value: str, tags: list[str]) -> ArchiveMemory:
+        """创建或更新归档记忆条目（容量治理的唯一收口点）。
+
+        超过 max_total_chars 时：
+        - overflow_action="summarize"：先落库（不丢信息），再触发异步压缩，立即返回；
+        - overflow_action="reject"：不写库，抛 ArchiveOverflowRejected。
+        """
+        outcome = await self.set_with_outcome(table_name, key, value, tags)
+        if outcome.item is None:
+            raise ArchiveOverflowRejected(
+                outcome.error or f"档案超过存储上限: {table_name}:{key}",
+                table_name=table_name,
+                key=key,
+                chars=outcome.chars,
+                max_total_chars=outcome.max_total_chars,
+                hint=outcome.hint,
+            )
+        return outcome.item
+
+    async def set_with_outcome(
+        self, table_name: str, key: str, value: str, tags: list[str]
+    ) -> ArchiveWriteOutcome:
+        """与 set 相同，但把超限信息（over_limit / 是否已调度压缩 / hint）一并返回。
+
+        工具层（archive_crud）用它给模型回 over_limit=True + hint；面板/内部写路径
+        可以直接用 set()。
+        """
+        limit = self._max_total_chars
+        chars = len(value or "")
+        governed = table_name not in self._exempt_tables
+        over_limit = governed and limit > 0 and chars > limit
+        if over_limit and self._overflow_action == "reject":
+            hint = (
+                f"档案超过存储上限 {limit} 字（当前 {chars} 字），已拒绝写入"
+                "（agent.memory.archive.overflow_action=reject）。"
+                "请先用 read_archive 的 outline/offset 分页阅读，再用 patch_archive "
+                "压缩或删除冗余内容后重试。"
+            )
+            self._logger.warning(
+                "档案超过存储上限，按配置拒绝写入",
+                table_name=table_name,
+                key=key,
+                chars=chars,
+                max_total_chars=limit,
+            )
+            return ArchiveWriteOutcome(
+                item=None,
+                over_limit=True,
+                action="reject",
+                chars=chars,
+                max_total_chars=limit,
+                hint=hint,
+                error=f"档案超过存储上限 {limit} 字（当前 {chars} 字），已拒绝写入",
+            )
+
+        async with self._uow_factory() as uow:
+            item = await uow.archive.set(table_name, key, value, tags)
+            await uow.commit()
+        self._logger.debug(
+            "存档记忆已保存",
+            table_name=table_name,
+            key=key,
+            version=item.version,
+        )
+        if not over_limit:
+            return ArchiveWriteOutcome(item=item, chars=chars, max_total_chars=limit)
+
+        # 先写后压缩：原文已经落库，压缩只是在后台把体积收回来（不丢信息）。
+        scheduled = self._schedule_overflow_compression(table_name, key, chars=chars, limit=limit)
+        if scheduled:
+            hint = (
+                f"档案已超过存储上限 {limit} 字（当前 {chars} 字），已触发后台自动压缩。"
+                "压缩期间请勿整条重写该档案；稍后用 read_archive 查看压缩结果。"
+            )
+        else:
+            hint = (
+                f"档案已超过存储上限 {limit} 字（当前 {chars} 字），后台自动压缩暂未调度"
+                "（AI 不可用或处于冷却中）。原文已完整保留，下次写入会自动重试。"
+            )
+        self._logger.warning(
+            "档案超过存储上限，已保留原内容并等待压缩",
+            table_name=table_name,
+            key=key,
+            chars=chars,
+            max_total_chars=limit,
+            compression_scheduled=scheduled,
+        )
+        return ArchiveWriteOutcome(
+            item=item,
+            over_limit=True,
+            action="summarize",
+            scheduled=scheduled,
+            chars=chars,
+            max_total_chars=limit,
+            hint=hint,
+        )
+
+    async def delete(self, table_name: str, key: str) -> bool:
+        async with self._uow_factory() as uow:
+            deleted = await uow.archive.delete(table_name, key)
+            if deleted:
+                await uow.commit()
+        self._logger.debug("存档记忆已删除", table_name=table_name, key=key, deleted=deleted)
+        return deleted
+
+    # ── 乐观锁与观测能力（面板） ────────────────────────────────────
+
+    async def set_if_version(
+        self,
+        table_name: str,
+        key: str,
+        value: str,
+        tags: list[str],
+        expected_version: int,
+    ) -> ArchiveMemory:
+        """带乐观锁的写入：version 不一致时抛 ArchiveVersionConflictError（面板 409）。
+
+        注意这里不做容量治理判定：面板是运维兜底入口，管理员必须能写入并看到
+        超限提示，而不是被上限拦在门外（真正超限的档案应通过压缩回收）。
+        """
+        limit = self._max_total_chars
+        chars = len(value or "")
+        if limit > 0 and chars > limit and table_name not in self._exempt_tables:
+            # 面板是运维兜底入口：必须能写入并看到超限，而不是被上限拦在门外；
+            # 这里只记录 WARNING，让超限档案仍能被 list_over_limit 枚举出来。
+            self._logger.warning(
+                "面板写入的档案超过存储上限（面板路径不拦截，仅记录）",
+                table_name=table_name,
+                key=key,
+                chars=chars,
+                max_total_chars=limit,
+            )
+        async with self._uow_factory() as uow:
+            setter = getattr(uow.archive, "set_if_version", None)
+            if setter is None:
+                # 默认内存实现（neobot_memory.defaults）没有乐观锁：退化成先查后写。
+                # 仅在单进程开发/测试路径上使用，真正的并发保护在 SqlAlchemy 仓库里。
+                item = await self._set_if_version_fallback(
+                    uow, table_name, key, value, tags, expected_version
+                )
+            else:
+                try:
+                    item = await setter(table_name, key, value, tags, expected_version)
+                except NeoBotError as exc:
+                    # 仓库层的冲突异常带 table/key/expected/actual，翻译时原样保留，
+                    # 面板据此能直接渲染「已被他人修改（当前 version=N）」。
+                    raise ArchiveVersionConflictError(
+                        str(exc),
+                        table_name=str(getattr(exc, "table_name", "") or table_name),
+                        key=str(getattr(exc, "key", "") or key),
+                        expected_version=int(getattr(exc, "expected_version", 0) or 0),
+                        actual_version=int(getattr(exc, "actual_version", 0) or 0),
+                    ) from exc
+            await uow.commit()
+        self._logger.debug(
+            "存档记忆乐观锁写入",
+            table_name=table_name,
+            key=key,
+            version=item.version,
+        )
+        return item
+
+    async def _set_if_version_fallback(
+        self,
+        uow: Any,
+        table_name: str,
+        key: str,
+        value: str,
+        tags: list[str],
+        expected_version: int,
+    ) -> ArchiveMemory:
+        """无原生乐观锁的存储实现：先查后写（有 TOCTOU 窗口，仅开发路径）。"""
+        current = await uow.archive.get(table_name, key)
+        actual = int(getattr(current, "version", 0) or 0) if current is not None else 0
+        try:
+            expected = int(expected_version)
+        except (TypeError, ValueError):
+            expected = 0
+        if actual != expected:
+            raise ArchiveVersionConflictError(
+                f"档案已被其他写入修改: {table_name}:{key}",
+                table_name=table_name,
+                key=key,
+                expected_version=expected,
+                actual_version=actual,
+            )
+        return await uow.archive.set(table_name, key, value, tags)
+
+    async def list_table_names(self) -> list[str]:
+        """库内实际存在哪些档案表（面板表清单；不依赖静态常量）。"""
+        async with self._uow_factory() as uow:
+            lister = getattr(uow.archive, "list_table_names", None)
+            if lister is None:
+                self._logger.warning("当前档案存储实现不支持枚举表名，返回空清单")
+                return []
+            names = await lister()
+        return [str(name) for name in names]
+
+    async def table_stats(self) -> list[dict[str, Any]]:
+        """每张档案表的条目数与最大 value 字符数。"""
+        async with self._uow_factory() as uow:
+            stats = getattr(uow.archive, "table_stats", None)
+            if stats is None:
+                self._logger.warning("当前档案存储实现不支持表统计，返回空清单")
+                return []
+            rows = await stats()
+        return [dict(row) for row in rows]
+
+    async def count_over_limit(self, table_name: Optional[str] = None) -> int:
+        """当前超过存储上限的档案条目数（上限禁用时为 0）。"""
+        limit = self._max_total_chars
+        if limit <= 0:
+            return 0
+        async with self._uow_factory() as uow:
+            counter = getattr(uow.archive, "count_over_limit", None)
+            if counter is None:
+                return 0
+            total = await counter(
+                limit,
+                table_name=table_name,
+                exclude_tables=tuple(sorted(self._exempt_tables)),
+            )
+        return int(total or 0)
+
+    async def list_over_limit(
+        self,
+        table_name: Optional[str] = None,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        """枚举「当前超过存储上限」的档案（A7 可观测，供面板直接返回 JSON）。
+
+        返回字段：table_name / key / chars / version / updated_at（ISO8601）/ preview。
+        内部豁免表（memory_counter 等）永远不出现在这里——它们天然超限，列出来只会
+        把真正的超标档案淹没。
+        """
+        max_chars = self._max_total_chars
+        if max_chars <= 0:
+            return []
+        page_size = max(0, min(int(limit), _MAX_OVER_LIMIT_PAGE_SIZE))
+        async with self._uow_factory() as uow:
+            lister = getattr(uow.archive, "list_over_limit", None)
+            if lister is None:
+                self._logger.warning("当前档案存储实现不支持超限清单，返回空清单")
+                return []
+            items = await lister(
+                max_chars,
+                table_name=table_name,
+                exclude_tables=tuple(sorted(self._exempt_tables)),
+                limit=page_size,
+                offset=max(offset, 0),
+            )
+        return [self._over_limit_entry(item, max_chars=max_chars) for item in items]
+
+    @staticmethod
+    def _over_limit_entry(item: ArchiveMemory, *, max_chars: int) -> dict[str, Any]:
+        value = item.value or ""
+        updated_at = item.updated_at
+        return {
+            "table_name": item.table_name,
+            "key": item.key,
+            "chars": len(value),
+            "version": item.version,
+            "updated_at": updated_at.isoformat() if updated_at is not None else None,
+            "max_total_chars": max_chars,
+            "preview": value[:_OVER_LIMIT_PREVIEW_CHARS],
+        }
+
+    # ── 压缩前快照（spec(4) Part C / D15） ──────────────────────────
+
+    @staticmethod
+    def _snapshot_access(uow: Any) -> Any:
+        """取快照访问层；旧实现 / 测试替身没有它时返回 None（快照降级为不落盘）。"""
+        return getattr(uow, "archive_snapshots", None)
+
+    async def save_snapshot(
+        self,
+        table_name: str,
+        key: str,
+        value: str,
+        *,
+        total_chars: Optional[int] = None,
+        version: int = 0,
+        reason: str = "manual",
+        operator_ip: Optional[str] = None,
+    ) -> Optional[int]:
+        """写入一份压缩前快照并执行保留策略，返回快照 id（存储不支持时为 None）。
+
+        写入时机由调用方保证：**压缩开始前**、拿到 chars_before 之后。
+        失败 / 未达标时调用方必须用 ``delete_snapshot`` 删掉本次快照。
+        """
+        text = str(value or "")
+        chars = int(total_chars) if total_chars is not None else len(text)
+        async with self._uow_factory() as uow:
+            access = self._snapshot_access(uow)
+            if access is None:
+                self._logger.warning(
+                    "当前档案存储实现不支持压缩快照，本次压缩不留痕",
+                    table_name=table_name,
+                    key=key,
+                )
+                return None
+            row = await access.add(
+                table_name,
+                key,
+                text,
+                total_chars=chars,
+                version=int(version or 0),
+                reason=str(reason or "manual"),
+                operator_ip=operator_ip,
+            )
+            pruned = await access.prune(
+                table_name,
+                key,
+                keep=MAX_ARCHIVE_SNAPSHOTS_PER_KEY,
+                max_total=MAX_ARCHIVE_SNAPSHOTS,
+            )
+            await uow.commit()
+        snapshot_id = int(row.get("id") or 0)
+        self._logger.debug(
+            "压缩前快照已保存",
+            table_name=table_name,
+            key=key,
+            total_chars=chars,
+            reason=str(reason or "manual"),
+            snapshot_id=snapshot_id,
+            pruned=int(pruned or 0),
+        )
+        return snapshot_id or None
+
+    async def list_snapshots(
+        self,
+        table_name: str,
+        key: str,
+        *,
+        limit: int = MAX_ARCHIVE_SNAPSHOTS_PER_KEY,
+        include_value: bool = False,
+    ) -> list[dict[str, Any]]:
+        """列出某条档案最近若干份快照（默认不含全文，避免大档案塞爆响应）。"""
+        page = max(0, min(int(limit), MAX_ARCHIVE_SNAPSHOTS_PER_KEY))
+        async with self._uow_factory() as uow:
+            access = self._snapshot_access(uow)
+            if access is None:
+                return []
+            rows = await access.list(
+                table_name, key, limit=page, include_value=include_value
+            )
+        return [self._snapshot_entry(row) for row in rows]
+
+    async def get_snapshot(self, snapshot_id: int) -> Optional[dict[str, Any]]:
+        """读取某一份快照全文（面板「查看某份快照」）。"""
+        async with self._uow_factory() as uow:
+            access = self._snapshot_access(uow)
+            if access is None:
+                return None
+            row = await access.get(int(snapshot_id))
+        if row is None:
+            return None
+        entry = self._snapshot_entry(row, include_value=True)
+        entry["value"] = str(row.get("value") or "")
+        return entry
+
+    async def delete_snapshot(self, snapshot_id: Optional[int]) -> bool:
+        """删除一份快照（压缩失败 / 未达标时回滚本次留痕）。"""
+        if not snapshot_id:
+            return False
+        async with self._uow_factory() as uow:
+            access = self._snapshot_access(uow)
+            if access is None:
+                return False
+            deleted = await access.delete(int(snapshot_id))
+            if deleted:
+                await uow.commit()
+        return bool(deleted)
+
+    async def prune_snapshots(
+        self, table_name: Optional[str] = None, key: Optional[str] = None
+    ) -> int:
+        """按保留策略清理快照：给了 (table_name, key) 时同时做单键与全局两级。"""
+        async with self._uow_factory() as uow:
+            access = self._snapshot_access(uow)
+            if access is None:
+                return 0
+            removed = await access.prune(
+                table_name,
+                key,
+                keep=MAX_ARCHIVE_SNAPSHOTS_PER_KEY,
+                max_total=MAX_ARCHIVE_SNAPSHOTS,
+            )
+            if removed:
+                await uow.commit()
+        return int(removed or 0)
+
+    @staticmethod
+    def _snapshot_entry(row: dict[str, Any], *, include_value: bool = False) -> dict[str, Any]:
+        """把仓库行投影成面板 / 工具可序列化的字典（时间转 ISO8601）。"""
+        created_at = row.get("created_at")
+        isoformat = getattr(created_at, "isoformat", None)
+        entry: dict[str, Any] = {
+            "id": int(row.get("id") or 0),
+            "table_name": str(row.get("table_name") or ""),
+            "key": str(row.get("key") or ""),
+            "total_chars": int(row.get("total_chars") or 0),
+            "version": int(row.get("version") or 0),
+            "reason": str(row.get("reason") or ""),
+            "operator_ip": row.get("operator_ip"),
+            "created_at": str(isoformat()) if callable(isoformat) else "",
+        }
+        if include_value:
+            entry["value"] = str(row.get("value") or "")
+        return entry
+
+    # ── 超限压缩调度 ────────────────────────────────────────────────
+
+    def _in_overflow_cooldown(self, table_name: str, key: str) -> bool:
+        until = self._overflow_cooldown_until.get((table_name, key), 0.0)
+        return until > 0.0 and time.monotonic() < until
+
+    def _schedule_overflow_compression(
+        self, table_name: str, key: str, *, chars: int, limit: int
+    ) -> bool:
+        """触发一次异步压缩；返回是否真的调度成功。
+
+        冷却与单飞：冷却在这里判（同一 key 在 overflow_summary_cooldown_seconds
+        内不重复触发），单飞由触发方持有（同一 (table, key) 同时只跑一个压缩任务）。
+        触发方返回 False（AI 不可用 / 正在压缩 / 处于失败退避）时不写冷却，
+        这样「下次写入再试」才不会被一次失败锁死 600 秒。
+        """
+        if self._in_overflow_cooldown(table_name, key):
+            self._logger.debug(
+                "档案超过存储上限，但仍在压缩冷却期内，跳过本次触发",
+                table_name=table_name,
+                key=key,
+            )
+            return False
+        trigger = self._overflow_trigger
+        if trigger is None:
+            self._logger.warning(
+                "档案超过存储上限但没有可用的自动压缩入口，仅保留原内容",
+                table_name=table_name,
+                key=key,
+                chars=chars,
+                max_total_chars=limit,
+            )
+            return False
+        try:
+            scheduled = bool(trigger(table_name, key))
+        except Exception as exc:
+            self._logger.warning(
+                "档案超过存储上限，触发自动压缩失败",
+                table_name=table_name,
+                key=key,
+                error=str(exc) or type(exc).__name__,
+            )
+            return False
+        if scheduled:
+            self._overflow_cooldown_until[(table_name, key)] = (
+                time.monotonic() + self._overflow_cooldown_seconds
+            )
+        return scheduled

neobot_memory-1.0.0/src/neobot_memory/defaults.py

@@ -0,0 +1,264 @@
+"""Defaults — 开箱即用的默认实现"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from neobot_contracts.models import ConversationRef, MemoryRecord
+from neobot_contracts.models.memory import ArchiveMemory, ImageAnalysis
+from neobot_contracts.ports.archive_memory_access import ArchiveMemoryAccess
+from neobot_contracts.time_context import now_utc
+from neobot_contracts.ports.image_analysis_access import ImageAnalysisAccess
+from neobot_contracts.ports.clock import SystemClock as SystemClock  # re-export
+from neobot_contracts.ports.logging import NullLogger as NullLogger  # re-export
+
+
+class InMemoryMemoryRepository:
+    """纯内存记忆存储，用于测试或独立运行"""
+
+    def __init__(self) -> None:
+        self._records: list[MemoryRecord] = []
+
+    async def save(self, record: MemoryRecord) -> None:
+        self._records.append(record)
+
+    async def search(
+        self, conversation: ConversationRef, query: str, limit: int = 5
+    ) -> list[MemoryRecord]:
+        matches = [
+            r for r in self._records
+            if r.conversation == conversation and query.lower() in r.content.lower()
+        ]
+        return matches[-limit:]
+
+
+class InMemoryArchiveMemoryAccess:
+    """内存档案式记忆存储，用于测试或独立运行"""
+
+    def __init__(self) -> None:
+        self._storage: dict[tuple[str, str], ArchiveMemory] = {}
+        self._id_counter = 0
+
+    async def get(self, table_name: str, key: str) -> Optional[ArchiveMemory]:
+        """根据表名和键名获取档案式记忆条目"""
+        entry = self._storage.get((table_name, key))
+        if entry is None:
+            return None
+        return self._clone(entry)
+
+    async def set(
+        self,
+        table_name: str,
+        key: str,
+        value: str,
+        tags: list[str],
+    ) -> ArchiveMemory:
+        """创建或更新档案式记忆条目"""
+        entry_key = (table_name, key)
+
+        if entry_key in self._storage:
+            # 更新现有条目
+            existing = self._storage[entry_key]
+            updated = ArchiveMemory(
+                id=existing.id,
+                table_name=table_name,
+                key=key,
+                value=value,
+                tags=tags.copy(),  # 创建副本避免外部修改
+                created_at=existing.created_at,  # 保留原始创建时间
+                updated_at=now_utc(),
+                version=existing.version + 1,
+            )
+        else:
+            # 创建新条目
+            self._id_counter += 1
+            now = now_utc()
+            updated = ArchiveMemory(
+                id=self._id_counter,
+                table_name=table_name,
+                key=key,
+                value=value,
+                tags=tags.copy(),
+                created_at=now,
+                updated_at=now,
+                version=1,
+            )
+
+        self._storage[entry_key] = self._clone(updated)
+        return self._clone(updated)
+
+    async def delete(self, table_name: str, key: str) -> bool:
+        """删除档案式记忆条目"""
+        entry_key = (table_name, key)
+        if entry_key in self._storage:
+            del self._storage[entry_key]
+            return True
+        return False
+
+    async def exists(self, table_name: str, key: str) -> bool:
+        """检查档案式记忆条目是否存在"""
+        return (table_name, key) in self._storage
+
+    async def list(
+        self,
+        table_name: str,
+        *,
+        tags: Optional[list[str]] = None,
+        key_query: Optional[str] = None,
+        value_query: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ArchiveMemory]:
+        """列出符合条件的档案式记忆条目"""
+        rows = [
+            self._clone(entry)
+            for (stored_table_name, _), entry in self._storage.items()
+            if stored_table_name == table_name
+        ]
+
+        if tags:
+            rows = [row for row in rows if all(tag in row.tags for tag in tags)]
+        if key_query:
+            lowered_key_query = key_query.lower()
+            rows = [row for row in rows if lowered_key_query in row.key.lower()]
+        if value_query:
+            lowered_value_query = value_query.lower()
+            rows = [row for row in rows if lowered_value_query in row.value.lower()]
+
+        rows.sort(key=lambda row: (row.updated_at, row.id), reverse=True)
+        return rows[offset : offset + limit]
+
+    # Type check: ensure class implements the protocol
+    def __init_subclass__(cls) -> None:
+        super().__init_subclass__()
+        # Verify that this class implements the ArchiveMemoryAccess protocol
+        if not issubclass(cls, ArchiveMemoryAccess):  # type: ignore
+            raise TypeError(f"{cls.__name__} does not implement ArchiveMemoryAccess protocol")
+
+    @staticmethod
+    def _clone(entry: ArchiveMemory) -> ArchiveMemory:
+        return ArchiveMemory(
+            id=entry.id,
+            table_name=entry.table_name,
+            key=entry.key,
+            value=entry.value,
+            tags=entry.tags.copy(),
+            created_at=entry.created_at,
+            updated_at=entry.updated_at,
+            version=entry.version,
+        )
+
+
+class InMemoryImageAnalysisAccess:
+    """In-memory image analysis cache for tests and standalone runs."""
+
+    def __init__(self) -> None:
+        self._storage: dict[str, ImageAnalysis] = {}
+        self._id_counter = 0
+
+    async def get(self, file_hash: str) -> Optional[ImageAnalysis]:
+        entry = self._storage.get(file_hash)
+        if entry is None:
+            return None
+        return self._clone(entry)
+
+    async def set(
+        self,
+        file_hash: str,
+        *,
+        source: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        original_width: Optional[int] = None,
+        original_height: Optional[int] = None,
+        processed_width: Optional[int] = None,
+        processed_height: Optional[int] = None,
+        analysis_text: Optional[str] = None,
+    ) -> ImageAnalysis:
+        if file_hash in self._storage:
+            existing = self._storage[file_hash]
+            updated = ImageAnalysis(
+                id=existing.id,
+                file_hash=file_hash,
+                source=source if source is not None else existing.source,
+                mime_type=mime_type if mime_type is not None else existing.mime_type,
+                original_width=original_width if original_width is not None else existing.original_width,
+                original_height=original_height if original_height is not None else existing.original_height,
+                processed_width=processed_width if processed_width is not None else existing.processed_width,
+                processed_height=processed_height if processed_height is not None else existing.processed_height,
+                analysis_text=analysis_text if analysis_text is not None else existing.analysis_text,
+                created_at=existing.created_at,
+                updated_at=now_utc(),
+                version=existing.version + 1,
+            )
+        else:
+            self._id_counter += 1
+            now = now_utc()
+            updated = ImageAnalysis(
+                id=self._id_counter,
+                file_hash=file_hash,
+                source=source,
+                mime_type=mime_type,
+                original_width=original_width,
+                original_height=original_height,
+                processed_width=processed_width,
+                processed_height=processed_height,
+                analysis_text=analysis_text,
+                created_at=now,
+                updated_at=now,
+                version=1,
+            )
+
+        self._storage[file_hash] = self._clone(updated)
+        return self._clone(updated)
+
+    async def delete(self, file_hash: str) -> bool:
+        if file_hash in self._storage:
+            del self._storage[file_hash]
+            return True
+        return False
+
+    async def exists(self, file_hash: str) -> bool:
+        return file_hash in self._storage
+
+    async def list(
+        self,
+        *,
+        source_query: Optional[str] = None,
+        has_analysis_text: Optional[bool] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ImageAnalysis]:
+        rows = [self._clone(entry) for entry in self._storage.values()]
+
+        if source_query:
+            lowered = source_query.lower()
+            rows = [row for row in rows if row.source and lowered in row.source.lower()]
+        if has_analysis_text is True:
+            rows = [row for row in rows if row.analysis_text]
+        elif has_analysis_text is False:
+            rows = [row for row in rows if not row.analysis_text]
+
+        rows.sort(key=lambda row: (row.updated_at, row.id), reverse=True)
+        return rows[offset : offset + limit]
+
+    def __init_subclass__(cls) -> None:
+        super().__init_subclass__()
+        if not issubclass(cls, ImageAnalysisAccess):  # type: ignore[arg-type]
+            raise TypeError(f"{cls.__name__} does not implement ImageAnalysisAccess protocol")
+
+    @staticmethod
+    def _clone(entry: ImageAnalysis) -> ImageAnalysis:
+        return ImageAnalysis(
+            id=entry.id,
+            file_hash=entry.file_hash,
+            source=entry.source,
+            mime_type=entry.mime_type,
+            original_width=entry.original_width,
+            original_height=entry.original_height,
+            processed_width=entry.processed_width,
+            processed_height=entry.processed_height,
+            analysis_text=entry.analysis_text,
+            created_at=entry.created_at,
+            updated_at=entry.updated_at,
+            version=entry.version,
+        )

neobot_memory-1.0.0/src/neobot_memory/image_service.py

@@ -0,0 +1,92 @@
+"""图片分析缓存服务。"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from neobot_contracts.models.memory import ImageAnalysis
+from neobot_contracts.ports.logging import Logger
+from neobot_contracts.ports.unit_of_work import UnitOfWorkFactory
+
+
+class ImageAnalysisService:
+    """图片分析结果的缓存 CRUD 与查询服务。"""
+
+    def __init__(self, uow_factory: UnitOfWorkFactory, logger: Logger) -> None:
+        self._uow_factory = uow_factory
+        self._logger = logger
+
+    async def get(self, file_hash: str) -> Optional[ImageAnalysis]:
+        async with self._uow_factory() as uow:
+            item = await uow.images.get(file_hash)
+        self._logger.debug("图像分析已获取", file_hash=file_hash, found=item is not None)
+        return item
+
+    async def exists(self, file_hash: str) -> bool:
+        async with self._uow_factory() as uow:
+            exists = await uow.images.exists(file_hash)
+        self._logger.debug("图像分析存在检查", file_hash=file_hash, exists=exists)
+        return exists
+
+    async def list(
+        self,
+        *,
+        source_query: Optional[str] = None,
+        has_analysis_text: Optional[bool] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ImageAnalysis]:
+        async with self._uow_factory() as uow:
+            items = await uow.images.list(
+                source_query=source_query,
+                has_analysis_text=has_analysis_text,
+                limit=limit,
+                offset=offset,
+            )
+        self._logger.debug(
+            "图像分析列表已获取",
+            count=len(items),
+            limit=limit,
+            offset=offset,
+            has_analysis_text=has_analysis_text,
+        )
+        return items
+
+    async def set(
+        self,
+        file_hash: str,
+        *,
+        source: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        original_width: Optional[int] = None,
+        original_height: Optional[int] = None,
+        processed_width: Optional[int] = None,
+        processed_height: Optional[int] = None,
+        analysis_text: Optional[str] = None,
+    ) -> ImageAnalysis:
+        async with self._uow_factory() as uow:
+            item = await uow.images.set(
+                file_hash,
+                source=source,
+                mime_type=mime_type,
+                original_width=original_width,
+                original_height=original_height,
+                processed_width=processed_width,
+                processed_height=processed_height,
+                analysis_text=analysis_text,
+            )
+            await uow.commit()
+        self._logger.debug(
+            "图像分析已保存",
+            file_hash=file_hash,
+            version=item.version,
+        )
+        return item
+
+    async def delete(self, file_hash: str) -> bool:
+        async with self._uow_factory() as uow:
+            deleted = await uow.images.delete(file_hash)
+            if deleted:
+                await uow.commit()
+        self._logger.debug("图像分析已删除", file_hash=file_hash, deleted=deleted)
+        return deleted

neobot_memory-1.0.0/src/neobot_memory/reader.py

@@ -0,0 +1,13 @@
+"""MemoryReader Protocol — 记忆读取抽象"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class MemoryReader(Protocol):
+    """记忆读取接口，MemoryService 结构性满足此接口"""
+
+    async def recall(
+        self, conversation_id: str, query: str, limit: int = 5
+    ) -> list[str]: ...

neobot_memory-1.0.0/src/neobot_memory/service.py

@@ -0,0 +1,46 @@
+"""MemoryService — 记忆读写服务"""
+
+from __future__ import annotations
+
+from neobot_contracts.models import ConversationRef, MemoryRecord
+from neobot_contracts.ports.clock import Clock
+from neobot_contracts.ports.logging import Logger
+from neobot_contracts.ports.repository import MemoryRepository
+
+
+class MemoryService:
+    """记忆服务，负责存储和检索记忆条目"""
+
+    def __init__(
+        self,
+        repository: MemoryRepository,
+        logger: Logger,
+        clock: Clock,
+    ) -> None:
+        self._repository = repository
+        self._logger = logger
+        self._clock = clock
+
+    async def remember(
+        self, conversation_id: str, speaker_id: str, content: str
+    ) -> None:
+        record = MemoryRecord(
+            conversation=ConversationRef(kind="private", id=conversation_id),
+            speaker_id=speaker_id,
+            content=content,
+            created_at=self._clock.now(),
+        )
+        await self._repository.save(record)
+        self._logger.debug("短期记忆已保存", conversation_id=conversation_id, speaker_id=speaker_id)
+
+    async def recall(
+        self, conversation_id: str, query: str, limit: int = 5
+    ) -> list[str]:
+        ref = ConversationRef(kind="private", id=conversation_id)
+        records = await self._repository.search(ref, query, limit)
+        self._logger.debug(
+            "记忆已检索",
+            conversation_id=conversation_id,
+            count=len(records),
+        )
+        return [r.content for r in records]