grafeo-memory 0.2.1__tar.gz → 0.2.2__tar.gz

{grafeo_memory-0.2.1 → grafeo_memory-0.2.2}/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to grafeo-memory are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2026-04-08
+
+Bi-temporal validity tracking, episode-based provenance, and community summaries for richer temporal knowledge graphs.
+
+### Added
+
+- **Bi-temporal model** (opt-in): every Memory node can now carry `valid_at` (when the fact became true in reality) and `invalid_at` (when it ceased being true), orthogonal to the existing system-time properties `created_at`/`expired_at`. Enable with `enable_bitemporal=True`
+- **Temporal annotation extraction**: new LLM step parses real-world dates from message context (ISO-8601, year-only, relative dates) and attaches them to extracted facts. New module `extraction/temporal.py` with `annotate_temporal_async()`
+- **Point-in-time queries**: `search(query, point_in_time=epoch_ms)` filters to facts that were valid at a specific moment. Memories with no `valid_at` are included permissively (backward compatible)
+- **Point-in-time hint detection**: `detect_temporal_hints()` now recognizes "as of", "at that time", "back then", "in YYYY" patterns and sets `point_in_time_hint=True` with automatic expired-memory inclusion
+- **Episode provenance** (opt-in): `add()` creates `:Episode` nodes storing the raw message text, linked to produced memories via `PRODUCED` edges and to extracted entities via `MENTIONS` edges. Enable with `enable_episodes=True`
+- **Session replay via episodes**: `NEXT_EPISODE` edges chain episodes within a run. When episodes are enabled, `LEADS_TO` edges between memories are no longer created (episodes handle session ordering)
+- **`get_episodes()`**: retrieve all episodes for a user, optionally filtered by `session_id`
+- **`get_provenance(memory_id)`**: trace any memory back to the raw episode that produced it
+- **`episode_chain(episode_id, direction)`**: follow `NEXT_EPISODE` edges forward, backward, or both for session replay
+- **Community summaries** (opt-in): after Louvain community detection, creates `:Community` nodes with LLM-generated `name` and `summary` for entity clusters (>= 2 members). Lazy materialization on next `search()`. Enable with `enable_community_summaries=True` (requires `enable_graph_algorithms=True`)
+- **`get_communities()`**: retrieve all detected communities and their summaries
+- **Community context in search**: relevant community summaries are discoverable via `get_community_context()` for entity-based lookups
+- New node labels: `Episode`, `Community`
+- New edge types: `PRODUCED`, `MENTIONS`, `NEXT_EPISODE`, `HAS_MEMBER`
+- New config options: `enable_bitemporal`, `enable_episodes`, `enable_community_summaries`
+- New types: `EpisodeResult`, `CommunityInfo`, `TemporalAnnotation`, `TemporalAnnotationOutput`, `CommunitySummaryOutput`
+- New exports: `EPISODE_LABEL`, `PRODUCED_EDGE`, `MENTIONS_EDGE`, `NEXT_EPISODE_EDGE`, `COMMUNITY_LABEL`, `HAS_MEMBER_EDGE`, `EpisodeResult`, `CommunityInfo`
+- New modules: `extraction/temporal.py`, `communities.py`
+- New prompts: `TEMPORAL_ANNOTATION_SYSTEM/USER`, `COMMUNITY_SUMMARY_SYSTEM/USER`
+- **`graph_name` scoping**: optional `graph_name` on `MemoryConfig` isolates memories and entities per subgraph when multiple callers share a database via `db=`. Stamped on all Memory and Entity creates, filtered on all read paths (`_build_filters`, `graph_search`, `temporal_chain`, session linking, `stats`). No behavior change when unset ([#23](https://github.com/GrafeoDB/grafeo-memory/issues/23), [#24](https://github.com/GrafeoDB/grafeo-memory/pull/24), thanks [@Michaelzag](https://github.com/Michaelzag))
+- `graph_name` added to property index list for fast scoped lookups
+- 15 new tests covering `graph_name` write stamping, read isolation, entity separation, stats scoping, temporal chain boundaries, and backward compatibility
+
+### Changed
+
+- `SearchResult` gains two new fields: `valid_at`, `invalid_at` (both default `None`, backward compatible)
+- `MemoryEvent` gains `valid_at` field (default `None`, backward compatible)
+- `ExtractionResult` gains `temporal_annotations` field (default empty dict, backward compatible)
+- `MemoryStats` gains `episode_count` and `community_count` fields (both default 0)
+- `search()`, `explain()` gain `point_in_time` keyword parameter on both `MemoryManager` and `AsyncMemoryManager`
+- `_expire_memory()` sets `invalid_at` on the expired node when bi-temporal mode is enabled
+- `_execute_decisions()` passes `valid_at` from temporal annotations to new memories and sets `invalid_at` on superseded memories
+- `_stats_impl()` now counts Episode and Community nodes
+- `db_info` in stats includes `episode_node_count` and `community_node_count`
+- MCP `memory_search` tool gains `point_in_time` parameter
+
 ## [0.2.1] - 2026-04-07
 
 Test quality, error surfacing, documentation improvements, and shared database support.
@@ -233,6 +275,8 @@ Initial release.
 - **Windows async compatibility**: persistent `asyncio.Runner` and `ProactorEventLoop` safety net for Python 3.13+
 - 230 tests, 83% coverage
 
+[Unreleased]: https://github.com/GrafeoDB/grafeo-memory/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/GrafeoDB/grafeo-memory/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/GrafeoDB/grafeo-memory/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/GrafeoDB/grafeo-memory/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/GrafeoDB/grafeo-memory/compare/v0.1.3...v0.1.4

{grafeo_memory-0.2.1 → grafeo_memory-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grafeo-memory
-Version: 0.2.1
+Version: 0.2.2
 Summary: AI memory layer powered by GrafeoDB's hybrid graph and vector database
 Project-URL: Homepage, https://github.com/GrafeoDB/grafeo-memory
 Project-URL: Repository, https://github.com/GrafeoDB/grafeo-memory

grafeo_memory-0.2.2/examples/temporal_bench.py

@@ -0,0 +1,129 @@
+"""Quick benchmark for temporal knowledge graph features.
+
+Exercises:
+  1. Bi-temporal model (valid_at/invalid_at, point-in-time queries)
+  2. Episode provenance (Episode nodes, PRODUCED edges, session replay)
+
+Requires:
+    MISTRAL_API_KEY in .env
+"""
+
+from __future__ import annotations
+
+import time
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from mistralai import Mistral  # noqa: E402
+
+from grafeo_memory import MemoryConfig, MemoryManager, MistralEmbedder  # noqa: E402
+
+
+def main():
+    client = Mistral()
+    embedder = MistralEmbedder(client)
+
+    config = MemoryConfig(
+        user_id="markus",
+        enable_bitemporal=True,
+        enable_episodes=True,
+        run_id="bench_run_1",
+    )
+
+    t0 = time.perf_counter()
+
+    with MemoryManager("mistral:mistral-small-latest", config, embedder=embedder) as mem:
+        # ------------------------------------------------------------------
+        # Phase 1: Bi-temporal -- add facts with real-world dates
+        # ------------------------------------------------------------------
+        print("=== Phase 1: Bi-Temporal ===\n")
+
+        msgs = [
+            "Markus joined Acme Corp as a software engineer in March 2022.",
+            "Markus was promoted to senior engineer at Acme Corp in January 2024.",
+            "Markus left Acme and joined Globex Industries in September 2024.",
+            "Markus started learning Rust in 2023, he previously only knew Python and Go.",
+        ]
+
+        for msg in msgs:
+            t1 = time.perf_counter()
+            events = mem.add(msg)
+            dt = (time.perf_counter() - t1) * 1000
+            for e in events:
+                va = f"  valid_at={e.valid_at}" if e.valid_at else ""
+                print(f"  [{e.action.value.upper():6s}] {e.text}{va}")
+                if e.old_text:
+                    print(f"           was: {e.old_text}")
+            print(f"  ({dt:.0f}ms)\n")
+
+        # Point-in-time search: "as of mid-2023"
+        from datetime import UTC, datetime
+
+        mid_2023 = int(datetime(2023, 7, 1, tzinfo=UTC).timestamp() * 1000)
+        print("Search: 'Where does Markus work?' (point_in_time=2023-07-01)")
+        results = mem.search("Where does Markus work?", point_in_time=mid_2023)
+        for r in results[:3]:
+            va = f"  valid_at={r.valid_at}" if r.valid_at else ""
+            ia = f"  invalid_at={r.invalid_at}" if r.invalid_at else ""
+            print(f"  [{r.score:.2f}] {r.text}{va}{ia}")
+        print()
+
+        # Current search (no point_in_time)
+        print("Search: 'Where does Markus work?' (current)")
+        results = mem.search("Where does Markus work?")
+        for r in results[:3]:
+            va = f"  valid_at={r.valid_at}" if r.valid_at else ""
+            print(f"  [{r.score:.2f}] {r.text}{va}")
+        print()
+
+        # ------------------------------------------------------------------
+        # Phase 2: Episode provenance
+        # ------------------------------------------------------------------
+        print("=== Phase 2: Episode Provenance ===\n")
+
+        episodes = mem.get_episodes()
+        print(f"Episodes created: {len(episodes)}")
+        for ep in episodes:
+            print(f"  [{ep.episode_id}] {ep.content[:60]}...")
+            print(f"    produced: {ep.produced_memories}")
+            print(f"    mentions: {ep.mentioned_entities}")
+        print()
+
+        # Session replay
+        if episodes:
+            print("Episode chain (forward from first):")
+            chain = mem.episode_chain(episodes[0].episode_id, direction="forward")
+            for ep in chain:
+                print(f"  -> [{ep.episode_id}] {ep.content[:50]}...")
+            print()
+
+            # Provenance
+            memories = mem.get_all()
+            if memories:
+                mid = memories[0].memory_id
+                prov = mem.get_provenance(mid)
+                print(f"Provenance for memory '{memories[0].text[:40]}...':")
+                for ep in prov:
+                    print(f"  <- Episode [{ep.episode_id}] {ep.content[:50]}...")
+                print()
+
+        # ------------------------------------------------------------------
+        # Stats
+        # ------------------------------------------------------------------
+        print("=== Stats ===\n")
+        stats = mem.stats()
+        print(f"  Memories:    {stats.total_memories}")
+        print(f"  Entities:    {stats.entity_count}")
+        print(f"  Relations:   {stats.relation_count}")
+        print(f"  Episodes:    {stats.episode_count}")
+        print(f"  Communities: {stats.community_count}")
+        print()
+
+    total = (time.perf_counter() - t0) * 1000
+    print(f"Total time: {total:.0f}ms")
+
+
+if __name__ == "__main__":
+    main()

{grafeo_memory-0.2.1 → grafeo_memory-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "grafeo-memory"
-version = "0.2.1"
+version = "0.2.2"
 description = "AI memory layer powered by GrafeoDB's hybrid graph and vector database"
 readme = "README.md"
 license = "Apache-2.0"

{grafeo_memory-0.2.1 → grafeo_memory-0.2.2}/src/grafeo_memory/__init__.py

@@ -16,11 +16,19 @@ from .scoring import (
 )
 from .temporal import TemporalHints, detect_temporal_hints
 from .types import (
+    COMMUNITY_LABEL,
+    EPISODE_LABEL,
+    HAS_MEMBER_EDGE,
     LEADS_TO_EDGE,
+    MENTIONS_EDGE,
+    NEXT_EPISODE_EDGE,
+    PRODUCED_EDGE,
     SUPERSEDES_EDGE,
     AddResult,
+    CommunityInfo,
     EntitiesOutput,
     Entity,
+    EpisodeResult,
     ExplainResult,
     ExplainStep,
     ExtractionResult,
@@ -39,13 +47,21 @@ from .types import (
 )
 
 __all__ = [
+    "COMMUNITY_LABEL",
+    "EPISODE_LABEL",
+    "HAS_MEMBER_EDGE",
     "LEADS_TO_EDGE",
+    "MENTIONS_EDGE",
+    "NEXT_EPISODE_EDGE",
+    "PRODUCED_EDGE",
     "SUPERSEDES_EDGE",
     "AddResult",
     "AsyncMemoryManager",
+    "CommunityInfo",
     "EmbeddingClient",
     "EntitiesOutput",
     "Entity",
+    "EpisodeResult",
     "ExplainResult",
     "ExplainStep",
     "ExtractionResult",
@@ -80,4 +96,4 @@ __all__ = [
     "detect_temporal_hints",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

grafeo_memory-0.2.2/src/grafeo_memory/communities.py

@@ -0,0 +1,283 @@
+"""Community lifecycle: detect, summarize, and query entity clusters."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from pydantic_ai import Agent
+
+from .prompts import COMMUNITY_SUMMARY_SYSTEM, COMMUNITY_SUMMARY_USER
+from .schemas import CommunitySummaryOutput
+from .search.vector import _get_props
+from .types import (
+    COMMUNITY_LABEL,
+    ENTITY_LABEL,
+    HAS_MEMBER_EDGE,
+    RELATION_EDGE,
+    CommunityInfo,
+    ModelType,
+)
+
+if TYPE_CHECKING:
+    from pydantic_ai.usage import RunUsage
+
+    from .protocol import GrafeoDBProtocol
+
+logger = logging.getLogger(__name__)
+
+
+async def materialize_communities_async(
+    db: GrafeoDBProtocol,
+    model: ModelType,
+    user_id: str,
+    louvain_result: dict,
+    *,
+    _on_usage: Callable[[str, RunUsage], None] | None = None,
+) -> list[CommunityInfo]:
+    """Create/update Community nodes from Louvain partition results.
+
+    Only communities with >= 2 members are materialized.
+    Summaries are regenerated only when membership changes.
+    """
+    communities_map = louvain_result.get("communities", {})
+    if not communities_map:
+        return []
+
+    # Group entity node IDs by community_id
+    clusters: dict[int, list[int]] = {}
+    for node_id, community_id in communities_map.items():
+        clusters.setdefault(community_id, []).append(node_id)
+
+    # Only process entities belonging to this user
+    entity_nodes: dict[int, dict] = {}
+    try:
+        for node_id, props in db.get_nodes_by_label(ENTITY_LABEL):
+            if props.get("user_id") == user_id:
+                entity_nodes[node_id] = props
+    except Exception:
+        return []
+
+    # Existing community nodes
+    existing_communities: dict[int, tuple[int, int]] = {}  # community_id -> (node_id, member_count)
+    try:
+        for node_id, props in db.get_nodes_by_label(COMMUNITY_LABEL):
+            if props.get("user_id") == user_id:
+                cid = props.get("community_id")
+                if cid is not None:
+                    existing_communities[int(cid)] = (node_id, int(props.get("member_count", 0)))
+    except Exception:
+        pass
+
+    results: list[CommunityInfo] = []
+    active_cids: set[int] = set()
+
+    for cid, member_ids in clusters.items():
+        # Filter to only entity nodes for this user
+        user_members = [nid for nid in member_ids if nid in entity_nodes]
+        if len(user_members) < 2:
+            continue
+
+        active_cids.add(cid)
+        member_names = [entity_nodes[nid].get("name", "") for nid in user_members]
+
+        # Check if community already exists with same membership
+        if cid in existing_communities:
+            existing_nid, existing_count = existing_communities[cid]
+            if existing_count == len(user_members):
+                # Membership unchanged, read existing summary
+                node = db.get_node(existing_nid)
+                if node is not None:
+                    props = _get_props(node)
+                    results.append(
+                        CommunityInfo(
+                            community_id=str(cid),
+                            name=props.get("name", ""),
+                            summary=props.get("summary", ""),
+                            member_count=existing_count,
+                            member_entities=member_names,
+                        )
+                    )
+                continue
+
+        # Collect relations between members for context
+        relation_texts: list[str] = []
+        for nid in user_members:
+            try:
+                query = (
+                    f"MATCH (a:{ENTITY_LABEL})-[r:{RELATION_EDGE}]->(b:{ENTITY_LABEL}) "
+                    f"WHERE id(a) = $nid RETURN a.name, r.relation_type, b.name"
+                )
+                for row in db.execute(query, {"nid": nid}):
+                    if isinstance(row, dict):
+                        vals = list(row.values())
+                        if len(vals) >= 3:
+                            relation_texts.append(f"{vals[0]} -> {vals[1]} -> {vals[2]}")
+            except Exception:
+                pass
+
+        # Generate summary via LLM
+        entities_text = "\n".join(f"- {n}" for n in member_names)
+        relations_text = "\n".join(f"- {r}" for r in relation_texts) if relation_texts else "(no relationships)"
+
+        agent = Agent(model, system_prompt=COMMUNITY_SUMMARY_SYSTEM, output_type=CommunitySummaryOutput)
+        try:
+            result = await agent.run(COMMUNITY_SUMMARY_USER.format(entities=entities_text, relations=relations_text))
+        except Exception:
+            logger.warning("Community summary generation failed for cid=%s", cid, exc_info=True)
+            continue
+
+        if _on_usage is not None:
+            _on_usage("community_summary", result.usage())
+
+        name = result.output.name
+        summary = result.output.summary
+
+        import time
+
+        now_ms = int(time.time() * 1000)
+
+        # Create or update community node
+        if cid in existing_communities:
+            existing_nid, _ = existing_communities[cid]
+            db.set_node_property(existing_nid, "name", name)
+            db.set_node_property(existing_nid, "summary", summary)
+            db.set_node_property(existing_nid, "member_count", len(user_members))
+            db.set_node_property(existing_nid, "updated_at", now_ms)
+            community_nid = existing_nid
+            # Delete old HAS_MEMBER edges
+            try:
+                del_query = (
+                    f"MATCH (c:{COMMUNITY_LABEL})-[r:{HAS_MEMBER_EDGE}]->(:{ENTITY_LABEL}) "
+                    f"WHERE id(c) = $cid RETURN id(r)"
+                )
+                for row in db.execute(del_query, {"cid": existing_nid}):
+                    if isinstance(row, dict):
+                        vals = list(row.values())
+                        if vals:
+                            with contextlib.suppress(Exception):
+                                db.delete_edge(int(vals[0]))
+            except Exception:
+                pass
+        else:
+            node = db.create_node(
+                [COMMUNITY_LABEL],
+                {
+                    "name": name,
+                    "summary": summary,
+                    "community_id": cid,
+                    "member_count": len(user_members),
+                    "user_id": user_id,
+                    "created_at": now_ms,
+                    "updated_at": now_ms,
+                },
+            )
+            community_nid = node.id if hasattr(node, "id") else node
+
+        # Create HAS_MEMBER edges
+        for nid in user_members:
+            with contextlib.suppress(Exception):
+                db.create_edge(community_nid, nid, HAS_MEMBER_EDGE)
+
+        results.append(
+            CommunityInfo(
+                community_id=str(cid),
+                name=name,
+                summary=summary,
+                member_count=len(user_members),
+                member_entities=member_names,
+            )
+        )
+
+    # Delete dissolved communities (existing but no longer active)
+    for cid, (existing_nid, _) in existing_communities.items():
+        if cid not in active_cids:
+            with contextlib.suppress(Exception):
+                db.delete_node(existing_nid)
+
+    return results
+
+
+def get_communities(db: GrafeoDBProtocol, user_id: str) -> list[CommunityInfo]:
+    """Retrieve all Community nodes for a user."""
+    try:
+        nodes = db.get_nodes_by_label(COMMUNITY_LABEL)
+    except Exception:
+        return []
+
+    results: list[CommunityInfo] = []
+    for node_id, props in nodes:
+        if props.get("user_id") != user_id:
+            continue
+
+        # Collect member entity names
+        member_names: list[str] = []
+        try:
+            query = (
+                f"MATCH (c:{COMMUNITY_LABEL})-[:{HAS_MEMBER_EDGE}]->(e:{ENTITY_LABEL}) WHERE id(c) = $cid RETURN e.name"
+            )
+            for row in db.execute(query, {"cid": node_id}):
+                if isinstance(row, dict):
+                    vals = list(row.values())
+                    if vals and vals[0]:
+                        member_names.append(str(vals[0]))
+        except Exception:
+            pass
+
+        results.append(
+            CommunityInfo(
+                community_id=str(props.get("community_id", node_id)),
+                name=props.get("name", ""),
+                summary=props.get("summary", ""),
+                member_count=int(props.get("member_count", 0)),
+                member_entities=member_names,
+            )
+        )
+    return results
+
+
+def get_community_context(db: GrafeoDBProtocol, entity_names: list[str], user_id: str) -> list[CommunityInfo]:
+    """Find communities that contain any of the given entities."""
+    if not entity_names:
+        return []
+
+    try:
+        nodes = db.get_nodes_by_label(COMMUNITY_LABEL)
+    except Exception:
+        return []
+
+    name_set = {n.lower() for n in entity_names}
+    results: list[CommunityInfo] = []
+
+    for node_id, props in nodes:
+        if props.get("user_id") != user_id:
+            continue
+
+        # Check if any member entity matches
+        member_names: list[str] = []
+        try:
+            query = (
+                f"MATCH (c:{COMMUNITY_LABEL})-[:{HAS_MEMBER_EDGE}]->(e:{ENTITY_LABEL}) WHERE id(c) = $cid RETURN e.name"
+            )
+            for row in db.execute(query, {"cid": node_id}):
+                if isinstance(row, dict):
+                    vals = list(row.values())
+                    if vals and vals[0]:
+                        member_names.append(str(vals[0]))
+        except Exception:
+            pass
+
+        if any(m.lower() in name_set for m in member_names):
+            results.append(
+                CommunityInfo(
+                    community_id=str(props.get("community_id", node_id)),
+                    name=props.get("name", ""),
+                    summary=props.get("summary", ""),
+                    member_count=int(props.get("member_count", 0)),
+                    member_entities=member_names,
+                )
+            )
+
+    return results

{grafeo_memory-0.2.1 → grafeo_memory-0.2.2}/src/grafeo_memory/extraction/__init__.py

@@ -2,8 +2,11 @@
 
 from .entities import extract, extract_async, extract_entities, extract_entities_async
 from .facts import extract_facts, extract_facts_async
+from .temporal import annotate_temporal, annotate_temporal_async
 
 __all__ = [
+    "annotate_temporal",
+    "annotate_temporal_async",
     "extract",
     "extract_async",
     "extract_entities",

grafeo_memory-0.2.2/src/grafeo_memory/extraction/temporal.py

@@ -0,0 +1,113 @@
+"""Temporal annotation extraction: identify when facts became true/ceased being true."""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable
+from datetime import UTC, date, datetime
+from typing import TYPE_CHECKING
+
+from pydantic_ai import Agent
+
+from .._compat import run_sync
+from ..prompts import TEMPORAL_ANNOTATION_SYSTEM, TEMPORAL_ANNOTATION_USER
+from ..schemas import TemporalAnnotationOutput
+from ..types import Fact, ModelType
+
+if TYPE_CHECKING:
+    from pydantic_ai.usage import RunUsage
+
+logger = logging.getLogger(__name__)
+
+_YEAR_ONLY_RE = re.compile(r"^\d{4}$")
+
+
+def _parse_date_to_epoch_ms(date_str: str | None) -> int | None:
+    """Parse an ISO-8601 date string (or year-only) to epoch milliseconds.
+
+    Returns None for unparseable or null input.
+    """
+    if not date_str:
+        return None
+
+    date_str = date_str.strip()
+
+    # Year-only: "2024" -> Jan 1 of that year
+    if _YEAR_ONLY_RE.match(date_str):
+        try:
+            dt = datetime(int(date_str), 1, 1, tzinfo=UTC)
+            return int(dt.timestamp() * 1000)
+        except (ValueError, OverflowError):
+            return None
+
+    # ISO-8601 date: "2024-01-15"
+    try:
+        d = date.fromisoformat(date_str)
+        dt = datetime(d.year, d.month, d.day, tzinfo=UTC)
+        return int(dt.timestamp() * 1000)
+    except ValueError:
+        pass
+
+    # ISO-8601 datetime: "2024-01-15T10:30:00"
+    try:
+        dt = datetime.fromisoformat(date_str)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=UTC)
+        return int(dt.timestamp() * 1000)
+    except ValueError:
+        pass
+
+    logger.debug("Could not parse date string: %r", date_str)
+    return None
+
+
+async def annotate_temporal_async(
+    model: ModelType,
+    facts: list[Fact],
+    original_text: str,
+    *,
+    today: str | None = None,
+    _on_usage: Callable[[str, RunUsage], None] | None = None,
+) -> dict[int, tuple[int | None, int | None]]:
+    """Annotate extracted facts with real-world validity timestamps.
+
+    Returns a mapping of fact_index -> (valid_at_ms, invalid_at_ms).
+    Only facts with detected temporal information are included.
+    """
+    if not facts:
+        return {}
+
+    today_str = today or date.today().isoformat()
+    facts_text = "\n".join(f"{i}. {f.text}" for i, f in enumerate(facts))
+
+    agent = Agent(model, system_prompt=TEMPORAL_ANNOTATION_SYSTEM, output_type=TemporalAnnotationOutput)
+    try:
+        result = await agent.run(TEMPORAL_ANNOTATION_USER.format(today=today_str, text=original_text, facts=facts_text))
+    except Exception:
+        logger.warning("Temporal annotation failed", exc_info=True)
+        return {}
+
+    if _on_usage is not None:
+        _on_usage("annotate_temporal", result.usage())
+
+    annotations: dict[int, tuple[int | None, int | None]] = {}
+    for ann in result.output.annotations:
+        valid_ms = _parse_date_to_epoch_ms(ann.valid_at)
+        invalid_ms = _parse_date_to_epoch_ms(ann.invalid_at)
+        if valid_ms is not None or invalid_ms is not None:
+            annotations[ann.fact_index] = (valid_ms, invalid_ms)
+
+    return annotations
+
+
+def annotate_temporal(
+    model: ModelType,
+    facts: list[Fact],
+    original_text: str,
+    *,
+    today: str | None = None,
+    _on_usage: Callable[[str, RunUsage], None] | None = None,
+) -> dict[int, tuple[int | None, int | None]]:
+    """Annotate extracted facts with real-world validity timestamps (sync)."""
+    return run_sync(annotate_temporal_async(model, facts, original_text, today=today, _on_usage=_on_usage))