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

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

@@ -5,6 +5,84 @@ 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.
+
+### Added
+
+- **Shared database support**: `MemoryManager` and `AsyncMemoryManager` accept an optional `db=` keyword argument to inject an existing `GrafeoDB` instance instead of creating one internally. `close()` respects ownership and leaves externally provided databases open ([#18](https://github.com/GrafeoDB/grafeo-memory/issues/18), [#19](https://github.com/GrafeoDB/grafeo-memory/pull/19), thanks [@Michaelzag](https://github.com/Michaelzag))
+- **Multi-tenant safety**: all internal operations are now scoped to Memory and Entity nodes, making it safe to share a database with non-memory data
+
+### Fixed
+
+- **Graph metrics pollution**: `_recompute_graph_metrics()` now writes `_pagerank`, `_betweenness`, `_community` only to Memory/Entity nodes instead of every node in the database
+- **Unlabeled Cypher queries**: `temporal_chain()` and `_get_node_relations()` now require `:Memory` labels on match patterns, preventing traversal from foreign nodes
+- **N+1 entity lookup**: `_find_or_create_entity` and `graph_search` replaced global `find_nodes_by_property` + Python filtering with single label-scoped Cypher queries, reducing FFI crossings
+- **Stats data leak**: `_stats_impl()` no longer exposes raw `db.info()`, returning only memory-scoped counts. MCP `memory://stats` resource now delegates to the manager's scoped stats
+- **Error surfacing tests**: broken embedder on add/search now verified to raise, not silently return empty results
+- **Persistence lifecycle tests**: write, close, reopen round-trip with `tmp_path`
+- **Multi-session regression tests**: sequential open/close/open guards against event loop corruption
+- **Concurrency tests**: concurrent async adds for same user (lock verification) and different users (isolation)
+- **Reconciliation boundary test**: controlled embeddings at threshold boundary verify UPDATE triggers
+- **History ordering test**: LEADS_TO chain verified for session-order retrieval
+- **Delete cascade test**: orphaned entity behavior after memory deletion documented
+- **Memory type filter test**: search with `memory_type` filter verified
+- **Summarize test**: non-empty summary from related memories
+- **MCP tool smoke tests**: all tool functions imported and called with mock context
+
+### Changed
+
+- `test_search_with_broken_embedder` now uses `pytest.raises` instead of silently passing
+- Concurrency tests use `async with` context manager for guaranteed cleanup
+- Error surfacing tests wrapped in `try/finally` for manager cleanup
+- Shared `make_manager` helper extracted to `conftest.py`
+- README: added model compatibility table (OpenAI, Anthropic, Mistral, Groq, Google)
+- README: documented reconciliation threshold tuning and `history()` return type
+- 435 tests passing
+
 ## [0.2.0] - 2026-03-26
 
 Temporal reasoning, multi-hop search and engine integration for better long running memory performance.
@@ -197,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.0 → grafeo_memory-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grafeo-memory
-Version: 0.2.0
+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
@@ -183,6 +183,18 @@ MemoryManager("google-gla:gemini-2.0-flash", config, embedder=embedder)
 
 Both accept an optional `model` parameter to override the default.
 
+### Which model works best?
+
+| Provider | Combined extraction | Individual extraction | Notes |
+| --- | --- | --- | --- |
+| OpenAI (gpt-4o-mini) | Works | Works | Recommended default |
+| Anthropic (claude-sonnet) | Works | Works | Untested in CI |
+| Mistral (mistral-small) | Falls back | Works | 3 API calls instead of 1 |
+| Groq | Unknown | Unknown | Needs testing |
+| Google | Unknown | Unknown | Needs testing |
+
+grafeo-memory tries a single "combined" LLM call first (facts + entities + relations in one schema). If the model cannot handle the combined schema, it falls back to separate calls automatically. Mistral models typically trigger this fallback, which means 3 API calls per `add()` instead of 1. The fallback is silent (logged at DEBUG level, no traceback printed).
+
 ## Custom Embeddings
 
 Implement the `EmbeddingClient` protocol to use any embedding provider:
@@ -306,7 +318,7 @@ config = MemoryConfig(instrument=InstrumentationSettings(
 - `.delete(memory_id)` → `bool`
 - `.delete_all(user_id=None)` → `int` (count deleted)
 - `.summarize(user_id=None, *, preserve_recent=5, batch_size=20)` → `AddResult`
-- `.history(memory_id)` → `list[HistoryEntry]`
+- `.history(memory_id)` → `list[HistoryEntry]`: returns change history sorted by timestamp (oldest first)
 - `.set_importance(memory_id, importance)` → `bool`
 - `.close()`: close the database
 
@@ -318,7 +330,7 @@ Use as a context manager: `with MemoryManager(...) as memory:`. Multiple session
 - `user_id`: default user scope (default `"default"`)
 - `session_id`: default session scope
 - `agent_id`: default agent scope
-- `reconciliation_threshold`: minimum similarity for reconciliation candidates (default 0.3)
+- `reconciliation_threshold`: minimum cosine similarity (0.0 to 1.0) for a memory to be considered a reconciliation candidate during `add()`. Lower values find more candidates, higher values require closer matches. At 0.3 (default), loosely related memories are considered. At 0.7+, only very similar memories trigger UPDATE/DELETE decisions
 - `search_min_score`: minimum score for search results, 0.0 returns everything (default 0.0)
 - `agreement_bonus`: score boost when both vector and graph find the same memory (default 0.1)
 - `embedding_dimensions`: vector dimensions (default 1536)
@@ -340,7 +352,7 @@ Use as a context manager: `with MemoryManager(...) as memory:`. Multiple session
 - **`SearchResponse`**: list subclass of `SearchResult`, with `.usage` for LLM token counts
 - **`MemoryEvent`**: `.action` (ADD/UPDATE/DELETE/NONE), `.memory_id`, `.text`, `.old_text`
 - **`SearchResult`**: `.memory_id`, `.text`, `.score`, `.user_id`, `.metadata`, `.relations`, `.memory_type`
-- **`HistoryEntry`**: `.event`, `.old_text`, `.new_text`, `.timestamp`, `.actor_id`, `.role`
+- **`HistoryEntry`**: `.event` (ADD/UPDATE/DELETE), `.old_text`, `.new_text`, `.timestamp` (epoch ms), `.actor_id`, `.role`. Returned sorted by timestamp ascending (oldest first)
 
 ### Iteration
 

{grafeo_memory-0.2.0 → grafeo_memory-0.2.2}/README.md

@@ -145,6 +145,18 @@ MemoryManager("google-gla:gemini-2.0-flash", config, embedder=embedder)
 
 Both accept an optional `model` parameter to override the default.
 
+### Which model works best?
+
+| Provider | Combined extraction | Individual extraction | Notes |
+| --- | --- | --- | --- |
+| OpenAI (gpt-4o-mini) | Works | Works | Recommended default |
+| Anthropic (claude-sonnet) | Works | Works | Untested in CI |
+| Mistral (mistral-small) | Falls back | Works | 3 API calls instead of 1 |
+| Groq | Unknown | Unknown | Needs testing |
+| Google | Unknown | Unknown | Needs testing |
+
+grafeo-memory tries a single "combined" LLM call first (facts + entities + relations in one schema). If the model cannot handle the combined schema, it falls back to separate calls automatically. Mistral models typically trigger this fallback, which means 3 API calls per `add()` instead of 1. The fallback is silent (logged at DEBUG level, no traceback printed).
+
 ## Custom Embeddings
 
 Implement the `EmbeddingClient` protocol to use any embedding provider:
@@ -268,7 +280,7 @@ config = MemoryConfig(instrument=InstrumentationSettings(
 - `.delete(memory_id)` → `bool`
 - `.delete_all(user_id=None)` → `int` (count deleted)
 - `.summarize(user_id=None, *, preserve_recent=5, batch_size=20)` → `AddResult`
-- `.history(memory_id)` → `list[HistoryEntry]`
+- `.history(memory_id)` → `list[HistoryEntry]`: returns change history sorted by timestamp (oldest first)
 - `.set_importance(memory_id, importance)` → `bool`
 - `.close()`: close the database
 
@@ -280,7 +292,7 @@ Use as a context manager: `with MemoryManager(...) as memory:`. Multiple session
 - `user_id`: default user scope (default `"default"`)
 - `session_id`: default session scope
 - `agent_id`: default agent scope
-- `reconciliation_threshold`: minimum similarity for reconciliation candidates (default 0.3)
+- `reconciliation_threshold`: minimum cosine similarity (0.0 to 1.0) for a memory to be considered a reconciliation candidate during `add()`. Lower values find more candidates, higher values require closer matches. At 0.3 (default), loosely related memories are considered. At 0.7+, only very similar memories trigger UPDATE/DELETE decisions
 - `search_min_score`: minimum score for search results, 0.0 returns everything (default 0.0)
 - `agreement_bonus`: score boost when both vector and graph find the same memory (default 0.1)
 - `embedding_dimensions`: vector dimensions (default 1536)
@@ -302,7 +314,7 @@ Use as a context manager: `with MemoryManager(...) as memory:`. Multiple session
 - **`SearchResponse`**: list subclass of `SearchResult`, with `.usage` for LLM token counts
 - **`MemoryEvent`**: `.action` (ADD/UPDATE/DELETE/NONE), `.memory_id`, `.text`, `.old_text`
 - **`SearchResult`**: `.memory_id`, `.text`, `.score`, `.user_id`, `.metadata`, `.relations`, `.memory_type`
-- **`HistoryEntry`**: `.event`, `.old_text`, `.new_text`, `.timestamp`, `.actor_id`, `.role`
+- **`HistoryEntry`**: `.event` (ADD/UPDATE/DELETE), `.old_text`, `.new_text`, `.timestamp` (epoch ms), `.actor_id`, `.role`. Returned sorted by timestamp ascending (oldest first)
 
 ### Iteration
 

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.0 → grafeo_memory-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "grafeo-memory"
-version = "0.2.0"
+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.0 → 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.0 → 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",