sessions-graph 0.1.0__py3-none-any.whl

sessions_graph/__init__.py

@@ -0,0 +1,39 @@
+"""Sessions Graph: Cross-session memory store for agents, backed by Memgraph.
+
+Quick start::
+
+    from sessions_graph import SessionsGraph, Memory
+
+    graph = SessionsGraph()
+    graph.setup()
+
+    mem = graph.save_memory(user_id="alice", content="Prefers Python over TypeScript")
+    results = graph.search_memories(user_id="alice", query="Python")
+
+Integration with Agent Context Graph::
+
+    from sessions_graph import SessionsGraph
+    from sessions_graph.connector import SessionsGraphConnector
+    from agent_context_graph import AgentLink
+    from agent_context_graph.adapters.claude import ClaudeAdapter
+
+    graph = SessionsGraph()
+    graph.setup()
+
+    connector = SessionsGraphConnector(graph)
+    link = AgentLink()
+    link.add_connector(connector)
+    adapter = ClaudeAdapter(link, session_id="s-1", session_kwargs={"user_id": "alice"})
+
+    # Memory writes and recalls go through the Python API:
+    graph.save_memory(
+        user_id=connector.active_user_id,
+        content="User works in the ai-toolkit repo",
+        session_id=connector.active_session_id,
+    )
+"""
+
+from .core import SessionsGraph
+from .models import Memory, MemoryValidationError
+
+__all__ = ["Memory", "MemoryValidationError", "SessionsGraph"]

sessions_graph/connector.py

