Enterprise agent platform for building, deploying, and operating AI teammates.
feat(memory): host-supplied provenance and UTC timestamps for stored memories (#3786)
Zhenghao Yinb84cd7929526
diff --git a/src/xagent/core/agent/context/memory_tool.py b/src/xagent/core/agent/context/memory_tool.pyindex c6b8bc759..6ddb33397 100644--- a/src/xagent/core/agent/context/memory_tool.py+++ b/src/xagent/core/agent/context/memory_tool.py@@ -15,6 +15,7 @@ from typing import Any, Literal, get_argsfrom pydantic import BaseModel, Fieldfrom ...memory.core import MemoryNote+from ...memory.provenance import MEMORY_PROVENANCE_METADATA_KEY, MemoryProvenancefrom ..trace import (trace_memory_retrieve_end,trace_memory_retrieve_start,@@ -80,7 +81,16 @@ class StoreMemoryArgs(BaseModel):class StoreMemoryTool:- """Execution-scoped ``store_memory`` tool bound to a memory store."""+ """Execution-scoped ``store_memory`` tool bound to a memory store.++ ``provenance`` is an optional host mapping, already validated by+ ``core.memory.provenance.validate_memory_provenance``, that is copied+ into every stored note's metadata under+ ``MEMORY_PROVENANCE_METADATA_KEY``. It is fixed for the tool's lifetime+ because a tool instance never outlives the run (and so the task/channel)+ it was built for. Without it the stored metadata is+ exactly ``{kind, source}``, as before provenance existed.+ """name = STORE_MEMORY_TOOL_NAMEdescription = _STORE_MEMORY_DESCRIPTION@@ -95,6 +105,7 @@ class StoreMemoryTool:category: str = "react_memory",max_stores: int = DEFAULT_MAX_STORES_PER_RUN,dedup_distance_threshold: float = DEFAULT_DEDUP_DISTANCE_THRESHOLD,+ provenance: MemoryProvenance | None = None,) -> None:self.memory_store = memory_storeself.task = task@@ -102,6 +113,7 @@ class StoreMemoryTool:self.category = categoryself.max_stores = max_storesself.dedup_distance_threshold = dedup_distance_threshold+ self.provenance = provenanceself.stored_count = 0self._store_lock = asyncio.Lock()@@ -205,16 +217,18 @@ class StoreMemoryTool:return results[0] if results else Nonedef _add(self, content: str, kind: str) -> str | None:- note = MemoryNote(- content=content,- category=self.category,- # No request text here: it is conversation content, and a note- # outlives the conversation it came from (#2753).- metadata={- "kind": kind,- "source": STORE_MEMORY_TOOL_NAME,- },- )+ # No request text here: it is conversation content, and a note+ # outlives the conversation it came from (#2753). Provenance carries+ # identifiers only (grammar-checked by ``validate_memory_provenance``).+ metadata: dict[str, Any] = {+ "kind": kind,+ "source": STORE_MEMORY_TOOL_NAME,+ }+ if self.provenance is not None:+ # A fresh plain dict per note: stores serialize metadata as JSON+ # and must not share one mutable mapping across notes.+ metadata[MEMORY_PROVENANCE_METADATA_KEY] = dict(self.provenance)+ note = MemoryNote(content=content, category=self.category, metadata=metadata)try:response = self.memory_store.add(note)except Exception:@@ -326,7 +340,13 @@ class UpdateMemoryArgs(BaseModel):class UpdateMemoryTool:- """Execution-scoped ``update_memory`` tool bound to a memory store."""+ """Execution-scoped ``update_memory`` tool bound to a memory store.++ Only the content changes: the note keeps its metadata, including any+ ``provenance``. Provenance records where a memory was *originally learned*+ and is deliberately not re-stamped with the updating run's channel, so a+ correction made elsewhere never relabels the memory's origin.+ """name = UPDATE_MEMORY_TOOL_NAMEdescription = (@@ -514,18 +534,27 @@ def build_memory_tools(task: str,runtime: Any | None = None,context: Any | None = None,+ provenance: MemoryProvenance | None = None,) -> list[Any]:"""Create the memory tool set, or [] when no memory store is active.When ``context`` is given, mark it so the system context renders thememory-usage guidance alongside the tools (see- ``MEMORY_TOOLS_METADATA_KEY``).+ ``MEMORY_TOOLS_METADATA_KEY``). ``provenance`` is forwarded to+ ``store_memory`` (see :class:`StoreMemoryTool`); hosts supply it through+ ``MemoryPolicyDecision.memory_provenance``, which binds it here as the+ run's memory-tools factory."""if memory_store is None:return []tools: list[Any] = [- StoreMemoryTool(memory_store=memory_store, task=task, runtime=runtime),+ StoreMemoryTool(+ memory_store=memory_store,+ task=task,+ runtime=runtime,+ provenance=provenance,+ ),SearchMemoryTool(memory_store=memory_store, runtime=runtime),UpdateMemoryTool(memory_store=memory_store),DeleteMemoryTool(memory_store=memory_store),diff --git a/src/xagent/core/memory/base.py b/src/xagent/core/memory/base.pyindex 6342955fa..710f65a5d 100644--- a/src/xagent/core/memory/base.py+++ b/src/xagent/core/memory/base.py@@ -1,7 +1,7 @@from __future__ import annotationsfrom abc import ABC, abstractmethod-from datetime import datetime+from datetime import MINYEAR, datetime, timezonefrom typing import Any, Collection, List, Optionalfrom .core import MemoryNote, MemoryResponse@@ -13,23 +13,41 @@ from .scope_columns import (def comparable_timestamp(value: Any) -> Any:- """Normalize a datetime for cross-comparison in date-range filters.-- Stored note timestamps default to naive local time- (``MemoryNote.timestamp``'s ``datetime.now`` factory), while caller-supplied- ``date_from``/``date_to`` filter values may be timezone-aware (FastAPI- parses ISO date query params with an offset into aware datetimes).- Comparing the two directly raises ``TypeError``, which the stores' outer- exception handlers would swallow into a silently empty result. Aware- datetimes are therefore converted to naive local time before comparison;- naive datetimes and non-datetime values pass through unchanged.-- Shared by every ``MemoryStore`` implementation's filter dispatch so the- stores cannot drift apart on this policy.+ """Normalize a datetime so naive and aware values order correctly.++ ``MemoryNote.timestamp`` defaults to aware UTC, but notes written before+ that default carry naive server-local time, and caller-supplied+ ``date_from``/``date_to`` filter values may be either (FastAPI parses ISO+ date query params with an offset into aware datetimes). Comparing naive+ with aware raises ``TypeError``, which the stores' outer exception+ handlers would swallow into a silently empty result, and sorting a mixed+ list raises outright. Every datetime is therefore converted to aware UTC;+ non-datetime values pass through unchanged.++ Legacy assumption: a naive datetime is interpreted in the *current*+ process timezone, because that is what the old ``datetime.now`` default+ wrote. This is only exact while the server's timezone has not changed+ since the legacy rows were written; if it has, those rows are shifted by+ the difference. Nothing stored records the original zone, so this cannot+ be corrected after the fact.++ A value within a day of ``datetime.min``/``datetime.max`` (e.g. an+ open-ended ``date_from=0001-01-01`` filter) cannot be shifted to UTC+ without leaving the representable range; it is clamped to the matching+ UTC bound instead of raising, so the filter still means "unbounded"+ rather than failing the whole request.++ Shared by every ``MemoryStore`` implementation's filter dispatch and+ newest-first ordering so the stores cannot drift apart on this policy."""- if isinstance(value, datetime) and value.tzinfo is not None:- return value.astimezone().replace(tzinfo=None)- return value+ if not isinstance(value, datetime):+ return value+ try:+ return value.astimezone(timezone.utc)+ except (OverflowError, ValueError):+ # Only years 1 and 9999 can overflow, so the year picks the bound.+ bound = datetime.min if value.year == MINYEAR else datetime.max+ return bound.replace(tzinfo=timezone.utc)class MemoryStore(ABC):@@ -258,8 +276,8 @@ class MemoryStore(ABC):):return False- # Date range filters (both sides tz-normalized so an aware filter- # against the naive default timestamps cannot raise TypeError;+ # Date range filters (both sides tz-normalized so naive legacy rows,+ # aware rows and aware/naive filters never raise TypeError;# explicit None = no bound)date_from = filters.get("date_from")date_to = filters.get("date_to")diff --git a/src/xagent/core/memory/core.py b/src/xagent/core/memory/core.pyindex e34973185..6528356e7 100644--- a/src/xagent/core/memory/core.py+++ b/src/xagent/core/memory/core.py@@ -1,7 +1,7 @@from __future__ import annotationsimport uuid-from datetime import datetime+from datetime import datetime, timezonefrom typing import Any, Optional, Unionfrom pydantic import BaseModel, Field@@ -13,7 +13,11 @@ class MemoryNote(BaseModel):keywords: list[str] = Field(default_factory=list)tags: list[str] = Field(default_factory=list)category: str = "general"- timestamp: datetime = Field(default_factory=datetime.now)+ # New notes are timezone-aware UTC. Rows written before this default were+ # naive server-local time and are still read back naive, so any code that+ # orders or compares timestamps must go through+ # ``base.comparable_timestamp`` rather than comparing them directly.+ timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))mime_type: str = "text/plain"metadata: dict[str, Any] = Field(default_factory=dict)diff --git a/src/xagent/core/memory/in_memory.py b/src/xagent/core/memory/in_memory.pyindex 85a6d0b1c..9b0561713 100644--- a/src/xagent/core/memory/in_memory.py+++ b/src/xagent/core/memory/in_memory.py@@ -3,7 +3,7 @@ from __future__ import annotationsimport uuidfrom typing import Any, List, Optional-from .base import MemoryStore+from .base import MemoryStore, comparable_timestampfrom .core import MemoryNote, MemoryResponse@@ -77,8 +77,9 @@ class InMemoryMemoryStore(MemoryStore):else:results = list(self._store.values())- # Sort by timestamp (newest first)- results.sort(key=lambda x: x.timestamp, reverse=True)+ # Sort by timestamp (newest first); normalized because legacy naive+ # and current aware timestamps cannot be compared directly.+ results.sort(key=lambda x: comparable_timestamp(x.timestamp), reverse=True)return resultsdiff --git a/src/xagent/core/memory/lancedb.py b/src/xagent/core/memory/lancedb.pyindex 80daad7f0..af89ae7b7 100644--- a/src/xagent/core/memory/lancedb.py+++ b/src/xagent/core/memory/lancedb.py@@ -17,7 +17,7 @@ from ..model.embedding.adapter import create_embedding_adapterfrom ..model.model import EmbeddingModelConfigfrom ..tools.core.RAG_tools.LanceDB.schema_manager import _safe_close_tablefrom ..utils.lancedb_sql import sql_string_literal-from .base import MemoryStore+from .base import MemoryStore, comparable_timestampfrom .core import MemoryNote, MemoryResponsefrom .retrieval_compatibility import DEFAULT_STREAM_BATCH_SIZE, stream_lexical_top_kfrom .schema_migration import (@@ -1130,8 +1130,8 @@ class LanceDBMemoryStore(MemoryStore):newest-first to match InMemoryStore.list_all."""notes = self.search(query="", k=10000, filters=filters or None)- # Mirror InMemoryStore: newest first.- notes.sort(key=lambda n: n.timestamp, reverse=True)+ # Mirror InMemoryStore: newest first, over naive legacy and aware rows.+ notes.sort(key=lambda n: comparable_timestamp(n.timestamp), reverse=True)return notesdef get_stats(self) -> dict[str, Any]:diff --git a/src/xagent/core/memory/provenance.py b/src/xagent/core/memory/provenance.pynew file mode 100644index 000000000..6c4b2d427--- /dev/null+++ b/src/xagent/core/memory/provenance.py@@ -0,0 +1,94 @@+"""Host-supplied provenance for model-stored memories.++A trusted host may describe *where* a memory was learned (for example a+Slack channel versus a DM) so its users can later see, per memory, the place+and time it came from. The host returns that description from its memory+policy resolver (``MemoryPolicyDecision.memory_provenance``); the web layer+binds it to the run's ``store_memory`` tool, which copies it into each new+note's metadata under :data:`MEMORY_PROVENANCE_METADATA_KEY`. The note's own+``timestamp`` records *when*.++Provenance means "originally learned in": it is written once, when the note+is first stored, and never re-stamped. ``update_memory`` keeps it while+replacing the content, ``UserIsolatedMemoryStore.update`` restores the stored+value over whatever a caller sends, and the REST create endpoint drops a+client-supplied value -- so it is server-owned like ``user_id`` and the+``execution_scope_*`` stamps.++Provenance is descriptive only. It is never a namespace dimension: stores do+not filter on it, it is not part of any scope fingerprint, and it cannot widen+or narrow which memories a run may read.++Imports stay limited to ``core.execution_scope`` (plus the standard+library) so that ``web.services.memory_policy`` does not have to import the+agent runtime merely to validate a decision.+"""++from __future__ import annotations++import re+from collections.abc import Mapping+from types import MappingProxyType+from typing import TypeAlias++from ..execution_scope import validate_scope_component++# Note-metadata key under which host-supplied provenance is stored as a+# nested string mapping. Nested (not flat-prefixed) so provenance can never+# collide with ``user_id`` or the ``execution_scope_*`` isolation stamps, and+# is never mistaken for a namespace dimension by store filters.+MEMORY_PROVENANCE_METADATA_KEY = "provenance"++# Provenance values must look like ASCII identifiers (Slack ``C…``/``D…``/+# ``G…`` ids, Teams ``19:…@thread.tacv2`` / ``a:1…`` ids and thread ids such+# as ``19:…@thread.tacv2;messageid=…``, Feishu ``oc_…`` ids, numeric task+# ids). This is defense in depth against a host bug that+# passes conversation text: it rejects whitespace, non-ASCII scripts (so+# spaceless CJK sentences fail) and punctuation typical of prose, but it+# cannot prove a value is not content -- the host remains responsible for+# passing identifiers only (#2753).+_PROVENANCE_VALUE_RE = re.compile(r"[A-Za-z0-9._:;@/=+-]{1,256}")++MemoryProvenance: TypeAlias = Mapping[str, str]+"""Non-content identifiers describing where a memory was learned, e.g.+``{"channel_kind": "dm", "channel_id": "D123", "task_id": "42"}``."""+++def validate_memory_provenance(provenance: MemoryProvenance) -> MemoryProvenance:+ """Validate host provenance and return an immutable copy.++ Keys follow the execution-scope component grammar+ (``[a-zA-Z0-9_-]{1,63}``); values must match the ASCII identifier grammar+ ``[A-Za-z0-9._:;@/=+-]{1,256}``. The value grammar is defense in depth: it+ catches a host bug that passes free text (whitespace, non-ASCII scripts,+ prose punctuation), but an identifier-shaped string can still be content,+ so hosts must pass identifiers only. An empty mapping is rejected too -- a+ host with nothing to record passes ``None``.++ Raises:+ TypeError: ``provenance`` is not a mapping, is empty, or a value is+ not a string.+ ValueError: a key or value does not match its grammar+ (``InvalidScopeComponentError`` is a ``ValueError``).+ """+ if not isinstance(provenance, Mapping) or not provenance:+ raise TypeError("memory provenance must be a non-empty mapping")+ validated: dict[str, str] = {}+ for key, value in provenance.items():+ validate_scope_component(key, field_name="memory provenance key")+ if not isinstance(value, str):+ raise TypeError(f"memory provenance value for {key!r} must be a string")+ if not _PROVENANCE_VALUE_RE.fullmatch(value):+ raise ValueError(+ f"memory provenance value for {key!r} must be an ASCII "+ "identifier matching [A-Za-z0-9._:;@/=+-]{1,256}"+ )+ validated[key] = value+ return MappingProxyType(validated)+++__all__ = [+ "MEMORY_PROVENANCE_METADATA_KEY",+ "MemoryProvenance",+ "validate_memory_provenance",+]diff --git a/src/xagent/core/memory/retrieval_compatibility.py b/src/xagent/core/memory/retrieval_compatibility.pyindex 1c26f3d38..475fb7a61 100644--- a/src/xagent/core/memory/retrieval_compatibility.py+++ b/src/xagent/core/memory/retrieval_compatibility.py@@ -31,6 +31,7 @@ from typing import Any, Callable, Generator, Iterable, Iterator, Optional, Unionfrom ..tools.core.RAG_tools.LanceDB.schema_manager import _safe_close_tablefrom ..utils.lancedb_sql import sql_and+from .base import comparable_timestampfrom .core import MemoryNotefrom .scope_columns import build_scope_wherefrom .storage_admission import AdmittedLanceDBMemoryStore, DormantLanceDBMemoryHandle@@ -258,7 +259,8 @@ def stream_list_all(batch_size=batch_size,))- notes.sort(key=lambda note: note.timestamp, reverse=True)+ # Naive legacy and aware current timestamps cannot be compared directly.+ notes.sort(key=lambda note: comparable_timestamp(note.timestamp), reverse=True)return notesdiff --git a/src/xagent/web/api/memory.py b/src/xagent/web/api/memory.pyindex ccb70f46c..b96abc63a 100644--- a/src/xagent/web/api/memory.py+++ b/src/xagent/web/api/memory.py@@ -11,8 +11,9 @@ from fastapi import APIRouter, Depends, HTTPException, Path, Queryfrom pydantic import BaseModel, Field, field_validatorfrom starlette import convertors as starlette_url # codespell:ignore-from xagent.core.memory.base import MemoryStore+from xagent.core.memory.base import MemoryStore, comparable_timestampfrom xagent.core.memory.core import MemoryNote+from xagent.core.memory.provenance import MEMORY_PROVENANCE_METADATA_KEYfrom ..auth_dependencies import get_current_userfrom ..dynamic_memory_store import get_memory_store, get_memory_store_manager@@ -344,7 +345,10 @@ class MemoryManagementRouter:"keywords": memory.keywords,"tags": memory.tags,"category": memory.category,- "timestamp": memory.timestamp,+ # Legacy rows are naive server-local time; emit+ # every timestamp as aware UTC so clients never+ # reinterpret it in the viewer's timezone.+ "timestamp": comparable_timestamp(memory.timestamp),"mime_type": memory.mime_type,"metadata": memory.metadata,}@@ -513,6 +517,10 @@ class MemoryManagementRouter:category=memory_request.get("category", "general"),metadata=memory_request.get("metadata", {}),)+ # Provenance is server-owned (stamped only by the+ # store_memory tool from host policy); a client cannot+ # claim where a hand-written memory was learned.+ memory_note.metadata.pop(MEMORY_PROVENANCE_METADATA_KEY, None)# Embeds the note.async with usage_scope(@@ -598,7 +606,8 @@ class MemoryManagementRouter:"keywords": memory.keywords,"tags": memory.tags,"category": memory.category,- "timestamp": memory.timestamp,+ # Aware UTC, as in the list response.+ "timestamp": comparable_timestamp(memory.timestamp),"mime_type": memory.mime_type,"metadata": memory.metadata,}diff --git a/src/xagent/web/services/agent_service_manager.py b/src/xagent/web/services/agent_service_manager.pyindex 60ccb73bb..ddab48f9c 100644--- a/src/xagent/web/services/agent_service_manager.py+++ b/src/xagent/web/services/agent_service_manager.py@@ -7,6 +7,7 @@ import timefrom collections import dequefrom collections.abc import Sequencefrom dataclasses import dataclass+from functools import partialfrom itertools import countfrom pathlib import Pathfrom typing import Any, Callable, Dict, List, Mapping, Optional, TypeVar, Union, cast@@ -22,6 +23,7 @@ from ...config import (from ...core.agent.context.memory_retrieval import (MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY,)+from ...core.agent.context.memory_tool import build_memory_toolsfrom ...core.agent.service import AgentServicefrom ...core.agent.structured_output import StructuredOutputFormatfrom ...core.execution_scope import (@@ -39,6 +41,7 @@ from ...core.memory.access_scope import ()from ...core.memory.base import MemoryStorefrom ...core.memory.in_memory import InMemoryMemoryStore+from ...core.memory.provenance import MemoryProvenancefrom ...core.model.chat.basic.adapter import attach_chat_retry_wrapperfrom ...core.model.chat.basic.base import BaseLLMfrom ...core.model.chat.basic.deepseek import DeepSeekLLM@@ -326,11 +329,20 @@ def _optional_task_int(task: Any, field: str) -> int | None:def _adapt_memory_tools_factory(factory: MemoryToolFactory | None,+ *,+ provenance: MemoryProvenance | None,) -> Callable[..., list[Any]] | None:- """Adapt the public frozen request contract to the core runtime callback."""+ """Adapt the public frozen request contract to the core runtime callback.++ Without a host factory, provenance is bound onto core's default+ ``build_memory_tools``; with neither, ``None`` keeps the pattern on its+ built-in default path exactly as before provenance existed.+ """if factory is None:- return None+ if provenance is None:+ return None+ return partial(build_memory_tools, provenance=provenance)def build_tools(*,@@ -345,6 +357,9 @@ def _adapt_memory_tools_factory(task=task,runtime=runtime,context=context,+ # A plain dict: host factories may serialize or store it,+ # which a read-only mapping proxy would not survive.+ provenance=None if provenance is None else dict(provenance),))if isinstance(tools, (str, bytes)) or not isinstance(tools, Sequence):@@ -369,6 +384,7 @@ def _compose_memory_binding(policy_scope: MemoryAccessScope | None,enabled: bool,availability_reason: str | None,+ provenance: MemoryProvenance | None,) -> AgentServiceMemoryPolicy:"""Combine backend selection with the legacy eligibility authority.@@ -407,7 +423,9 @@ def _compose_memory_binding(memory_access_scope=selected_scope,backend_identity=binding.backend_identity,route_generation=binding.route_generation,- memory_tools_factory=_adapt_memory_tools_factory(binding.memory_tools_factory),+ memory_tools_factory=_adapt_memory_tools_factory(+ binding.memory_tools_factory, provenance=provenance+ ),)@@ -466,12 +484,14 @@ def resolve_agent_service_memory_policy(return _inert_memory_policy(MEMORY_BINDING_RESOLUTION_FAILURE_REASON)policy_scope = override.memory_access_scope if override is not None else None+ provenance = override.memory_provenance if override is not None else Noneif binding is not None:return _compose_memory_binding(binding=binding,policy_scope=policy_scope,enabled=enabled,availability_reason=None if override is None else override.reason,+ provenance=provenance,)try:@@ -511,6 +531,7 @@ def resolve_agent_service_memory_policy(memory_available=True if override is None else override.available,memory_availability_reason=None if override is None else override.reason,memory_access_scope=access_scope,+ memory_tools_factory=_adapt_memory_tools_factory(None, provenance=provenance),)diff --git a/src/xagent/web/services/memory_binding.py b/src/xagent/web/services/memory_binding.pyindex c3d877f07..b065dbb3d 100644--- a/src/xagent/web/services/memory_binding.py+++ b/src/xagent/web/services/memory_binding.py@@ -20,6 +20,7 @@ from typing import Any, TypeAliasfrom ...core.memory.access_scope import MemoryAccessScope, bind_memory_access_scopefrom ...core.memory.base import MemoryStore+from ...core.memory.provenance import MemoryProvenancefrom ...core.memory.scope_columns import strict_user_idfrom .db_runtime import run_db_io_cancellation_safe@@ -108,12 +109,19 @@ class MemoryToolAssemblyRequest:The factory is called synchronously during pattern setup and must notperform blocking I/O. Core copies the returned sequence before addingrun-local tools and marks the context for memory-usage guidance.++ ``provenance`` is a plain-dict copy of the task's validated+ ``MemoryPolicyDecision`` provenance (``None`` when the policy resolver+ supplied none). A factory+ that builds its own ``store_memory`` tool should forward it so notes carry+ the same provenance as the default tool set."""memory_store: MemoryStore = field(repr=False)task: strruntime: Any | None = field(default=None, repr=False)context: Any | None = field(default=None, repr=False)+ provenance: MemoryProvenance | None = Nonedef __post_init__(self) -> None:if not isinstance(self.memory_store, MemoryStore):diff --git a/src/xagent/web/services/memory_policy.py b/src/xagent/web/services/memory_policy.pyindex f76498e74..fbd1152ab 100644--- a/src/xagent/web/services/memory_policy.py+++ b/src/xagent/web/services/memory_policy.py@@ -11,6 +11,7 @@ from typing import Anyfrom ...core.execution_scope import ExecutionScopefrom ...core.memory.access_scope import MemoryAccessScope+from ...core.memory.provenance import MemoryProvenance, validate_memory_provenancefrom ...core.memory.scope_columns import strict_user_idlogger = logging.getLogger(__name__)@@ -35,12 +36,37 @@ class MemoryPolicyRequest:@dataclass(frozen=True)class MemoryPolicyDecision:- """Explicit memory eligibility and availability decision."""+ """Explicit memory eligibility and availability decision.++ ``memory_provenance`` optionally describes where memories stored during+ this task are learned (e.g. ``{"channel_kind": "dm", "channel_id": "D1"}``).+ The ``store_memory`` tool copies it into each new note's metadata under+ ``"provenance"``; see ``core.memory.provenance``. It is validated and+ frozen on construction: a value outside the ASCII identifier grammar fails+ the resolver (and therefore memory) closed. That grammar is defense in+ depth, not proof a value is not content; hosts must pass identifiers+ only. It is descriptive only and never affects which memories the task+ may read.++ Like ``memory_access_scope``, it requires enabled, available memory:+ hosts must leave ``memory_provenance`` unset (``None``) whenever they+ return ``enabled=False`` or ``available=False``, otherwise the decision+ is rejected and memory fails closed for the task.+ """enabled: boolavailable: boolreason: str | None = Nonememory_access_scope: MemoryAccessScope | None = None+ memory_provenance: MemoryProvenance | None = None++ def __post_init__(self) -> None:+ if self.memory_provenance is not None:+ object.__setattr__(+ self,+ "memory_provenance",+ validate_memory_provenance(self.memory_provenance),+ )MemoryPolicyResolver = Callable[[MemoryPolicyRequest], MemoryPolicyDecision]@@ -72,8 +98,15 @@ def resolve_trusted_memory_policy(decision = resolver(request)_validate_decision(decision)return decision- except Exception:- logger.warning("Trusted memory policy resolver failed")+ except Exception as exc:+ # Name the failure so a rejected decision (e.g. an invalid provenance+ # value) is diagnosable. Validation messages name the offending key+ # and grammar, never the rejected value, which may be content.+ logger.warning(+ "Trusted memory policy resolver failed (%s: %s)",+ type(exc).__name__,+ exc,+ )return MemoryPolicyDecision(enabled=False,available=False,@@ -102,6 +135,10 @@ def _validate_decision(decision: object) -> None:decision.enabled and decision.available):raise ValueError("memory access scope requires enabled, available memory")+ if decision.memory_provenance is not None and not (+ decision.enabled and decision.available+ ):+ raise ValueError("memory provenance requires enabled, available memory")def memory_retrieval_scope_fingerprint(diff --git a/src/xagent/web/user_isolated_memory.py b/src/xagent/web/user_isolated_memory.pyindex 159d1b7a6..1be77c097 100644--- a/src/xagent/web/user_isolated_memory.py+++ b/src/xagent/web/user_isolated_memory.py@@ -13,10 +13,20 @@ from xagent.core.execution_scope import (from xagent.core.memory.access_scope import MemoryAccessScopefrom xagent.core.memory.base import MemoryStorefrom xagent.core.memory.core import MemoryNote, MemoryResponse+from xagent.core.memory.provenance import MEMORY_PROVENANCE_METADATA_KEYfrom xagent.core.memory.scope_columns import SCOPE_EXCLUSIVE_FILTER_KEYfrom xagent.core.user_context import current_user_id+def _is_server_owned_metadata_key(key: str) -> bool:+ """Metadata a by-id update restores from the stored note: scope-dimension+ stamps and ``provenance`` (``user_id`` is re-stamped separately)."""+ return (+ key.startswith(MEMORY_DIMENSION_METADATA_PREFIX)+ or key == MEMORY_PROVENANCE_METADATA_KEY+ )++class UserIsolatedMemoryStore(MemoryStore):"""Memory store implementation that isolates memory by user ID using context.@@ -274,17 +284,18 @@ class UserIsolatedMemoryStore(MemoryStore):existing_isolation_metadata = {key: valuefor key, value in existing_response.content.metadata.items()- if key.startswith(MEMORY_DIMENSION_METADATA_PREFIX)+ if _is_server_owned_metadata_key(key)}- # Isolation metadata is server-owned. A caller may replace ordinary- # metadata, but cannot move an authenticated note to another owner (or- # to an invalid/ownerless value), nor add/remove its scope dimensions.- # An unscoped note stays unscoped: the stored set is restored even when- # it is empty.+ # Isolation metadata and provenance are server-owned. A caller may+ # replace ordinary metadata, but cannot move an authenticated note to+ # another owner (or to an invalid/ownerless value), add/remove its+ # scope dimensions, or forge/wipe where it was originally learned. An+ # unscoped (or provenance-less) note stays so: the stored set is+ # restored even when it is empty.if existing_isolation_metadata is not None:for key in tuple(note.metadata):- if key.startswith(MEMORY_DIMENSION_METADATA_PREFIX):+ if _is_server_owned_metadata_key(key):note.metadata.pop(key)note.metadata.update(existing_isolation_metadata)if user_id is not None:diff --git a/tests/core/agent/test_memory_tool.py b/tests/core/agent/test_memory_tool.pyindex 9a00ad3ff..505ce76f4 100644--- a/tests/core/agent/test_memory_tool.py+++ b/tests/core/agent/test_memory_tool.py@@ -1,6 +1,7 @@"""Tests for the model-invocable ``store_memory`` tool."""import asyncio+import jsonfrom typing import Any, castimport pytest@@ -18,6 +19,7 @@ from xagent.core.execution_scope import ExecutionScope, ExecutionScopeContextfrom xagent.core.memory.core import MemoryNote, MemoryResponsefrom xagent.core.memory.in_memory import InMemoryMemoryStorefrom xagent.core.memory.lancedb import LanceDBMemoryStore+from xagent.core.memory.provenance import validate_memory_provenancefrom xagent.core.model.embedding import BaseEmbeddingfrom xagent.web.user_isolated_memory import UserContext, UserIsolatedMemoryStore@@ -94,6 +96,79 @@ async def test_store_memory_adds_note_with_metadata() -> None:assert tool.stored_count == 1+async def test_store_memory_stamps_host_provenance() -> None:+ store = RecordingMemoryStore()+ provenance = validate_memory_provenance(+ {"channel_kind": "channel", "channel_id": "C123ABC", "task_id": "42"}+ )+ [tool, *_] = build_memory_tools(+ memory_store=store,+ task="Summarize what Alice said about the Q3 launch",+ provenance=provenance,+ )++ await tool.execute(content="Team ships on Thursdays.", kind="domain_insight")+ await tool.execute(content="User prefers bullet lists.", kind="user_preference")++ first, second = store.added+ assert first.metadata == {+ "kind": "domain_insight",+ "source": "store_memory",+ "provenance": {+ "channel_kind": "channel",+ "channel_id": "C123ABC",+ "task_id": "42",+ },+ }+ # Each note gets its own plain JSON-serializable copy.+ assert type(first.metadata["provenance"]) is dict+ assert first.metadata["provenance"] is not second.metadata["provenance"]+ # Neither the task request nor any other conversation text is stamped.+ serialized = json.dumps(first.metadata)+ assert "Alice" not in serialized+ assert "Q3 launch" not in serialized+++async def test_store_memory_without_provenance_keeps_legacy_metadata() -> None:+ store = RecordingMemoryStore()+ [tool, *_] = build_memory_tools(memory_store=store, task="task")++ await tool.execute(content="Team ships on Thursdays.", kind="domain_insight")++ assert store.added[0].metadata == {+ "kind": "domain_insight",+ "source": "store_memory",+ }+++async def test_store_memory_provenance_survives_lancedb_round_trip(+ tmp_path: Any,+) -> None:+ store = LanceDBMemoryStore(+ db_dir=str(tmp_path),+ collection_name="provenance_round_trip",+ embedding_model=_DeterministicEmbedding(),+ )+ tool = StoreMemoryTool(+ memory_store=store,+ task="task",+ provenance=validate_memory_provenance(+ {"channel_kind": "dm", "channel_id": "D42"}+ ),+ )++ result = await tool.execute(content="User prefers concise replies.")++ stored = store.get(result["memory_id"]).content+ assert stored.metadata["provenance"] == {"channel_kind": "dm", "channel_id": "D42"}+ assert stored.timestamp.utcoffset() is not None+ [listed] = store.list_all()+ assert listed.metadata["provenance"] == {"channel_kind": "dm", "channel_id": "D42"}++@pytest.mark.asyncioasync def test_store_memory_skips_duplicate() -> None:store = RecordingMemoryStore(search_results=[object()])diff --git a/tests/core/memory/test_in_memory.py b/tests/core/memory/test_in_memory.pyindex 41c313792..cc6ffc29d 100644--- a/tests/core/memory/test_in_memory.py+++ b/tests/core/memory/test_in_memory.py@@ -562,6 +562,25 @@ class TestSearchListOnlyFilterParity:n.id for n in memory_store.list_all(filters={"date_from": cutoff_utc})] == ["new-home"]+ def test_list_all_orders_naive_legacy_and_aware_utc_rows(self, memory_store):+ # Rows written before UTC timestamps are naive server-local time;+ # new rows are aware UTC. list_all must order the mix newest-first+ # instead of raising TypeError on a naive/aware comparison.+ between = (self.now - timedelta(days=1)).astimezone(timezone.utc)+ memory_store.add(+ MemoryNote(id="aware-middle", content="aware report", timestamp=between)+ )+ memory_store.add(+ MemoryNote(id="aware-default", content="default timestamp report")+ )++ assert [n.id for n in memory_store.list_all()] == [+ "aware-default",+ "new-home",+ "aware-middle",+ "old-work",+ ]+def test_timezone_aware_stored_timestamp_with_naive_filter(self, memory_store):# The other direction: an aware stored timestamp must compare against# a naive filter value.diff --git a/tests/core/memory/test_lancedb.py b/tests/core/memory/test_lancedb.pyindex 3e551b645..b2f615a8e 100644--- a/tests/core/memory/test_lancedb.py+++ b/tests/core/memory/test_lancedb.py@@ -780,6 +780,25 @@ class TestSearchListOnlyFilterParity:n.id for n in parity_store.list_all(filters={"date_from": cutoff_utc})] == ["new-home"]+ def test_list_all_orders_naive_legacy_and_aware_utc_rows(self, parity_store):+ # Rows written before UTC timestamps are naive server-local time;+ # new rows are aware UTC. list_all must order the mix newest-first+ # instead of raising TypeError on a naive/aware comparison.+ between = (self.now - timedelta(days=1)).astimezone(timezone.utc)+ assert parity_store.add(+ MemoryNote(id="aware-middle", content="aware report", timestamp=between)+ ).success+ assert parity_store.add(+ MemoryNote(id="aware-default", content="default timestamp report")+ ).success++ assert [n.id for n in parity_store.list_all()] == [+ "aware-default",+ "new-home",+ "aware-middle",+ "old-work",+ ]+def test_timezone_aware_stored_timestamp_with_naive_filter(self, parity_store):# The other direction: an aware stored timestamp must compare against# a naive filter value.diff --git a/tests/core/memory/test_provenance.py b/tests/core/memory/test_provenance.pynew file mode 100644index 000000000..5c1889122--- /dev/null+++ b/tests/core/memory/test_provenance.py@@ -0,0 +1,74 @@+"""Tests for host memory provenance validation."""++from types import MappingProxyType+from typing import Any++import pytest++from xagent.core.memory.provenance import validate_memory_provenance+++def test_validate_memory_provenance_returns_frozen_copy() -> None:+ source = {"channel_kind": "dm", "channel_id": "D123ABC", "task_id": "42"}++ validated = validate_memory_provenance(source)++ assert isinstance(validated, MappingProxyType)+ assert dict(validated) == source+ # A later host-side mutation cannot reach notes stored from the copy.+ source["channel_id"] = "C999"+ assert validated["channel_id"] == "D123ABC"+++ "identifier",+ [+ "C0123ABCD", # Slack public channel+ "D0123ABCD", # Slack DM+ "G0123ABCD", # Slack group DM / private channel+ "19:[email protected]", # Teams channel conversation+ "19:[email protected];messageid=1700000000000", # Teams thread+ "a:1Xyz-AbC_dEf+gh/ij=", # Teams personal conversation+ "oc_5ad11d72b830411d72b836c20", # Feishu chat+ "42", # task id+ ],+)+def test_validate_memory_provenance_accepts_platform_identifiers(+ identifier: str,+) -> None:+ assert validate_memory_provenance({"channel_id": identifier})["channel_id"] == (+ identifier+ )+++ "provenance",+ [+ # Conversation text can never pass the identifier grammar (#2753).+ {"channel_id": "please remember my salary is 100k"},+ {"note": "line\nbreak"},+ # Spaceless prose: non-ASCII scripts and prose punctuation fail too.+ {"channel_id": "我的银行卡密码是123456请帮我记住"},+ {"channel_id": "remember_this,it's_my_pin!"},+ {"channel_id": "café"},+ {"channel_id": ""},+ {"channel_id": "x" * 257},+ {"bad key": "C1"},+ {"": "C1"},+ {"channel:id": "C1"},+ ],+)+def test_validate_memory_provenance_rejects_text_and_bad_keys(+ provenance: dict[str, str],+) -> None:+ with pytest.raises(ValueError):+ validate_memory_provenance(provenance)+++ "provenance",+ [{}, {"task_id": 42}, {"channel_id": None}, ["channel_id", "C1"]],+)+def test_validate_memory_provenance_rejects_wrong_shapes(provenance: Any) -> None:+ with pytest.raises(TypeError):+ validate_memory_provenance(provenance)diff --git a/tests/core/memory/test_timestamps.py b/tests/core/memory/test_timestamps.pynew file mode 100644index 000000000..0ffc08b60--- /dev/null+++ b/tests/core/memory/test_timestamps.py@@ -0,0 +1,101 @@+"""Tests for UTC memory note timestamps coexisting with naive legacy rows."""++import os+import time+from collections.abc import Iterator+from datetime import datetime, timedelta, timezone++import pytest++from xagent.core.memory.base import comparable_timestamp+from xagent.core.memory.core import MemoryNote+from xagent.core.memory.in_memory import InMemoryMemoryStore++UTC = timezone.utc+++def new_york_tz() -> Iterator[None]:+ """Pin the process timezone so naive legacy timestamps have a known+ meaning (EST is UTC-5 in January) regardless of the CI host's zone."""+ previous = os.environ.get("TZ")+ os.environ["TZ"] = "America/New_York"+ time.tzset()+ yield+ if previous is None:+ del os.environ["TZ"]+ else:+ os.environ["TZ"] = previous+ time.tzset()+++def test_new_memory_note_timestamp_is_utc_aware() -> None:+ note = MemoryNote(content="x")++ assert note.timestamp.tzinfo is not None+ assert note.timestamp.utcoffset() == timedelta(0)++[email protected]("new_york_tz")+def test_comparable_timestamp_reads_naive_as_server_local_time() -> None:+ # A legacy naive 09:30 written by a New York server is 14:30 UTC.+ assert comparable_timestamp(datetime(2026, 1, 15, 9, 30)) == datetime(+ 2026, 1, 15, 14, 30, tzinfo=UTC+ )+ aware = datetime(2026, 1, 15, 9, 30, tzinfo=timezone(timedelta(hours=8)))+ assert comparable_timestamp(aware) == datetime(2026, 1, 15, 1, 30, tzinfo=UTC)+ assert comparable_timestamp("not a datetime") == "not a datetime"++[email protected]("new_york_tz")+def test_comparable_timestamp_orders_naive_legacy_against_aware_utc() -> None:+ naive_earlier = datetime(2026, 1, 15, 9, 0) # 14:00 UTC+ aware_middle = datetime(2026, 1, 15, 14, 15, tzinfo=UTC)+ naive_later = datetime(2026, 1, 15, 9, 30) # 14:30 UTC++ ordered = sorted(+ [naive_later, aware_middle, naive_earlier], key=comparable_timestamp+ )++ assert ordered == [naive_earlier, aware_middle, naive_later]+++ ("value", "expected"),+ [+ (datetime.min, datetime.min.replace(tzinfo=UTC)),+ (datetime.max, datetime.max.replace(tzinfo=UTC)),+ (+ datetime.min.replace(tzinfo=timezone(timedelta(hours=5))),+ datetime.min.replace(tzinfo=UTC),+ ),+ (+ datetime.max.replace(tzinfo=timezone(timedelta(hours=-5))),+ datetime.max.replace(tzinfo=UTC),+ ),+ ],+ ids=("naive-min", "naive-max", "aware-min", "aware-max"),+)[email protected]("new_york_tz")+def test_comparable_timestamp_clamps_unrepresentable_extremes(+ value: datetime, expected: datetime+) -> None:+ assert comparable_timestamp(value) == expected++[email protected]("new_york_tz")+def test_extreme_date_filters_mean_unbounded() -> None:+ store = InMemoryMemoryStore()+ store.add(MemoryNote(id="legacy", content="a", timestamp=datetime(2026, 1, 1)))+ store.add(MemoryNote(id="current", content="b"))++ filters = {"date_from": datetime.min, "date_to": datetime.max}++ assert {note.id for note in store.list_all(filters=filters)} == {+ "legacy",+ "current",+ }+ assert {note.id for note in store.search("", k=10, filters=filters)} == {+ "legacy",+ "current",+ }diff --git a/tests/web/services/test_memory_policy.py b/tests/web/services/test_memory_policy.pyindex 90b3e7452..c53fc94f7 100644--- a/tests/web/services/test_memory_policy.py+++ b/tests/web/services/test_memory_policy.py@@ -208,6 +208,7 @@ def test_compose_memory_binding_preserves_matching_scope_authority() -> None:policy_scope=scope,enabled=True,availability_reason=None,+ provenance=None,)assert policy.memory is binding.store@@ -231,6 +232,7 @@ def test_compose_memory_binding_binds_policy_scope_when_binding_has_none() -> Nopolicy_scope=scope,enabled=True,availability_reason=None,+ provenance=None,)assert policy.memory is not binding.store@@ -257,6 +259,7 @@ def test_compose_memory_binding_rejects_conflicting_scope_authorities() -> None:),enabled=True,availability_reason=None,+ provenance=None,)assert policy.memory_enabled is False@@ -784,6 +787,11 @@ def test_resolver_exception_fails_closed_for_preview() -> None:memory_dimensions={"principal": "person-1"},),),+ MemoryPolicyDecision(+ enabled=False,+ available=True,+ memory_provenance={"channel_id": "C1"},+ ),],ids=("wrong-type",@@ -793,6 +801,7 @@ def test_resolver_exception_fails_closed_for_preview() -> None:"non-bool-flag","malformed-access-scope","scope-while-disabled",+ "provenance-while-disabled",),)def test_invalid_resolver_decision_fails_closed(@@ -812,6 +821,232 @@ def test_invalid_resolver_decision_fails_closed(get_memory_store.assert_not_called()+async def test_resolver_provenance_is_stamped_by_default_store_memory_tool(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ store = InMemoryMemoryStore()+ monkeypatch.setattr(+ agent_runtime_service, "get_memory_store", Mock(return_value=store)+ )+ host_provenance = {"channel_kind": "channel", "channel_id": "C42", "task_id": "17"}+ set_trusted_memory_policy_resolver(+ lambda _request: MemoryPolicyDecision(+ enabled=True,+ available=True,+ memory_provenance=host_provenance,+ )+ )++ policy = agent_runtime_service.resolve_agent_service_memory_policy(task=_task())+ # The decision froze its own copy; a later host mutation cannot leak in.+ host_provenance["channel_id"] = "C-mutated"++ assert policy.memory is store+ assert policy.memory_tools_factory is not None+ tools = policy.memory_tools_factory(+ memory_store=policy.memory,+ task="what did Bob say in the standup?",+ runtime=None,+ context=None,+ )+ assert [tool.name for tool in tools] == [+ "store_memory",+ "search_memory",+ "update_memory",+ "delete_memory",+ ]+ result = await tools[0].execute(content="Standups are at 10:00 UTC.")++ note = store.get(result["memory_id"]).content+ assert note.metadata["provenance"] == {+ "channel_kind": "channel",+ "channel_id": "C42",+ "task_id": "17",+ }+ assert "Bob" not in str(note.metadata)+++def test_resolver_without_provenance_keeps_builtin_memory_tool_path(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setattr(+ agent_runtime_service,+ "get_memory_store",+ Mock(return_value=InMemoryMemoryStore()),+ )+ set_trusted_memory_policy_resolver(+ lambda _request: MemoryPolicyDecision(enabled=True, available=True)+ )++ policy = agent_runtime_service.resolve_agent_service_memory_policy(task=_task())++ # No factory: ReAct builds its default tool set exactly as before.+ assert policy.memory_tools_factory is None+++def test_resolver_provenance_carrying_text_fails_closed(+ monkeypatch: pytest.MonkeyPatch,+ caplog: pytest.LogCaptureFixture,+) -> None:+ get_memory_store = Mock(name="get-memory-store")+ monkeypatch.setattr(agent_runtime_service, "get_memory_store", get_memory_store)+ set_trusted_memory_policy_resolver(+ lambda _request: MemoryPolicyDecision(+ enabled=True,+ available=True,+ memory_provenance={"channel_id": "please remember my password"},+ )+ )++ with caplog.at_level("WARNING"):+ policy = agent_runtime_service.resolve_agent_service_memory_policy(task=_task())++ # The failure is diagnosable (names the key and grammar) without echoing+ # the rejected value, which may be conversation content.+ assert "ValueError" in caplog.text+ assert "memory provenance value for 'channel_id'" in caplog.text+ assert "please remember my password" not in caplog.text+ assert isinstance(policy.memory, InMemoryMemoryStore)+ assert policy.memory_enabled is False+ assert policy.memory_available is False+ assert policy.memory_availability_reason == MEMORY_POLICY_RESOLVER_FAILURE_REASON+ get_memory_store.assert_not_called()+++def test_binding_tool_factory_receives_policy_provenance() -> None:+ seen: list[MemoryToolAssemblyRequest] = []++ def factory(request: MemoryToolAssemblyRequest) -> list[object]:+ seen.append(request)+ return []++ set_trusted_memory_binding_resolver(+ lambda _request: MemoryStoreBinding(+ store=InMemoryMemoryStore(),+ backend_identity="backend-a",+ route_generation="route-1",+ memory_tools_factory=factory,+ )+ )+ set_trusted_memory_policy_resolver(+ lambda _request: MemoryPolicyDecision(+ enabled=True,+ available=True,+ memory_provenance={"channel_kind": "dm", "channel_id": "D7"},+ )+ )++ policy = agent_runtime_service.resolve_agent_service_memory_policy(task=_task())+ assert policy.memory_tools_factory is not None+ policy.memory_tools_factory(+ memory_store=policy.memory, task="t", runtime=None, context=None+ )++ [request] = seen+ # A plain dict copy, so host factories can serialize or keep it.+ assert type(request.provenance) is dict+ assert request.provenance == {"channel_kind": "dm", "channel_id": "D7"}+++async def test_binding_without_tool_factory_binds_provenance_to_default_tools() -> None:+ store = InMemoryMemoryStore()+ set_trusted_memory_binding_resolver(+ lambda _request: MemoryStoreBinding(+ store=store,+ backend_identity="backend-a",+ route_generation="route-1",+ )+ )+ set_trusted_memory_policy_resolver(+ lambda _request: MemoryPolicyDecision(+ enabled=True,+ available=True,+ memory_provenance={"channel_kind": "dm", "channel_id": "D7"},+ )+ )++ policy = agent_runtime_service.resolve_agent_service_memory_policy(task=_task())++ assert policy.memory is store+ assert policy.memory_tools_factory is not None+ tools = policy.memory_tools_factory(+ memory_store=policy.memory, task="t", runtime=None, context=None+ )+ assert [tool.name for tool in tools] == [+ "store_memory",+ "search_memory",+ "update_memory",+ "delete_memory",+ ]+ result = await tools[0].execute(content="User prefers short answers.")+ assert store.get(result["memory_id"]).content.metadata["provenance"] == {+ "channel_kind": "dm",+ "channel_id": "D7",+ }+++async def test_cached_service_picks_up_and_drops_provenance_across_turns(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ store = InMemoryMemoryStore()+ monkeypatch.setattr(+ agent_runtime_service, "get_memory_store", Mock(return_value=store)+ )+ turn_provenance: dict[str, Any] = {"value": {"channel_id": "C1"}}+ set_trusted_memory_policy_resolver(+ lambda _request: MemoryPolicyDecision(+ enabled=True,+ available=True,+ memory_provenance=turn_provenance["value"],+ )+ )+ service = AgentService(+ name="cached",+ id="web_task_17",+ tools=[],+ enable_workspace=False,+ memory=InMemoryMemoryStore(),+ )+ service._execution_adapter = service._build_execution_adapter()+ manager = agent_runtime_service.AgentServiceManager()+ manager._agents[17] = service++ async def reconcile() -> None:+ await manager._reconcile_cached_agent_memory_policy(+ 17,+ task=_task(),+ agent_config={},+ ambient_owner_user_id=23,+ ambient_execution_scope=None,+ )++ def store_tool_provenance() -> dict[str, str] | None:+ factory = service.memory_tools_factory+ assert service._execution_adapter.config.memory_tools_factory is factory+ if factory is None:+ return None+ [store_tool, *_] = factory(+ memory_store=store, task="t", runtime=None, context=None+ )+ return dict(store_tool.provenance)++ await reconcile()+ assert store_tool_provenance() == {"channel_id": "C1"}++ # A later turn without provenance falls back to the built-in tool path.+ turn_provenance["value"] = None+ await reconcile()+ assert store_tool_provenance() is None++ # And a turn from another channel picks up that channel's provenance.+ turn_provenance["value"] = {"channel_id": "D2"}+ await reconcile()+ assert store_tool_provenance() == {"channel_id": "D2"}++def test_resolver_receives_none_for_missing_or_nonprimitive_task_fields() -> None:resolver = Mock(return_value=MemoryPolicyDecision(diff --git a/tests/web/test_memory_api.py b/tests/web/test_memory_api.pyindex a3c994d64..8864180e0 100644--- a/tests/web/test_memory_api.py+++ b/tests/web/test_memory_api.py@@ -3,8 +3,9 @@import jsonimport osimport tempfile+import timefrom collections.abc import Iterator-from datetime import datetime+from datetime import datetime, timedelta, timezonefrom typing import Anyfrom unittest.mock import Mockfrom urllib.parse import quote@@ -124,6 +125,21 @@ def auth_headers(test_db):return {"Authorization": f"Bearer {token}"}+def new_york_tz() -> Iterator[None]:+ """Pin the server timezone so naive legacy timestamps have a known+ instant (EST is UTC-5 in January) regardless of the CI host's zone."""+ previous = os.environ.get("TZ")+ os.environ["TZ"] = "America/New_York"+ time.tzset()+ yield+ if previous is None:+ del os.environ["TZ"]+ else:+ os.environ["TZ"] = previous+ time.tzset()++@pytest.fixturedef mock_memory_store():"""Create a mock memory store for testing."""@@ -363,6 +379,53 @@ class TestMemoryListEndpoint:# Ensure context field is not presentassert "context" not in memory+ def test_list_and_get_surface_provenance_and_utc_timestamp(+ self, client, mock_memory_store, auth_headers, new_york_tz+ ):+ """Provenance lives in metadata and is returned verbatim; every+ timestamp, including a naive legacy one, is serialized as aware UTC."""+ provenance = {"channel_kind": "dm", "channel_id": "D123", "task_id": "9"}+ aware = MemoryNote(+ id=MEMORY_ID_1,+ content="User prefers concise replies.",+ category="react_memory",+ metadata={+ "kind": "user_preference",+ "source": "store_memory",+ "provenance": provenance,+ },+ timestamp=datetime(2026, 11, 13, 8, 30, tzinfo=timezone.utc),+ )+ legacy = MemoryNote(+ id=MEMORY_ID_2,+ content="Legacy note.",+ timestamp=datetime(2026, 1, 1, 8, 30),+ )+ mock_memory_store.list_all.return_value = [aware, legacy]+ mock_memory_store.get.return_value = Mock(+ success=True, memory_id=MEMORY_ID_1, content=aware+ )++ listed = client.get("/api/memory/list", headers=auth_headers).json()+ fetched = client.get(f"/api/memory/{MEMORY_ID_1}", headers=auth_headers)++ first, second = listed["memories"]+ assert first["metadata"]["provenance"] == provenance+ # Both the aware row and the naive legacy row are emitted as aware+ # UTC, so browsers never reinterpret a legacy row in viewer-local time:+ # naive 08:30 written by a New York (EST, UTC-5) server is 13:30 UTC.+ first_ts = datetime.fromisoformat(first["timestamp"])+ assert first_ts == datetime(2026, 11, 13, 8, 30, tzinfo=timezone.utc)+ assert first_ts.utcoffset() == timedelta(0)+ legacy_ts = datetime.fromisoformat(second["timestamp"])+ assert legacy_ts == datetime(2026, 1, 1, 13, 30, tzinfo=timezone.utc)+ assert legacy_ts.utcoffset() == timedelta(0)+ assert fetched.status_code == 200+ assert fetched.json()["metadata"]["provenance"] == provenance+ assert datetime.fromisoformat(fetched.json()["timestamp"]) == datetime(+ 2026, 11, 13, 8, 30, tzinfo=timezone.utc+ )+def test_list_memories_with_category_filter(self, client, mock_memory_store, auth_headers):@@ -577,6 +640,29 @@ class TestMemoryCreateEndpoint:assert call_args.content == "New test memory"assert call_args.category == "general"+ def test_create_memory_drops_client_supplied_provenance(+ self, client, mock_memory_store, auth_headers+ ):+ """Provenance is server-owned: a client cannot claim where a+ hand-written memory was learned."""+ mock_memory_store.add.return_value = Mock(success=True, memory_id="new-1")++ response = client.post(+ "/api/memory/",+ json={+ "content": "Forged origin",+ "metadata": {+ "source": "test",+ "provenance": {"channel_kind": "dm", "channel_id": "D-forged"},+ },+ },+ headers=auth_headers,+ )++ assert response.status_code == 200+ note = mock_memory_store.add.call_args[0][0]+ assert note.metadata == {"source": "test"}+def test_create_memory_with_defaults(self, client, mock_memory_store, auth_headers):"""Test memory creation with default values."""mock_memory_store.add.return_value = Mock(diff --git a/tests/web/test_user_isolated_in_memory.py b/tests/web/test_user_isolated_in_memory.pyindex 4e13bdaa2..1ea008f3b 100644--- a/tests/web/test_user_isolated_in_memory.py+++ b/tests/web/test_user_isolated_in_memory.py@@ -78,3 +78,42 @@ class TestUserIsolationOnInMemoryPath:# pre-existing behavior for non-web callers.results = seeded_store.list_all()assert {n.id for n in results} == {"a1", "a2", "b1"}+++class TestProvenanceIsServerOwned:+ """``provenance`` records where a memory was originally learned; a by-id+ update (e.g. the REST PUT, which replaces metadata wholesale) can neither+ forge nor wipe it, mirroring the user_id / scope-dimension stamps."""++ def test_update_restores_stored_provenance(self, store):+ original = {"channel_kind": "channel", "channel_id": "C1"}+ with UserContext(1):+ store.add(+ MemoryNote(id="p1", content="old", metadata={"provenance": original})+ )+ forged = MemoryNote(+ id="p1",+ content="new",+ metadata={"source": "api", "provenance": {"channel_id": "D-forged"}},+ )+ assert store.update(forged).success+ wiped = MemoryNote(id="p1", content="newer", metadata={})+ assert store.update(wiped).success++ stored = store.get("p1").content+ assert stored.content == "newer"+ assert stored.metadata["provenance"] == original++ def test_update_cannot_add_provenance_to_a_note_without_one(self, store):+ with UserContext(1):+ store.add(MemoryNote(id="n1", content="hand-written"))+ assert store.update(+ MemoryNote(+ id="n1",+ content="edited",+ metadata={"provenance": {"channel_id": "C-forged"}},+ )+ ).success++ stored = store.get("n1").content+ assert "provenance" not in stored.metadata