Skip to content

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.py
index 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_args
from pydantic import BaseModel, Field
from ...memory.core import MemoryNote
+from ...memory.provenance import MEMORY_PROVENANCE_METADATA_KEY, MemoryProvenance
from ..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_NAME
description = _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_store
self.task = task
@@ -102,6 +113,7 @@ class StoreMemoryTool:
self.category = category
self.max_stores = max_stores
self.dedup_distance_threshold = dedup_distance_threshold
+ self.provenance = provenance
self.stored_count = 0
self._store_lock = asyncio.Lock()
@@ -205,16 +217,18 @@ class StoreMemoryTool:
return results[0] if results else None
def _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_NAME
description = (
@@ -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 the
memory-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.py
index 6342955fa..710f65a5d 100644
--- a/src/xagent/core/memory/base.py
+++ b/src/xagent/core/memory/base.py
@@ -1,7 +1,7 @@
from __future__ import annotations
from abc import ABC, abstractmethod
-from datetime import datetime
+from datetime import MINYEAR, datetime, timezone
from typing import Any, Collection, List, Optional
from .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.py
index e34973185..6528356e7 100644
--- a/src/xagent/core/memory/core.py
+++ b/src/xagent/core/memory/core.py
@@ -1,7 +1,7 @@
from __future__ import annotations
import uuid
-from datetime import datetime
+from datetime import datetime, timezone
from typing import Any, Optional, Union
from 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.py
index 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 annotations
import uuid
from typing import Any, List, Optional
-from .base import MemoryStore
+from .base import MemoryStore, comparable_timestamp
from .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 results
diff --git a/src/xagent/core/memory/lancedb.py b/src/xagent/core/memory/lancedb.py
index 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_adapter
from ..model.model import EmbeddingModelConfig
from ..tools.core.RAG_tools.LanceDB.schema_manager import _safe_close_table
from ..utils.lancedb_sql import sql_string_literal
-from .base import MemoryStore
+from .base import MemoryStore, comparable_timestamp
from .core import MemoryNote, MemoryResponse
from .retrieval_compatibility import DEFAULT_STREAM_BATCH_SIZE, stream_lexical_top_k
from .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 notes
def get_stats(self) -> dict[str, Any]:
diff --git a/src/xagent/core/memory/provenance.py b/src/xagent/core/memory/provenance.py
new file mode 100644
index 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.py
index 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, Union
from ..tools.core.RAG_tools.LanceDB.schema_manager import _safe_close_table
from ..utils.lancedb_sql import sql_and
+from .base import comparable_timestamp
from .core import MemoryNote
from .scope_columns import build_scope_where
from .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 notes
diff --git a/src/xagent/web/api/memory.py b/src/xagent/web/api/memory.py
index 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, Query
from pydantic import BaseModel, Field, field_validator
from starlette import convertors as starlette_url # codespell:ignore
-from xagent.core.memory.base import MemoryStore
+from xagent.core.memory.base import MemoryStore, comparable_timestamp
from xagent.core.memory.core import MemoryNote
+from xagent.core.memory.provenance import MEMORY_PROVENANCE_METADATA_KEY
from ..auth_dependencies import get_current_user
from ..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.py
index 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 time
from collections import deque
from collections.abc import Sequence
from dataclasses import dataclass
+from functools import partial
from itertools import count
from pathlib import Path
from 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_tools
from ...core.agent.service import AgentService
from ...core.agent.structured_output import StructuredOutputFormat
from ...core.execution_scope import (
@@ -39,6 +41,7 @@ from ...core.memory.access_scope import (
)
from ...core.memory.base import MemoryStore
from ...core.memory.in_memory import InMemoryMemoryStore
+from ...core.memory.provenance import MemoryProvenance
from ...core.model.chat.basic.adapter import attach_chat_retry_wrapper
from ...core.model.chat.basic.base import BaseLLM
from ...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 None
if 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.py
index 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, TypeAlias
from ...core.memory.access_scope import MemoryAccessScope, bind_memory_access_scope
from ...core.memory.base import MemoryStore
+from ...core.memory.provenance import MemoryProvenance
from ...core.memory.scope_columns import strict_user_id
from .db_runtime import run_db_io_cancellation_safe
@@ -108,12 +109,19 @@ class MemoryToolAssemblyRequest:
The factory is called synchronously during pattern setup and must not
perform blocking I/O. Core copies the returned sequence before adding
run-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: str
runtime: Any | None = field(default=None, repr=False)
context: Any | None = field(default=None, repr=False)
+ provenance: MemoryProvenance | None = None
def __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.py
index 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 Any
from ...core.execution_scope import ExecutionScope
from ...core.memory.access_scope import MemoryAccessScope
+from ...core.memory.provenance import MemoryProvenance, validate_memory_provenance
from ...core.memory.scope_columns import strict_user_id
logger = 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: bool
available: bool
reason: str | None = None
memory_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.py
index 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 MemoryAccessScope
from xagent.core.memory.base import MemoryStore
from xagent.core.memory.core import MemoryNote, MemoryResponse
+from xagent.core.memory.provenance import MEMORY_PROVENANCE_METADATA_KEY
from xagent.core.memory.scope_columns import SCOPE_EXCLUSIVE_FILTER_KEY
from 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: value
for 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.py
index 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 json
from typing import Any, cast
import pytest
@@ -18,6 +19,7 @@ from xagent.core.execution_scope import ExecutionScope, ExecutionScopeContext
from xagent.core.memory.core import MemoryNote, MemoryResponse
from xagent.core.memory.in_memory import InMemoryMemoryStore
from xagent.core.memory.lancedb import LanceDBMemoryStore
+from xagent.core.memory.provenance import validate_memory_provenance
from xagent.core.model.embedding import BaseEmbedding
from 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.asyncio
async 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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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() -> No
policy_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.py
index a3c994d64..8864180e0 100644
--- a/tests/web/test_memory_api.py
+++ b/tests/web/test_memory_api.py
@@ -3,8 +3,9 @@
import json
import os
import tempfile
+import time
from collections.abc import Iterator
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
from typing import Any
from unittest.mock import Mock
from 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.fixture
def mock_memory_store():
"""Create a mock memory store for testing."""
@@ -363,6 +379,53 @@ class TestMemoryListEndpoint:
# Ensure context field is not present
assert "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.py
index 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