@@ -0,0 +1,117 @@
+"""Agent Context Graph connector for SessionsGraph.
+
+The connector is intentionally thin: it watches ``SessionStartEvent`` and
+``SessionEndEvent`` to MERGE ``(:User)`` and ``(:Session)`` nodes so that
+provenance relationships can be wired when memories are saved.  Memory writes
+themselves happen through the :class:`SessionsGraph` Python API directly,
+not through the event stream.
+
+Usage::
+
+    from sessions_graph import SessionsGraph
+    from sessions_graph.connector import SessionsGraphConnector
+    from agent_context_graph import AgentLink
+    from agent_context_graph.adapters.claude import ClaudeAdapter
+
+    graph = SessionsGraph()
+    graph.setup()
+
+    connector = SessionsGraphConnector(graph)
+
+    link = AgentLink()
+    link.add_connector(connector)
+    adapter = ClaudeAdapter(link, session_id="s-1", session_kwargs={"user_id": "alice"})
+
+    # Later, from within the agent:
+    graph.save_memory(
+        user_id=connector.active_user_id,
+        content="User prefers concise answers",
+        session_id=connector.active_session_id,
+    )
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agent_context_graph.events import Event, EventType, SessionEndEvent, SessionStartEvent
+from agent_context_graph.protocols import GraphConnector
+
+if TYPE_CHECKING:
+    from .core import SessionsGraph
+
+
+_SUPPORTED_EVENTS = {EventType.SESSION_START, EventType.SESSION_END}
+
+
+class SessionsGraphConnector(GraphConnector):
+    """Receives Agent Context Graph session events for memory provenance.
+
+    On ``SESSION_START``:
+      - MERGEs ``(:User {user_id})`` and ``(:Session {session_id})`` nodes.
+      - Tracks ``active_user_id`` and ``active_session_id`` for use in API calls.
+
+    On ``SESSION_END``:
+      - Clears the tracked active session context.
+
+    Args:
+        graph: An initialised :class:`SessionsGraph` instance.
+    """
+
+    def __init__(self, graph: SessionsGraph) -> None:
+        self._graph = graph
+        self._active_user_id: str | None = None
+        self._active_session_id: str | None = None
+
+    # ------------------------------------------------------------------
+    # GraphConnector interface
+    # ------------------------------------------------------------------
+
+    def supports(self, event: Event) -> bool:
+        return event.event_type in _SUPPORTED_EVENTS
+
+    def on_event(self, event: Event) -> None:
+        if isinstance(event, SessionStartEvent):
+            self._on_session_start(event)
+        elif isinstance(event, SessionEndEvent):
+            self._on_session_end(event)
+
+    # ------------------------------------------------------------------
+    # Active session context (convenience for callers)
+    # ------------------------------------------------------------------
+
+    @property
+    def active_user_id(self) -> str | None:
+        """The ``user_id`` from the most recent ``SessionStartEvent``, if any."""
+        return self._active_user_id
+
+    @property
+    def active_session_id(self) -> str | None:
+        """The ``session_id`` from the most recent ``SessionStartEvent``, if any."""
+        return self._active_session_id
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _on_session_start(self, event: SessionStartEvent) -> None:
+        user_id: str | None = getattr(event, "user_id", None)
+
+        if user_id:
+            self._active_user_id = user_id
+            # Ensure the User node exists before any save_memory call
+            self._graph._db.query(
+                "MERGE (:User {user_id: $user_id});",
+                params={"user_id": user_id},
+            )
+
+        self._active_session_id = event.session_id
+        # Ensure the Session node exists for provenance wiring
+        self._graph._db.query(
+            "MERGE (:Session {session_id: $session_id});",
+            params={"session_id": event.session_id},
+        )
+
+    def _on_session_end(self, event: SessionEndEvent) -> None:
+        self._active_user_id = None
+        self._active_session_id = None

sessions_graph/core.py

@@ -0,0 +1,237 @@
+"""Core SessionsGraph class for storing and recalling agent memories in Memgraph.
+
+Graph schema
+------------
+Nodes:
+    (:User  {user_id})
+    (:Memory {memory_id, user_id, content, created_at, session_id?})
+    (:Session {session_id})
+
+Relationships:
+    (:User)-[:HAS_MEMORY]->(:Memory)
+    (:Session)-[:PRODUCED_MEMORY]->(:Memory)   — only when session_id is provided
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any
+
+from memgraph_toolbox.api.memgraph import Memgraph
+
+from .models import Memory, validate_content, validate_memory_id, validate_user_id
+
+_FULLTEXT_INDEX = "memory_content_index"
+
+
+class SessionsGraph:
+    """Store and recall agent memories in Memgraph.
+
+    Provides:
+    - :meth:`save_memory`   — persist a new Memory for a user
+    - :meth:`get_memories`  — retrieve all Memories for a user
+    - :meth:`search_memories` — full-text search over Memory content
+    - :meth:`update_memory` — replace the content of an existing Memory
+    - :meth:`delete_memory` — remove a Memory by ID
+    """
+
+    def __init__(self, memgraph: Memgraph | None = None, **kwargs: Any) -> None:
+        """Initialise SessionsGraph.
+
+        Args:
+            memgraph: An existing Memgraph client instance.  When *None* a new
+                      one is created from *kwargs* / environment variables.
+            **kwargs: Forwarded to :class:`Memgraph` when *memgraph* is ``None``.
+        """
+        self._db = memgraph or Memgraph(**kwargs)
+
+    # ------------------------------------------------------------------
+    # Schema setup
+    # ------------------------------------------------------------------
+
+    def setup(self) -> None:
+        """Create constraints, indexes, and the full-text index."""
+        self._db.query("CREATE CONSTRAINT ON (u:User) ASSERT u.user_id IS UNIQUE;")
+        self._db.query("CREATE CONSTRAINT ON (m:Memory) ASSERT m.memory_id IS UNIQUE;")
+        self._db.query("CREATE INDEX ON :Memory(user_id);")
+        self._db.query("CREATE INDEX ON :Memory(created_at);")
+        self._db.query(f"CREATE TEXT INDEX {_FULLTEXT_INDEX} ON :Memory(content);")
+
+    def drop(self) -> None:
+        """Remove all Memory-related constraints and indexes."""
+        with contextlib.suppress(Exception):
+            self._db.query("DROP CONSTRAINT ON (u:User) ASSERT u.user_id IS UNIQUE;")
+        with contextlib.suppress(Exception):
+            self._db.query("DROP CONSTRAINT ON (m:Memory) ASSERT m.memory_id IS UNIQUE;")
+        with contextlib.suppress(Exception):
+            self._db.query(f"DROP TEXT INDEX {_FULLTEXT_INDEX};")
+
+    # ------------------------------------------------------------------
+    # Write
+    # ------------------------------------------------------------------
+
+    def save_memory(
+        self,
+        user_id: str,
+        content: str,
+        *,
+        session_id: str | None = None,
+        memory_id: str | None = None,
+    ) -> Memory:
+        """Persist a new Memory for *user_id*.
+
+        Args:
+            user_id:    The owning user identity.
+            content:    The free-form text assertion to store.
+            session_id: Optional session that produced this memory (for provenance).
+            memory_id:  Override the auto-generated UUID (useful in tests).
+
+        Returns:
+            The persisted :class:`Memory` instance.
+        """
+        memory = Memory(
+            user_id=validate_user_id(user_id),
+            content=validate_content(content),
+            session_id=session_id,
+            **({"memory_id": memory_id} if memory_id else {}),
+        )
+
+        # MERGE user, CREATE memory, wire ownership
+        self._db.query(
+            """
+            MERGE (u:User {user_id: $user_id})
+            CREATE (m:Memory {
+                memory_id: $memory_id,
+                user_id:   $user_id,
+                content:   $content,
+                created_at: $created_at
+            })
+            CREATE (u)-[:HAS_MEMORY]->(m)
+            """,
+            params={
+                "user_id": memory.user_id,
+                "memory_id": memory.memory_id,
+                "content": memory.content,
+                "created_at": memory.created_at,
+            },
+        )
+
+        # Wire session provenance when a session_id is supplied
+        if session_id:
+            self._db.query(
+                """
+                MERGE (s:Session {session_id: $session_id})
+                WITH s
+                MATCH (m:Memory {memory_id: $memory_id})
+                CREATE (s)-[:PRODUCED_MEMORY]->(m)
+                """,
+                params={"session_id": session_id, "memory_id": memory.memory_id},
+            )
+
+        return memory
+
+    # ------------------------------------------------------------------
+    # Read
+    # ------------------------------------------------------------------
+
+    def get_memories(self, user_id: str) -> list[Memory]:
+        """Return all Memories owned by *user_id*, newest first."""
+        validate_user_id(user_id)
+        rows = self._db.query(
+            """
+            MATCH (u:User {user_id: $user_id})-[:HAS_MEMORY]->(m:Memory)
+            OPTIONAL MATCH (s:Session)-[:PRODUCED_MEMORY]->(m)
+            RETURN m.memory_id  AS memory_id,
+                   m.user_id    AS user_id,
+                   m.content    AS content,
+                   m.created_at AS created_at,
+                   s.session_id AS session_id
+            ORDER BY m.created_at DESC
+            """,
+            params={"user_id": user_id},
+        )
+        return [self._row_to_memory(r) for r in rows]
+
+    def search_memories(self, user_id: str, query: str, *, limit: int = 10) -> list[Memory]:
+        """Full-text search over Memory content for *user_id*.
+
+        Args:
+            user_id: Only return Memories owned by this user.
+            query:   Full-text search query string.
+            limit:   Maximum number of results to return.
+
+        Returns:
+            Matching :class:`Memory` instances ordered by relevance score.
+        """
+        validate_user_id(user_id)
+        if not query or not query.strip():
+            return []
+
+        rows = self._db.query(
+            f"""
+            CALL text_search.search_all('{_FULLTEXT_INDEX}', $query)
+            YIELD node AS m, score
+            WHERE m.user_id = $user_id
+            OPTIONAL MATCH (s:Session)-[:PRODUCED_MEMORY]->(m)
+            RETURN m.memory_id  AS memory_id,
+                   m.user_id    AS user_id,
+                   m.content    AS content,
+                   m.created_at AS created_at,
+                   s.session_id AS session_id
+            ORDER BY score DESC
+            LIMIT {int(limit)}
+            """,
+            params={"user_id": user_id, "query": query.strip()},
+        )
+        return [self._row_to_memory(r) for r in rows]
+
+    # ------------------------------------------------------------------
+    # Update / Delete
+    # ------------------------------------------------------------------
+
+    def update_memory(self, memory_id: str, content: str) -> Memory | None:
+        """Replace the content of an existing Memory.
+
+        Returns the updated :class:`Memory`, or ``None`` if not found.
+        """
+        validate_memory_id(memory_id)
+        validate_content(content)
+
+        rows = self._db.query(
+            """
+            MATCH (m:Memory {memory_id: $memory_id})
+            SET m.content = $content
+            OPTIONAL MATCH (s:Session)-[:PRODUCED_MEMORY]->(m)
+            RETURN m.memory_id  AS memory_id,
+                   m.user_id    AS user_id,
+                   m.content    AS content,
+                   m.created_at AS created_at,
+                   s.session_id AS session_id
+            """,
+            params={"memory_id": memory_id, "content": content},
+        )
+        if not rows:
+            return None
+        return self._row_to_memory(rows[0])
+
+    def delete_memory(self, memory_id: str) -> None:
+        """Remove a Memory and all its relationships by ID."""
+        validate_memory_id(memory_id)
+        self._db.query(
+            "MATCH (m:Memory {memory_id: $memory_id}) DETACH DELETE m;",
+            params={"memory_id": memory_id},
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _row_to_memory(row: dict) -> Memory:
+        return Memory(
+            memory_id=row["memory_id"],
+            user_id=row["user_id"],
+            content=row["content"],
+            created_at=row["created_at"],
+            session_id=row.get("session_id"),
+        )

sessions_graph/models.py

@@ -0,0 +1,69 @@
+"""Data models for Sessions Graph.
+
+Defines the core data structure for a Memory — a cross-session-durable
+free-form text assertion written explicitly by an agent.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from uuid import uuid4
+
+_USER_ID_RE = re.compile(r"^[a-zA-Z0-9_@.\-]{1,256}$")
+_MEMORY_ID_RE = re.compile(r"^[a-zA-Z0-9_-]{1,128}$")
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _generate_id() -> str:
+    return str(uuid4())
+
+
+class MemoryValidationError(ValueError):
+    """Raised when a Memory field violates validation rules."""
+
+
+def validate_user_id(user_id: str) -> str:
+    if not user_id or not _USER_ID_RE.match(user_id):
+        raise MemoryValidationError(f"user_id must match pattern {_USER_ID_RE.pattern!r}, got: {user_id!r}")
+    return user_id
+
+
+def validate_memory_id(memory_id: str) -> str:
+    if not memory_id or not _MEMORY_ID_RE.match(memory_id):
+        raise MemoryValidationError(f"memory_id must match pattern {_MEMORY_ID_RE.pattern!r}, got: {memory_id!r}")
+    return memory_id
+
+
+def validate_content(content: str) -> str:
+    if not content or not content.strip():
+        raise MemoryValidationError("content must be a non-empty string")
+    return content
+
+
+@dataclass
+class Memory:
+    """A cross-session-durable free-form text assertion owned by a user.
+
+    Attributes:
+        user_id:    The identity of the user this memory belongs to.
+        content:    The free-form text assertion.
+        memory_id:  Unique identifier (auto-generated UUID by default).
+        created_at: ISO-format UTC timestamp of when the memory was written.
+        session_id: The session that produced this memory (optional provenance).
+    """
+
+    user_id: str
+    content: str
+    memory_id: str = field(default_factory=_generate_id)
+    created_at: str = field(default_factory=_utc_now)
+    session_id: str | None = None
+
+    def __post_init__(self) -> None:
+        validate_user_id(self.user_id)
+        validate_memory_id(self.memory_id)
+        validate_content(self.content)

sessions_graph-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: sessions-graph
+Version: 0.1.0
+Summary: Cross-session memory store for agents, backed by Memgraph
+License: MIT
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: memgraph-toolbox
+Provides-Extra: agent-context-graph
+Requires-Dist: agent-context-graph>=0.1.2; extra == 'agent-context-graph'
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.3; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Sessions Graph
+
+Sessions Graph is the [Context Graph](../CONTEXT-MAP.md) component for session context and cross-session recall. It is the **authority on `(:Session)` nodes** in the Context Graph family. It stores free-form text assertions — called **Memories** — written explicitly by agents, and makes them searchable in future sessions.
+
+Requires **Memgraph ≥ 3.6** (text search is stable from that release).
+
+## Installation
+
+```bash
+pip install sessions-graph
+```
+
+To use with Agent Context Graph:
+
+```bash
+pip install sessions-graph[agent-context-graph]
+```
+
+## Quick start
+
+```python
+from sessions_graph import SessionsGraph
+
+graph = SessionsGraph()   # connects via MEMGRAPH_HOST / MEMGRAPH_PORT env vars
+graph.setup()           # creates constraints and the text index (run once)
+
+# Write a memory
+mem = graph.save_memory(
+    user_id="alice",
+    content="Prefers Python over TypeScript",
+    session_id="s-abc123",   # optional — links memory to a session for provenance
+)
+
+# Retrieve all memories for a user
+memories = graph.get_memories("alice")
+
+# Search memories by content (full-text, powered by Tantivy)
+results = graph.search_memories("alice", "Python")
+
+# Update or delete
+graph.update_memory(mem.memory_id, "Prefers Python, especially for data tooling")
+graph.delete_memory(mem.memory_id)
+```
+
+## Integration with Agent Context Graph
+
+Wire the `SessionsGraphConnector` into an `AgentLink` to get automatic session provenance — the connector tracks the active `session_id` and `user_id` from `SessionStartEvent` so you can reference them when saving memories.
+
+```python
+from sessions_graph import SessionsGraph
+from sessions_graph.connector import SessionsGraphConnector
+from agent_context_graph import AgentLink
+from agent_context_graph.adapters.claude import ClaudeAdapter
+
+graph = SessionsGraph()
+graph.setup()
+
+connector = SessionsGraphConnector(graph)
+link = AgentLink()
+link.add_connector(connector)
+
+adapter = ClaudeAdapter(
+    link,
+    session_id="s-abc123",
+    session_kwargs={"user_id": "alice"},
+)
+
+# During the session, save memories via the Python API:
+graph.save_memory(
+    user_id=connector.active_user_id,
+    content="User works primarily in the ai-toolkit repository",
+    session_id=connector.active_session_id,
+)
+```
+
+## Graph schema
+
+```
+(:User {user_id})
+    └─[:HAS_MEMORY]─▶ (:Memory {memory_id, user_id, content, created_at})
+                              ▲
+              [:PRODUCED_MEMORY]
+                              │
+                      (:Session {session_id})   ← shared idempotent coordination point
+```
+
+## Text search
+
+Sessions Graph uses [Memgraph text search](https://memgraph.com/docs/querying/text-search) (powered by Tantivy) for `search_memories`. The text index is created on `setup()`:
+
+```cypher
+CREATE TEXT INDEX memory_content_index ON :Memory(content);
+```
+
+Searches run as:
+
+```cypher
+CALL text_search.search_all('memory_content_index', 'Python')
+YIELD node AS m, score
+WHERE m.user_id = 'alice'
+RETURN m.content, score
+ORDER BY score DESC
+LIMIT 10;
+```
+
+The query string follows [Tantivy query syntax](https://docs.rs/tantivy/latest/tantivy/query/struct.QueryParser.html).
+
+## API reference
+
+| Method | Description |
+|---|---|
+| `setup()` | Create constraints and text index. Run once on first use. |
+| `drop()` | Remove all Memory-related constraints and indexes. |
+| `save_memory(user_id, content, *, session_id, memory_id)` | Persist a new Memory. Returns the stored `Memory` object. |
+| `get_memories(user_id)` | Return all Memories for a user, newest first. |
+| `search_memories(user_id, query, *, limit=10)` | Full-text search over Memory content. |
+| `update_memory(memory_id, content)` | Replace the content of an existing Memory. Returns `None` if not found. |
+| `delete_memory(memory_id)` | Remove a Memory and all its relationships. |

sessions_graph-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sessions_graph/__init__.py,sha256=w45gncXgA_L7fqggHLH7VgK70mvnAinqK-XFVATFJXk,1236
+sessions_graph/connector.py,sha256=67h-lRqt0-egJFw3Y61KSjrNbsLj3Iq8lXaInXZeN5k,4108
+sessions_graph/core.py,sha256=DI3c9IcyfefupZ5vgAATq-5DniU_yRebbv5HxNgi_64,8647
+sessions_graph/models.py,sha256=lzUAwnRcQ-smFer0f-fbyM8VURI0fsbZZswbZ_0za2k,2132
+sessions_graph-0.1.0.dist-info/METADATA,sha256=q5e2uln6bhLENvZrFcRhDZNDFtOleLFrEZdkQF44kgc,4463
+sessions_graph-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sessions_graph-0.1.0.dist-info/RECORD,,

sessions_graph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any