agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/memory/models.py

@@ -19,7 +19,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Literal
+from typing import Any, Literal, Mapping
 
 __all__ = [
     "LongTermMemoryRecord",
@@ -195,6 +195,50 @@ SensitiveLabel = Literal[
     "binary",
     "none",
 ]
+#: 敏感级别（长任务方案 §7.2）：none=可跨作用域；low=限同作用域；high=禁止入长期 Memory。
+SensitivityLevel = Literal["none", "low", "high"]
+#: 写策略（长任务方案 §7.2）：auto=管线自动提交；user_confirm=需用户确认；locked=只读。
+WritePolicy = Literal["auto", "user_confirm", "locked"]
+MemoryArtifactModality = Literal[
+    "text", "image", "audio", "video", "document", "binary"
+]
+
+
+@dataclass(frozen=True)
+class MemoryArtifactRef:
+    """长期记忆引用的多模态 Artifact 元数据。
+
+    这里只保存可审计的引用与内容指纹，绝不保存 base64、文件字节或签名下载
+    URL。真正的内容仍由 Artifact Store 按权限读取，默认不会进入 Prompt。
+    """
+
+    uri: str
+    mime_type: str
+    content_hash: str
+    size_bytes: int
+    modality: MemoryArtifactModality = "binary"
+
+    def __post_init__(self) -> None:
+        if not self.uri.startswith("artifact://"):
+            raise ValueError("Memory Artifact 必须使用 artifact:// 稳定引用")
+        if not self.mime_type or "/" not in self.mime_type:
+            raise ValueError("Memory Artifact 必须声明合法 MIME type")
+        if not self.content_hash or len(self.content_hash) < 16:
+            raise ValueError("Memory Artifact 必须携带内容哈希")
+        if self.size_bytes < 0:
+            raise ValueError("Memory Artifact size_bytes 不能为负数")
+
+    @classmethod
+    def from_value(cls, value: MemoryArtifactRef | Mapping[str, Any]) -> MemoryArtifactRef:
+        if isinstance(value, cls):
+            return value
+        return cls(
+            uri=str(value.get("uri") or ""),
+            mime_type=str(value.get("mime_type") or ""),
+            content_hash=str(value.get("content_hash") or ""),
+            size_bytes=int(value.get("size_bytes") or 0),
+            modality=str(value.get("modality") or "binary"),  # type: ignore[arg-type]
+        )
 
 
 @dataclass(frozen=True)
@@ -222,6 +266,21 @@ class MemoryRecord:
     metadata: dict[str, Any] = field(default_factory=dict)
     created_at: str = ""
     updated_at: str = ""
+    # ---- 长任务方案 §7.2 兼容扩展（全部带默认值，additive） ----
+    #: 来源 Artifact 引用（大 Tool Result / 摘要正文不进正文，只留引用）。
+    source_artifact_refs: tuple[str, ...] = field(default=())
+    #: 多模态来源的结构化元数据。只含稳定引用，不含媒体正文或临时下载 URL。
+    source_artifacts: tuple[MemoryArtifactRef, ...] = field(default=())
+    #: 敏感级别：high 禁止入长期 Memory（须先脱敏）；low 限同作用域。
+    sensitivity: SensitivityLevel = "none"
+    #: 写策略：locked 记录只能显式解锁后更新；user_confirm 需用户确认。
+    write_policy: WritePolicy = "auto"
+    #: 本记录 supersede 的旧记录（审计链）。
+    supersedes: tuple[str, ...] = field(default=())
+
+    def __post_init__(self) -> None:
+        normalized = tuple(MemoryArtifactRef.from_value(item) for item in self.source_artifacts)
+        object.__setattr__(self, "source_artifacts", normalized)
 
     def is_active_now(self, *, now_iso: str = "") -> bool:
         if self.status != "active":
@@ -248,6 +307,17 @@ class MemoryCandidate:
     sensitive_labels: list[SensitiveLabel] = field(default_factory=list)
     reason: str = ""
     slot_key: str = ""
+    # ---- 长任务方案 §7.2 兼容扩展（additive） ----
+    source_artifact_refs: tuple[str, ...] = field(default=())
+    source_artifacts: tuple[MemoryArtifactRef, ...] = field(default=())
+    sensitivity: SensitivityLevel = "none"
+    write_policy: WritePolicy = "auto"
+    #: TTL（ISO 日期字符串；空 = 不过期）。时效数据必须有来源和 TTL（§7.3）。
+    expires_at: str = ""
+
+    def __post_init__(self) -> None:
+        normalized = tuple(MemoryArtifactRef.from_value(item) for item in self.source_artifacts)
+        object.__setattr__(self, "source_artifacts", normalized)
 
     def is_hard_rejected(self) -> bool:
         return any(label != "none" for label in self.sensitive_labels)
@@ -274,6 +344,12 @@ class MemorySearchResult:
     latency_ms: int
     accounting_accuracy: str
     truncated_by_budget: bool = False
+    #: Harness-side retrieval projection. Additive fields keep Provider contracts
+    #: stable while making semantic fallback visible to Studio/observability.
+    retrieval_strategy: str = "provider"
+    reranker_status: str = "not_configured"
+    semantic_scorer_status: str = "not_configured"
+    dedicated_reranker_status: str = "not_configured"
 
 
 @dataclass(frozen=True)

ksadk/memory/provider_resolver.py

@@ -63,6 +63,11 @@ def resolve_memory_provider(provider_ref: str) -> MemoryProviderLike:
 
         return LongTermMemoryService.from_env()
 
+    if ref in ("local-postgres", "postgres"):
+        from ksadk.memory.providers.local_postgres import PostgresMemoryProvider
+
+        return PostgresMemoryProvider()
+
     # 默认：持久 SQLite（local-default / local-sqlite / 未知 ref）
     from ksadk.memory.providers.local_sqlite import (
         resolve_default_memory_provider,

ksadk/memory/providers/local_postgres.py

@@ -0,0 +1,200 @@
+"""Postgres 长期记忆 Provider（分布式后端，plan §9 / 方案 P1）。
+
+实现与 :class:`SqliteMemoryProvider` 相同的 MemoryProvider Protocol，
+但用 psycopg 连接 Postgres，支持多副本共享。
+
+依赖：``ksadk[postgres]`` extra（psycopg[binary]）。缺依赖时显式报错。
+
+配置：``KSADK_MEMORY_PROVIDER=local-postgres`` + ``KSADK_MEMORY_POSTGRES_DSN``
+或 ``KSADK_CHECKPOINT_DSN``（复用同一连接串）。
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Any
+
+from ksadk.memory.models import (
+    CoreMemoryRequest,
+    MemoryCapabilities,
+    MemoryDeleteRequest,
+    MemoryDeleteResult,
+    MemoryRecord,
+    MemorySearchRequest,
+    MemorySearchResult,
+)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS memory_records (
+    memory_id TEXT PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    workspace_id TEXT NOT NULL,
+    scope TEXT NOT NULL,
+    scope_id TEXT NOT NULL,
+    memory_type TEXT NOT NULL DEFAULT 'fact',
+    content TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1,
+    status TEXT NOT NULL DEFAULT 'active',
+    source_event_ids TEXT NOT NULL DEFAULT '[]',
+    sensitive_labels TEXT NOT NULL DEFAULT '[]',
+    confidence REAL NOT NULL DEFAULT 0.8,
+    importance REAL NOT NULL DEFAULT 0.6,
+    created_at REAL NOT NULL,
+    updated_at REAL NOT NULL,
+    expires_at REAL
+);
+CREATE INDEX IF NOT EXISTS idx_memory_scope
+ON memory_records (tenant_id, workspace_id, scope, scope_id);
+CREATE INDEX IF NOT EXISTS idx_memory_status
+ON memory_records (tenant_id, workspace_id, status);
+"""
+
+
+class PostgresMemoryProvider:
+    """Postgres 长期记忆 Provider（多副本共享，实现 MemoryProviderLike Protocol）。
+
+    与 :class:`SqliteMemoryProvider` 接口一致，但用 Postgres 连接。
+    线程安全：单连接 + per-thread lock（与 SQLite 版相同策略）。
+    ``last_error`` 供 Coordinator 区分"吞错返空"与"真无记忆"。
+    """
+
+    capabilities_def = MemoryCapabilities(
+        semantic_search=False,
+        keyword_search=True,
+        metadata_filter=True,
+        versioned_update=True,
+        hard_delete=True,
+        ttl=True,
+        max_record_chars=8192,
+    )
+
+    def __init__(
+        self,
+        *,
+        dsn: str | None = None,
+        tenant_id: str = "local",
+        workspace_id: str = "local",
+    ) -> None:
+        self._dsn = (
+            dsn
+            or os.getenv("KSADK_MEMORY_POSTGRES_DSN")
+            or os.getenv("KSADK_CHECKPOINT_DSN", "")
+        )
+        if not self._dsn:
+            raise RuntimeError(
+                "PostgresMemoryProvider 需要 DSN"
+                "（KSADK_MEMORY_POSTGRES_DSN 或 KSADK_CHECKPOINT_DSN）"
+            )
+        try:
+            import psycopg  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise RuntimeError(
+                "PostgresMemoryProvider 需要"
+                " ksadk[postgres] extra（psycopg[binary]）"
+            ) from exc
+        self._psycopg = psycopg
+        self._tenant_id = tenant_id
+        self._workspace_id = workspace_id
+        self._lock = threading.Lock()
+        self._conn = psycopg.connect(self._dsn, autocommit=True)
+        self._conn.execute(_SCHEMA)
+        self.last_error: str = ""
+
+    # ---- MemoryProvider Protocol ----
+
+    def capabilities(self) -> MemoryCapabilities:
+        return self.capabilities_def
+
+    def search(self, request: MemorySearchRequest) -> MemorySearchResult:
+        start = time.monotonic()
+        try:
+            with self._lock:
+                query = request.query.strip()
+                if not query:
+                    return MemorySearchResult(
+                        records=[],
+                        elapsed_ms=int((time.monotonic() - start) * 1000),
+                    )
+                # keyword search (ILIKE, Postgres 大小写不敏感)
+                pattern = f"%{query}%"
+                rows = self._conn.execute(
+                    """SELECT * FROM memory_records
+                       WHERE tenant_id = %s AND workspace_id = %s
+                         AND status = 'active'
+                         AND (content ILIKE %s)
+                       ORDER BY importance DESC, updated_at DESC
+                       LIMIT %s""",
+                    (self._tenant_id, self._workspace_id, pattern, request.top_k),
+                ).fetchall()
+                records = [self._row_to_record(row) for row in rows]
+                return MemorySearchResult(
+                    records=records,
+                    elapsed_ms=int((time.monotonic() - start) * 1000),
+                )
+        except Exception as exc:  # noqa: BLE001 - 不阻断主对话
+            self.last_error = str(exc)
+            return MemorySearchResult(records=[], elapsed_ms=int((time.monotonic() - start) * 1000))
+
+    def list_core(self, request: CoreMemoryRequest) -> list[MemoryRecord]:
+        try:
+            with self._lock:
+                rows = self._conn.execute(
+                    """SELECT * FROM memory_records
+                       WHERE tenant_id = %s AND workspace_id = %s
+                         AND status = 'active'
+                       ORDER BY importance DESC, updated_at DESC
+                       LIMIT %s""",
+                    (self._tenant_id, self._workspace_id, request.max_blocks),
+                ).fetchall()
+                return [self._row_to_record(row) for row in rows]
+        except Exception as exc:  # noqa: BLE001
+            self.last_error = str(exc)
+            return []
+
+    def delete(self, request: MemoryDeleteRequest) -> MemoryDeleteResult:
+        try:
+            with self._lock:
+                self._conn.execute(
+                    "DELETE FROM memory_records WHERE memory_id = %s"
+                    " AND scope = %s AND scope_id = %s",
+                    (request.memory_id, request.scope, request.scope_id),
+                )
+            return MemoryDeleteResult(deleted=True)
+        except Exception as exc:  # noqa: BLE001
+            self.last_error = str(exc)
+            return MemoryDeleteResult(deleted=False)
+
+    def close(self) -> None:
+        with self._lock:
+            if self._conn:
+                self._conn.close()
+
+    # ---- helpers ----
+
+    def _row_to_record(self, row: Any) -> MemoryRecord:
+        # psycopg Row 可按列名访问
+        import json
+
+        return MemoryRecord(
+            memory_id=row["memory_id"],
+            tenant_id=row["tenant_id"],
+            workspace_id=row["workspace_id"],
+            scope=row["scope"],
+            scope_id=row["scope_id"],
+            memory_type=row["memory_type"],
+            content=row["content"],
+            version=row["version"],
+            status=row["status"],
+            source_event_ids=json.loads(row["source_event_ids"] or "[]"),
+            sensitive_labels=json.loads(row["sensitive_labels"] or "[]"),
+            confidence=row["confidence"],
+            importance=row["importance"],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            expires_at=row["expires_at"],
+        )
+
+
+__all__ = ["PostgresMemoryProvider"]

ksadk/memory/providers/local_sqlite.py

@@ -16,12 +16,14 @@ import re
 import sqlite3
 import threading
 import time
+from dataclasses import asdict
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any
 
 from ksadk.memory.models import (
     CoreMemoryRequest,
+    MemoryArtifactRef,
     MemoryCapabilities,
     MemoryDeleteRequest,
     MemoryDeleteResult,
@@ -82,6 +84,15 @@ def _row_to_record(row: sqlite3.Row) -> MemoryRecord:
         metadata=json.loads(row["metadata"] or "{}"),
         created_at=row["created_at"] or "",
         updated_at=row["updated_at"] or "",
+        # 长任务方案 §7.2 扩展列（additive migration）。
+        source_artifact_refs=tuple(json.loads(row["source_artifact_refs"] or "[]")),
+        source_artifacts=tuple(
+            MemoryArtifactRef.from_value(item)
+            for item in json.loads(row["source_artifacts"] or "[]")
+        ),
+        sensitivity=row["sensitivity"] or "none",
+        write_policy=row["write_policy"] or "auto",
+        supersedes=tuple(json.loads(row["supersedes"] or "[]")),
     )
 
 
@@ -115,6 +126,23 @@ CREATE INDEX IF NOT EXISTS idx_scope ON memory_records(tenant_id, workspace_id,
 CREATE INDEX IF NOT EXISTS idx_content_hash ON memory_records(content_hash);
 """
 
+#: 长任务方案 §7.2 扩展列（additive；老库经 ALTER TABLE 补列）。
+_EXTENSION_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("source_artifact_refs", "TEXT NOT NULL DEFAULT '[]'"),
+    ("source_artifacts", "TEXT NOT NULL DEFAULT '[]'"),
+    ("sensitivity", "TEXT NOT NULL DEFAULT 'none'"),
+    ("write_policy", "TEXT NOT NULL DEFAULT 'auto'"),
+    ("supersedes", "TEXT NOT NULL DEFAULT '[]'"),
+)
+
+
+def _migrate(conn: sqlite3.Connection) -> None:
+    """给老库补扩展列（SQLite 无 IF NOT EXISTS for ADD COLUMN，逐列试加）。"""
+    existing = {r["name"] for r in conn.execute("PRAGMA table_info(memory_records)")}
+    for column, decl in _EXTENSION_COLUMNS:
+        if column not in existing:
+            conn.execute(f"ALTER TABLE memory_records ADD COLUMN {column} {decl}")
+
 
 class SqliteMemoryProvider:
     """本地 SQLite 长期记忆 Provider。
@@ -154,6 +182,7 @@ class SqliteMemoryProvider:
         self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
         self._conn.row_factory = sqlite3.Row
         self._conn.executescript(_SCHEMA)
+        _migrate(self._conn)
         self._conn.commit()
         self.last_error: str = ""
         # 每次 Provider 启动执行一次有界清理；不在每次 recall/upsert 热路径扫描全表。
@@ -230,8 +259,9 @@ class SqliteMemoryProvider:
                     memory_id, tenant_id, workspace_id, scope, scope_id, memory_type,
                     content, summary, status, confidence, importance, valid_from, valid_to,
                     expires_at, source_session_id, source_event_ids, source_seq_range,
-                    content_hash, version, metadata, created_at, updated_at
-                ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+                    content_hash, version, metadata, created_at, updated_at,
+                    source_artifact_refs, source_artifacts, sensitivity, write_policy, supersedes
+                ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
                 ON CONFLICT(memory_id) DO UPDATE SET
                     content=excluded.content, summary=excluded.summary, status=excluded.status,
                     confidence=excluded.confidence, importance=excluded.importance,
@@ -239,7 +269,11 @@ class SqliteMemoryProvider:
                     expires_at=excluded.expires_at, source_event_ids=excluded.source_event_ids,
                     source_seq_range=excluded.source_seq_range, content_hash=excluded.content_hash,
                     version=excluded.version, metadata=excluded.metadata,
-                        updated_at=excluded.updated_at
+                        updated_at=excluded.updated_at,
+                        source_artifact_refs=excluded.source_artifact_refs,
+                        source_artifacts=excluded.source_artifacts,
+                        sensitivity=excluded.sensitivity, write_policy=excluded.write_policy,
+                        supersedes=excluded.supersedes
                 """,
                 (
                     record.memory_id,
@@ -264,6 +298,11 @@ class SqliteMemoryProvider:
                     json.dumps(record.metadata, ensure_ascii=False),
                     created,
                     now,
+                    json.dumps(list(record.source_artifact_refs)),
+                    json.dumps([asdict(item) for item in record.source_artifacts]),
+                    record.sensitivity,
+                    record.write_policy,
+                    json.dumps(list(record.supersedes)),
                 ),
             )
             self._conn.commit()

ksadk/memory/retrieval.py

@@ -0,0 +1,189 @@
+"""混合检索管线（长任务方案 §7.5 P2）。
+
+检索策略分层（可插拔，KsADK MemoryRecord 始终是公共协议）：
+
+.. code-block:: text
+
+    Tenant / ACL / Scope Filter   （Provider SQL 已完成）
+      -> Time / Status / TTL Filter（Coordinator.recall 已完成）
+      -> Keyword + Vector Search   （keyword：词项覆盖率；vector：可选注入）
+      -> Rerank                    （分数融合：coverage 为主，vector 加权）
+      -> Deduplicate / Diversity   （同 slot_key 只留最高分）
+      -> Token Budget Truncation   （按分数顺序装箱）
+
+本地 SQLite Provider 无向量索引，``vector_score`` 由外部注入（企业
+Memory Service / 向量库适配器提供）；缺失时退化为纯关键词管线，不阻塞。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Mapping, Protocol, Sequence
+
+from ksadk.memory.models import MemoryRecord
+
+#: 多样性控制：同 slot_key 保留的最高分条数。
+_PER_SLOT_LIMIT = 1
+
+
+class MemorySemanticScorer(Protocol):
+    """Optional semantic scoring boundary for a Memory Service or embedding backend.
+
+    Implementations return normalized scores in ``[0, 1]`` keyed by ``memory_id``.
+    The runtime treats the scorer as an optional enhancement: failures must degrade
+    to keyword retrieval instead of failing the conversation.
+    """
+
+    def score(
+        self, *, query: str, records: Sequence[MemoryRecord]
+    ) -> Mapping[str, float]: ...
+
+
+class MemoryReranker(Protocol):
+    """Optional second-stage reranker boundary.
+
+    A reranker receives the already filtered and cheaply ranked candidate set and
+    returns memory ids in preferred order.  It may be backed by a cross-encoder,
+    a managed rerank API or an organization-specific policy model.  The Harness
+    validates its output and degrades to the first-stage order on any failure.
+    """
+
+    def rerank(self, *, query: str, records: Sequence[MemoryRecord]) -> Sequence[str]: ...
+
+
+@dataclass(frozen=True)
+class RetrievalConfig:
+    """管线参数（Token 截断与多样性，避免硬编码全局常数）。"""
+
+    top_k: int = 8
+    max_tokens: int = 4000
+    #: vector 分数权重（0 = 纯关键词）。
+    vector_weight: float = 0.0
+    per_slot_limit: int = _PER_SLOT_LIMIT
+
+
+def keyword_coverage(query: str, content: str) -> float:
+    """查询词项在内容中的覆盖率（0~1；ASCII 词 + CJK 2-gram）。"""
+    terms = _query_terms(query)
+    if not terms:
+        return 0.0
+    lowered = content.lower()
+    hits = sum(1 for t in terms if t in lowered)
+    return round(hits / len(terms), 4)
+
+
+def _query_terms(query: str) -> list[str]:
+    from ksadk.memory.providers.local_sqlite import _keyword_query_terms
+
+    ascii_terms, cjk_terms = _keyword_query_terms(query)
+    terms = [t.lower() for t in ascii_terms]
+    # CJK 词项直接作为覆盖判据（provider 侧已做 2-gram 切分）。
+    terms.extend(cjk_terms)
+    return terms
+
+
+def rerank_records(
+    records: Sequence[MemoryRecord],
+    *,
+    query: str,
+    config: RetrievalConfig | None = None,
+    vector_score: Callable[[MemoryRecord], float] | None = None,
+) -> list[MemoryRecord]:
+    """Rerank + 去重/多样性 + Token 截断（§7.5 默认管线）。
+
+    分数 = (1-w) * keyword_coverage + w * vector_score；无 vector 注入时
+    w 强制为 0（退化为纯关键词）。排序后按 slot_key 去重（保留最高分），
+    最后按分数顺序做 Token 装箱截断。
+    """
+    cfg = config or RetrievalConfig()
+    weight = cfg.vector_weight if vector_score is not None else 0.0
+
+    scored: list[tuple[float, MemoryRecord]] = []
+    for record in records:
+        kw = keyword_coverage(query, record.content)
+        vec = vector_score(record) if vector_score is not None and weight > 0 else 0.0
+        score = round((1 - weight) * kw + weight * vec, 4)
+        # 综合重要性微调（同分时 importance 高者在前，不改变主序）。
+        scored.append((score + record.importance * 1e-6, record))
+    scored.sort(key=lambda pair: -pair[0])
+
+    # Deduplicate / Diversity：同 slot_key 只留最高分（slot_key 取 metadata）。
+    seen_slots: dict[str, int] = {}
+    diverse: list[MemoryRecord] = []
+    for score, record in scored:
+        slot = str(record.metadata.get("slot_key") or "")
+        if slot:
+            count = seen_slots.get(slot, 0)
+            if count >= cfg.per_slot_limit:
+                continue
+            seen_slots[slot] = count + 1
+        diverse.append(record)
+        if len(diverse) >= cfg.top_k:
+            break
+
+    return _box_by_tokens(diverse, cfg.max_tokens)
+
+
+def select_ranked_records(
+    records: Sequence[MemoryRecord],
+    *,
+    ranked_ids: Sequence[str],
+    top_k: int,
+    max_tokens: int,
+    per_slot_limit: int = _PER_SLOT_LIMIT,
+) -> list[MemoryRecord]:
+    """Validate a reranker order, preserve diversity and enforce the token budget.
+
+    Unknown ids, duplicate ids and omitted candidates are rejected.  Requiring a
+    full permutation prevents a faulty or compromised reranker from silently
+    dropping Memory facts.  Callers should catch ``ValueError`` and retain the
+    first-stage result.
+    """
+
+    by_id = {record.memory_id: record for record in records}
+    normalized = tuple(str(memory_id) for memory_id in ranked_ids)
+    if len(normalized) != len(set(normalized)):
+        raise ValueError("reranker returned duplicate memory ids")
+    if set(normalized) != set(by_id):
+        raise ValueError("reranker must return every candidate exactly once")
+
+    selected: list[MemoryRecord] = []
+    seen_slots: dict[str, int] = {}
+    for memory_id in normalized:
+        record = by_id[memory_id]
+        slot = str(record.metadata.get("slot_key") or "")
+        if slot:
+            count = seen_slots.get(slot, 0)
+            if count >= per_slot_limit:
+                continue
+            seen_slots[slot] = count + 1
+        selected.append(record)
+        if len(selected) >= top_k:
+            break
+    return _box_by_tokens(selected, max_tokens)
+
+
+def _box_by_tokens(records: list[MemoryRecord], max_tokens: int) -> list[MemoryRecord]:
+    """按顺序装箱（§10.6：Token 预算截断）。"""
+    from ksadk.context_engine.tokenizer import get_default_token_counter
+
+    counter = get_default_token_counter()
+    total = 0
+    out: list[MemoryRecord] = []
+    for record in records:
+        n = counter.count_text(record.content)
+        if total + n > max_tokens:
+            break
+        total += n
+        out.append(record)
+    return out
+
+
+__all__ = [
+    "MemoryReranker",
+    "MemorySemanticScorer",
+    "RetrievalConfig",
+    "keyword_coverage",
+    "rerank_records",
+    "select_ranked_records",
+]