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

ksadk/memory/adk/resilient_session_service.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from dataclasses import dataclass
 from typing import Any, Optional
 
 from ksadk.compat.adk_compat import (
@@ -12,11 +13,22 @@ from ksadk.compat.adk_compat import (
     ListSessionsResponse,
     Session,
 )
+from ksadk.sessions.db_budget import DatabaseOperationDeadline, session_db_budget
 from ksadk.sessions.resilience import is_session_backend_failure
 
 logger = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True)
+class ADKEventCommitUnknown:
+    """Fail-open live event whose durable COMMIT cannot be confirmed."""
+
+    app_name: str
+    user_id: str
+    session_id: str
+    event_id: str
+
+
 class ResilientADKSessionService(BaseSessionService):
     """Run ADK sessions locally while mirroring them to durable storage."""
 
@@ -26,6 +38,11 @@ class ResilientADKSessionService(BaseSessionService):
         self.primary = primary
         self.live = InMemorySessionService()
         self._primary_sessions: dict[tuple[str, str, str], Session] = {}
+        # A failed write has an unknown commit outcome. Never replay it or
+        # hydrate stale durable state over the live session after recovery.
+        self._dirty_sessions: set[tuple[str, str, str]] = set()
+        self._deleted_sessions: set[tuple[str, str, str]] = set()
+        self.unknown_event_commits: set[ADKEventCommitUnknown] = set()
         self._primary_enabled = True
         self._probe_task: asyncio.Task[None] | None = None
 
@@ -92,7 +109,42 @@ class ResilientADKSessionService(BaseSessionService):
     def _key(app_name: str, user_id: str, session_id: str) -> tuple[str, str, str]:
         return app_name, user_id, session_id
 
+    def _write_deadline(self) -> DatabaseOperationDeadline:
+        return DatabaseOperationDeadline(
+            getattr(self.primary, "db_budget", None) or session_db_budget()
+        )
+
+    async def reconcile_event_commit(
+        self, *, app_name: str, user_id: str, session_id: str, event_id: str
+    ) -> str:
+        """Read back a stable ADK event ID after a write's outcome is unknown.
+
+        Absence is still ``unknown`` because an in-flight commit may finish
+        after this read. This method never replays an event or clears dirty
+        local state.
+        """
+        try:
+            durable = await self.primary.get_session(
+                app_name=app_name, user_id=user_id, session_id=session_id
+            )
+        except Exception:
+            return "unknown"
+        if durable and any(event.id == event_id for event in durable.events):
+            self.unknown_event_commits.discard(
+                ADKEventCommitUnknown(app_name, user_id, session_id, event_id)
+            )
+            return "committed"
+        return "unknown"
+
     async def _hydrate(self, durable: Session) -> Session:
+        key = self._key(durable.app_name, durable.user_id, durable.id)
+        if key in self._dirty_sessions:
+            existing = await self.live.get_session(
+                app_name=durable.app_name, user_id=durable.user_id, session_id=durable.id
+            )
+            if existing is None:
+                raise RuntimeError("Dirty ADK session has no live state")
+            return existing
         existing = await self.live.get_session(
             app_name=durable.app_name,
             user_id=durable.user_id,
@@ -128,12 +180,15 @@ class ResilientADKSessionService(BaseSessionService):
         session_id: Optional[str] = None,
     ) -> Session:
         if session_id:
+            key = self._key(app_name, user_id, session_id)
             existing = await self.live.get_session(
                 app_name=app_name,
                 user_id=user_id,
                 session_id=session_id,
             )
-            if self._primary_enabled:
+            if key in self._dirty_sessions and existing is not None:
+                return existing
+            if self._primary_enabled and key not in self._dirty_sessions:
                 try:
                     durable = await self.primary.get_session(
                         app_name=app_name,
@@ -154,7 +209,9 @@ class ResilientADKSessionService(BaseSessionService):
             state=state,
             session_id=session_id,
         )
-        if self._primary_enabled:
+        key = self._key(app_name, user_id, live.id)
+        self._deleted_sessions.discard(key)
+        if self._primary_enabled and key not in self._dirty_sessions:
             try:
                 durable = await self.primary.create_session(
                     app_name=app_name,
@@ -164,8 +221,11 @@ class ResilientADKSessionService(BaseSessionService):
                 )
                 self._primary_sessions[self._key(app_name, user_id, live.id)] = durable
             except Exception as exc:
+                self._dirty_sessions.add(key)
                 if not self._handle_primary_failure(exc):
                     raise
+        else:
+            self._dirty_sessions.add(key)
         return live
 
     async def get_session(
@@ -176,13 +236,16 @@ class ResilientADKSessionService(BaseSessionService):
         session_id: str,
         config: Optional[GetSessionConfig] = None,
     ) -> Optional[Session]:
+        key = self._key(app_name, user_id, session_id)
         live = await self.live.get_session(
             app_name=app_name,
             user_id=user_id,
             session_id=session_id,
             config=config,
         )
-        if not self._primary_enabled:
+        if key in self._deleted_sessions:
+            return None
+        if not self._primary_enabled or key in self._dirty_sessions:
             return live
         try:
             durable = await self.primary.get_session(
@@ -207,6 +270,9 @@ class ResilientADKSessionService(BaseSessionService):
             try:
                 durable = await self.primary.list_sessions(app_name=app_name, user_id=user_id)
                 for session in durable.sessions:
+                    key = self._key(session.app_name, session.user_id, session.id)
+                    if key in self._dirty_sessions:
+                        continue
                     await self._hydrate(session)
             except Exception as exc:
                 if not self._handle_primary_failure(exc):
@@ -214,8 +280,11 @@ class ResilientADKSessionService(BaseSessionService):
         return await self.live.list_sessions(app_name=app_name, user_id=user_id)
 
     async def delete_session(self, *, app_name: str, user_id: str, session_id: str) -> None:
+        key = self._key(app_name, user_id, session_id)
         await self.live.delete_session(app_name=app_name, user_id=user_id, session_id=session_id)
-        self._primary_sessions.pop(self._key(app_name, user_id, session_id), None)
+        self._primary_sessions.pop(key, None)
+        self._dirty_sessions.add(key)
+        self._deleted_sessions.add(key)
         if self._primary_enabled:
             try:
                 await self.primary.delete_session(
@@ -223,33 +292,64 @@ class ResilientADKSessionService(BaseSessionService):
                     user_id=user_id,
                     session_id=session_id,
                 )
+                self._dirty_sessions.discard(key)
+                self._deleted_sessions.discard(key)
             except Exception as exc:
                 if not self._handle_primary_failure(exc):
                     raise
 
     async def append_event(self, session: Session, event: Event) -> Event:
         stored = await self.live.append_event(session, event)
-        if not self._primary_enabled:
-            return stored
+        deadline = self._write_deadline()
         key = self._key(session.app_name, session.user_id, session.id)
+        if not self._primary_enabled or key in self._dirty_sessions:
+            self._dirty_sessions.add(key)
+            return stored
         durable_session = self._primary_sessions.get(key)
         try:
             if durable_session is None:
-                durable_session = await self.primary.get_session(
-                    app_name=session.app_name,
-                    user_id=session.user_id,
-                    session_id=session.id,
-                )
-                if durable_session is None:
-                    durable_session = await self.primary.create_session(
+                durable_session = await deadline.run(
+                    self.primary.get_session(
                         app_name=session.app_name,
                         user_id=session.user_id,
-                        state=session.state,
                         session_id=session.id,
                     )
+                )
+                if durable_session is None:
+                    durable_session = await deadline.run(
+                        self.primary.create_session(
+                            app_name=session.app_name,
+                            user_id=session.user_id,
+                            state=session.state,
+                            session_id=session.id,
+                        )
+                    )
                 self._primary_sessions[key] = durable_session
-            await self.primary.append_event(durable_session, event)
+            await deadline.run(self.primary.append_event(durable_session, event))
         except Exception as exc:
+            if is_session_backend_failure(exc):
+                try:
+                    outcome = await deadline.run(
+                        self.reconcile_event_commit(
+                            app_name=session.app_name,
+                            user_id=session.user_id,
+                            session_id=session.id,
+                            event_id=event.id,
+                        )
+                    )
+                except Exception:
+                    outcome = "unknown"
+                if outcome == "committed":
+                    # A lost acknowledgement is not a failed write. Reload the
+                    # exact durable revision before the next append.
+                    self._primary_sessions.pop(key, None)
+                    return stored
+                self.unknown_event_commits.add(ADKEventCommitUnknown(*key, event.id))
+                logger.warning(
+                    "ADK event commit outcome unknown; retaining dirty live state",
+                    extra={"session_backend_reason_code": "ADK_EVENT_COMMIT_UNKNOWN"},
+                )
+            self._dirty_sessions.add(key)
             if not self._handle_primary_failure(exc):
                 raise
         return stored

ksadk/memory/adk/short_term_memory.py

@@ -153,18 +153,17 @@ class ShortTermMemory(BaseModel):
         try:
             from ksadk.compat.adk_compat import DatabaseSessionService
             from ksadk.memory.adk.resilient_session_service import ResilientADKSessionService
-            from ksadk.sessions.resilience import session_backend_timeout_seconds
-
-            service_kwargs = {}
             if normalized_db_url.startswith(("postgresql://", "postgresql+asyncpg://")):
-                timeout = session_backend_timeout_seconds()
-                service_kwargs["connect_args"] = {
-                    "timeout": timeout,
-                    "command_timeout": timeout,
-                }
+                from ksadk.memory.adk.bounded_database_session_service import (
+                    BoundedADKDatabaseSessionService,
+                )
+
+                primary = BoundedADKDatabaseSessionService(db_url=normalized_db_url)
+            else:
+                primary = DatabaseSessionService(db_url=normalized_db_url)
 
             self._session_service = ResilientADKSessionService(
-                DatabaseSessionService(db_url=normalized_db_url, **service_kwargs)
+                primary
             )
             logger.info("ShortTermMemory: using DatabaseSessionService")
         except ImportError:

ksadk/memory/extraction.py

@@ -12,8 +12,12 @@
 
 from __future__ import annotations
 
+import hashlib
+import json
 import re
 import uuid
+from dataclasses import replace
+from types import SimpleNamespace
 from typing import Sequence
 
 from ksadk.memory.models import MemoryCandidate, MemoryScope
@@ -25,6 +29,23 @@ _EXPLICIT_PATTERNS: tuple[re.Pattern[str], ...] = (
     re.compile(r"(?i)remember\s+(?:that\s+)?(.+)", re.IGNORECASE),
     re.compile(r"(?i)请记[:：]?\s*(.+)"),
 )
+# A declared conversation/turn horizon belongs to Session history, not the
+# cross-session Memory provider. Inspect the memory-bearing first statement:
+# a later "For this turn reply ACK" only scopes the answer format.
+_SESSION_RETENTION = re.compile(
+    r"\b(?:for|during|within|in)\s+(?:only\s+)?(?:this|the\s+current)\s+"
+    r"(?:conversation|chat|session|turn)\b"
+    r"|(?:本次|这次|此次|当前|这个|本)(?:会话|对话|聊天)"
+    r"|(?:本轮|这轮)",
+    re.IGNORECASE,
+)
+
+
+def _session_only_memory(text: str) -> bool:
+    statement = re.split(r"[。！？!?\r\n]|\.(?=\s|$)", text.strip(), maxsplit=1)[0]
+    return _SESSION_RETENTION.search(statement) is not None
+
+
 # 明确纠正同一偏好槽位。首期只覆盖语义边界清晰的动作型偏好，避免把
 # “喜欢音乐”和“喜欢运动”等无关事实误判为冲突。
 _PREFERENCE_CORRECTION = re.compile(
@@ -95,17 +116,44 @@ def derive_profile_slot_key(content: str) -> str:
     return f"profile.preference.{labels[action]}"
 
 
+def is_explicit_memory_instruction(text: str) -> bool:
+    """Recognize a complete durable instruction, not a quoted substring.
+
+    Candidate extraction intentionally searches larger transcripts. A host
+    granting an immediate explicit write needs the narrower whole-input test.
+    Unsupported wording can use the host's exact-call consent path; this is
+    not a general semantic intent classifier.
+    """
+    text = text.strip()
+    if _session_only_memory(text):
+        return False
+    if any(pattern.fullmatch(text) for pattern in _EXPLICIT_PATTERNS):
+        return True
+    if _PREFERENCE_CORRECTION.fullmatch(text) or _GENERAL_CORRECTION.fullmatch(text):
+        return True
+    hobby = _HOBBY_DECLARATION.fullmatch(text)
+    return bool(hobby and hobby.group("correction"))
+
+
 def propose_memory_candidates(
     events: Sequence[any],  # type: ignore[name-defined]
     *,
     scope: MemoryScope = "user",
     scope_id: str = "",
+    max_content_chars: int | None = 1000,
 ) -> list[MemoryCandidate]:
     """从待压缩事件提取记忆候选（方案 §9.2）。
 
     纯确定性、无 LLM。返回候选列表交 Coordinator flush；Policy 决定 commit/reject。
     """
     candidates: list[MemoryCandidate] = []
+    if max_content_chars is not None and (
+        type(max_content_chars) is not int or max_content_chars < 1
+    ):
+        raise ValueError("memory candidate limit must be a positive integer or None")
+
+    def bounded(content):
+        return content if max_content_chars is None else content[:max_content_chars]
     if not events:
         return candidates
     for event in events:
@@ -119,6 +167,8 @@ def propose_memory_candidates(
 
         # 1. 用户显式记忆意图
         if author == "user" or event_type == "user_message":
+            if _session_only_memory(text):
+                continue
             hobby = _HOBBY_DECLARATION.search(text)
             if hobby and hobby.group("correction"):
                 new_value = hobby.group("value").strip().strip("。.，, ")
@@ -131,7 +181,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.95,
                             importance=0.9,
                             source_event_ids=[event_id],
@@ -153,7 +203,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.9,
                             importance=0.8,
                             source_event_ids=[event_id],
@@ -175,7 +225,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.95,
                             importance=0.9,
                             source_event_ids=[event_id],
@@ -197,7 +247,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.9,
                             importance=0.8,
                             source_event_ids=[event_id],
@@ -221,7 +271,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.75,
                             importance=0.65,
                             source_event_ids=[event_id],
@@ -242,7 +292,7 @@ def propose_memory_candidates(
                     memory_type="fact",
                     scope=scope,
                     scope_id=scope_id,
-                    content=text[:1000],
+                    content=bounded(text),
                     confidence=0.7,
                     importance=0.6,
                     source_event_ids=[event_id],
@@ -253,6 +303,65 @@ def propose_memory_candidates(
     return candidates
 
 
+def explicit_memory_target(text: str) -> tuple[str, str] | None:
+    """Decode one whole explicit goal without truncating its requested fact.
+
+    This is a pure intent interpretation. The synthetic extraction input never
+    supplies persisted provenance or write authorization; those remain the
+    host's actual goal, approval and Run event identities.
+    """
+    if not is_explicit_memory_instruction(text):
+        return None
+    candidates = propose_memory_candidates(
+        (SimpleNamespace(text=text, author="user", event_type="user_message"),),
+        max_content_chars=None,
+    )
+    explicit = [candidate for candidate in candidates
+                if candidate.reason.startswith("explicit_user")]
+    if len(explicit) != 1:
+        return None
+    return explicit[0].operation, explicit[0].content
+
+
+NATIVE_USER_EXTRACTION_POLICY = "native-original-user-profile/v2"
+
+
+def native_user_memory_candidate(
+    text: str, *, source_event_id: str, scope: MemoryScope, scope_id: str,
+) -> MemoryCandidate | None:
+    """Interpret a complete original user statement, never a transcript substring.
+
+    The host must supply canonical user input and its durable source identity.
+    Confidence describes known user authorship, not the truth of a preference
+    or permission to persist it. The existing Policy still requires independent
+    observations for implicit declarations. No model/summary/tool text is admitted.
+    """
+    text = text.strip()
+    explicit = is_explicit_memory_instruction(text)
+    implicit = any(pattern.fullmatch(text) for pattern in _IMPLICIT_PREFERENCE_PATTERNS)
+    hobby = _HOBBY_DECLARATION.fullmatch(text)
+    if not source_event_id.strip() or not (explicit or implicit or hobby):
+        return None
+    proposed = propose_memory_candidates(
+        (SimpleNamespace(text=text, author="user", event_type="user_message"),),
+        scope=scope, scope_id=scope_id, max_content_chars=None,
+    )
+    if not proposed and hobby and not hobby.group("correction"):
+        proposed = [MemoryCandidate(
+            candidate_id="pending", operation="add", memory_type="profile", scope=scope,
+            scope_id=scope_id, content=f"我的爱好是{hobby.group('value').strip()}",
+            confidence=1, importance=0.65, source_event_ids=[source_event_id],
+            reason="implicit_user_preference", slot_key="profile.preference.hobby",
+        )]
+    if len(proposed) != 1 or (not explicit and proposed[0].reason != "implicit_user_preference"):
+        return None
+    value = proposed[0]
+    identity = json.dumps((NATIVE_USER_EXTRACTION_POLICY, scope, scope_id, source_event_id,
+                           value.operation, value.content), ensure_ascii=False)
+    return replace(value, candidate_id="candidate_" + hashlib.sha256(identity.encode()).hexdigest(),
+                   confidence=1, source_event_ids=[source_event_id])
+
+
 class MemoryExtractor:
     """方案 §9.2 的 ``MemoryExtractor.propose()`` 接口封装。"""
 
@@ -264,4 +373,8 @@ class MemoryExtractor:
         return propose_memory_candidates(events, scope=self._scope, scope_id=self._scope_id)
 
 
-__all__ = ["MemoryExtractor", "derive_profile_slot_key", "propose_memory_candidates"]
+__all__ = [
+    "MemoryExtractor", "derive_profile_slot_key", "explicit_memory_target",
+    "is_explicit_memory_instruction", "propose_memory_candidates",
+    "native_user_memory_candidate", "NATIVE_USER_EXTRACTION_POLICY",
+]

ksadk/memory/providers/local_candidates.py

@@ -0,0 +1,183 @@
+"""Local candidate consumption under the owning Provider's writer transaction.
+
+No candidate body is retained while pending/rejected. Original source markers
+outlive a forget so replay cannot count old prose as new evidence or resurrect it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import replace
+
+from ksadk.memory.extraction import NATIVE_USER_EXTRACTION_POLICY, derive_profile_slot_key
+from ksadk.memory.models import MemoryRecord
+from ksadk.memory.policy import MemoryPolicy, content_hash
+
+from .local_sqlite import VersionConflict, _now_iso, _row_to_record
+
+
+def namespace(tenant_id, workspace_id, scope, scope_id, memory_type):
+    identity = (tenant_id, None if scope == "org" else workspace_id, scope, scope_id, memory_type)
+    return hashlib.sha256(json.dumps(identity, ensure_ascii=False).encode()).hexdigest()
+
+
+def discard_slot_observations(conn, record):
+    key = namespace(record.tenant_id, record.workspace_id, record.scope,
+                    record.scope_id, record.memory_type)
+    slot = str(record.metadata.get("slot_key") or derive_profile_slot_key(record.content))
+    conn.execute(
+        "DELETE FROM memory_candidate_observations WHERE namespace=? "
+        "AND (content_hash=? OR (slot_key<>'' AND slot_key=?))",
+        (key, record.content_hash, slot),
+    )
+
+
+def consume_explicit_write_horizon(conn, record, original, candidates):
+    """A confirmed write consumes earlier eligible inputs in its actual slot.
+
+This is part of the same writer transaction as the fact and receipt. Keep only
+original identities/digests, and preserve unrelated slots for later extraction.
+"""
+    targets = (original, record) if original is not None else (record,)
+    slots = {value for target in targets if (
+        value := target.metadata.get("slot_key") or derive_profile_slot_key(target.content)
+    )}
+    hashes = {target.content_hash for target in targets}
+    for candidate, source_digest in candidates:
+        if (candidate.scope, candidate.scope_id) != (record.scope, record.scope_id):
+            raise VersionConflict("candidate_write_horizon_scope_unbound")
+        if not (candidate.slot_key in slots or content_hash(candidate.content) in hashes):
+            continue
+        key = namespace(record.tenant_id, record.workspace_id, candidate.scope,
+                        candidate.scope_id, candidate.memory_type)
+        for target in targets:
+            conn.execute(
+                "DELETE FROM memory_candidate_observations WHERE namespace=? "
+                "AND (content_hash=? OR (slot_key<>'' AND slot_key=?))",
+                (key, target.content_hash,
+                 target.metadata.get("slot_key") or derive_profile_slot_key(target.content)),
+            )
+        source = candidate.source_event_ids[0]
+        previous = conn.execute(
+            "SELECT source_digest FROM memory_candidate_sources "
+            "WHERE namespace=? AND source_event_id=?", (key, source),
+        ).fetchone()
+        if previous is not None and previous["source_digest"] != source_digest:
+            raise VersionConflict("candidate_source_changed")
+        conn.execute("INSERT OR IGNORE INTO memory_candidate_sources VALUES (?,?,?)",
+                     (key, source, source_digest))
+
+
+def consume(provider, candidate, *, operation_key, request_digest, source_session_id,
+            source_digest, tenant_id, workspace_id):
+    # The caller holds the Provider lock and BEGIN IMMEDIATE. Fact, source,
+    # independent observations and receipt commit/roll back together.
+    prior = provider._mutation_receipt_locked(operation_key, request_digest)
+    if prior is not None:
+        return prior
+    if tenant_id != provider._tenant_id or len(candidate.source_event_ids) != 1:
+        raise VersionConflict("candidate_source_or_tenant_unbound")
+    conn, source = provider._conn, candidate.source_event_ids[0]
+    key = namespace(tenant_id, workspace_id, candidate.scope, candidate.scope_id,
+                    candidate.memory_type)
+    fact_hash = content_hash(candidate.content)
+    fingerprint = hashlib.sha256(json.dumps(
+        (NATIVE_USER_EXTRACTION_POLICY, candidate.slot_key, fact_hash),
+    ).encode()).hexdigest()
+
+    def seal(decision, *, reason, observations=0, record=None, action=None):
+        result = {"committed": decision == "committed", "decision": decision,
+                  "code": reason, "observations": observations}
+        if record is not None:
+            result.update(memory_id=record.memory_id, version=record.version,
+                          status=record.status, content_hash=record.content_hash,
+                          action=action)
+        conn.execute("INSERT INTO memory_operation_receipts VALUES (?,?,?)",
+                     (operation_key, request_digest, json.dumps(result, ensure_ascii=False)))
+        return result
+
+    policy = MemoryPolicy()
+    early = policy.evaluate(candidate)
+    if early.decision == "reject":
+        return seal("rejected", reason=early.reason)
+    if len(candidate.content) > provider.capabilities().max_record_chars:
+        return seal("rejected", reason="candidate_content_over_budget")
+    original = conn.execute(
+        "SELECT source_digest FROM memory_candidate_sources "
+        "WHERE namespace=? AND source_event_id=?",
+        (key, source),
+    ).fetchone()
+    if original is not None:
+        if original["source_digest"] != source_digest:
+            raise VersionConflict("candidate_source_changed")
+        count = conn.execute(
+            "SELECT COUNT(*) FROM memory_candidate_observations "
+            "WHERE namespace=? AND candidate_key=?",
+            (key, fingerprint),
+        ).fetchone()[0]
+        return seal("duplicate_source", reason="original_source_already_consumed",
+                    observations=count)
+
+    # Native writes have a slot key. For older records derive only the same
+    # deterministic slot inside the exact tenant/workspace/scope/type partition.
+    rows = conn.execute(
+        "SELECT * FROM memory_records WHERE tenant_id=? AND scope=? AND scope_id=? "
+        "AND memory_type=? AND status='active' "
+        "AND (scope='org' OR workspace_id=?)",
+        (tenant_id, candidate.scope, candidate.scope_id, candidate.memory_type, workspace_id),
+    ).fetchall()
+    matches = [record for row in rows if (
+        (record := _row_to_record(row)).content_hash == fact_hash
+        or bool(candidate.slot_key) and (
+            record.metadata.get("slot_key") or derive_profile_slot_key(record.content)
+        ) == candidate.slot_key
+    )]
+    if len(matches) > 1:
+        return seal("rejected", reason="candidate_slot_ambiguous")
+    existing = matches[0] if matches else None
+    if existing is not None and existing.write_policy == "locked":
+        return seal("rejected", reason="candidate_slot_locked")
+    if candidate.operation != "add" and existing is None:
+        return seal("rejected", reason="candidate_correction_target_missing")
+    conn.execute("INSERT INTO memory_candidate_sources VALUES (?,?,?)",
+                 (key, source, source_digest))
+    conn.execute("INSERT INTO memory_candidate_observations VALUES (?,?,?,?,?,?)",
+                 (key, fingerprint, source, fact_hash, candidate.slot_key, _now_iso()))
+    observed = conn.execute(
+        "SELECT source_event_id FROM memory_candidate_observations "
+        "WHERE namespace=? AND candidate_key=? ORDER BY source_event_id",
+        (key, fingerprint),
+    ).fetchall()
+    count = len(observed)
+    effective = replace(candidate, operation="update") if existing else candidate
+    evaluated = policy.evaluate(effective, existing=existing, observations=count)
+    if evaluated.decision != "commit":
+        return seal(evaluated.decision, reason=evaluated.reason, observations=count)
+    if existing is not None and existing.content_hash == fact_hash:
+        return seal("duplicate", reason="same_current_fact", observations=count, record=existing)
+    from uuid import uuid4
+
+    record = MemoryRecord(
+        memory_id=existing.memory_id if existing else "memory_" + uuid4().hex,
+        tenant_id=tenant_id, workspace_id=workspace_id, scope=candidate.scope,
+        scope_id=candidate.scope_id, memory_type=candidate.memory_type,
+        content=candidate.content, summary=candidate.content, status="active",
+        confidence=candidate.confidence, importance=candidate.importance,
+        valid_from=existing.valid_from if existing else _now_iso(), valid_to="",
+        expires_at=candidate.expires_at,
+        source_session_id=existing.source_session_id if existing else source_session_id,
+        source_event_ids=list(dict.fromkeys((
+            *(existing.source_event_ids if existing else ()),
+            *(row["source_event_id"] for row in observed),
+        ))), source_seq_range=None, content_hash=fact_hash, version=1,
+        metadata={**(existing.metadata if existing else {}),
+                  "slot_key": candidate.slot_key,
+                  "extraction_policy": NATIVE_USER_EXTRACTION_POLICY,
+                  "mutation_session_id": source_session_id, "source_input_digest": source_digest},
+        write_policy=existing.write_policy if existing else
+        "user_confirm" if candidate.reason.startswith("explicit_user") else "auto",
+    )
+    saved = provider._upsert_locked(record, expected_version=existing.version if existing else None)
+    return seal("committed", reason=evaluated.reason, observations=count, record=saved,
+                action="correct" if existing else "remember")