sessions-graph 0.1.0__tar.gz

sessions_graph-0.1.0/.gitignore

@@ -0,0 +1,192 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+
+# VS Code
+.vscode/
+
+
+# Local agent hook configuration
+/.codex/
+/.claude/settings.local.json
+/AGENTS.md
+/docs/agents/
+/context-graph/CONTEXT-MAP.md
+/context-graph/*/CONTEXT.md
+/context-graph/docs/adr/
+/context-graph/*/docs/adr/
+
+# Project specific files
+/enterprise-context/sic-agent/sic-scrapper/output/*

sessions_graph-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,118 @@
+# 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/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "sessions-graph"
+version = "0.1.0"
+description = "Cross-session memory store for agents, backed by Memgraph"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+classifiers = [
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "memgraph-toolbox",
+]
+
+[project.optional-dependencies]
+agent-context-graph = [
+    "agent-context-graph>=0.1.2",
+]
+test = [
+    "pytest>=9.0.3",
+]
+
+[tool.uv.sources]
+agent-context-graph = { workspace = true }
+memgraph-toolbox = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

sessions_graph-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_sessions_graph.py

@@ -0,0 +1,179 @@
+"""Unit tests for Sessions Graph models, core, and connector.
+
+These tests use an in-memory stub for the Memgraph client so they run
+without a live database.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from sessions_graph.models import Memory, MemoryValidationError
+
+# ---------------------------------------------------------------------------
+# models
+# ---------------------------------------------------------------------------
+
+
+class TestMemory:
+    def test_valid_memory_is_created(self):
+        m = Memory(user_id="alice", content="Prefers Python")
+        assert m.user_id == "alice"
+        assert m.content == "Prefers Python"
+        assert m.memory_id  # auto-generated
+        assert m.created_at
+        assert m.session_id is None
+
+    def test_empty_content_raises(self):
+        with pytest.raises(MemoryValidationError, match="content"):
+            Memory(user_id="alice", content="")
+
+    def test_whitespace_only_content_raises(self):
+        with pytest.raises(MemoryValidationError, match="content"):
+            Memory(user_id="alice", content="   ")
+
+    def test_invalid_user_id_raises(self):
+        with pytest.raises(MemoryValidationError, match="user_id"):
+            Memory(user_id="alice bob", content="some fact")  # space not allowed
+
+    def test_session_id_stored(self):
+        m = Memory(user_id="alice", content="fact", session_id="s-1")
+        assert m.session_id == "s-1"
+
+
+# ---------------------------------------------------------------------------
+# core (stubbed Memgraph)
+# ---------------------------------------------------------------------------
+
+
+def _stub_db(rows: list | None = None):
+    db = MagicMock()
+    db.query.return_value = rows or []
+    return db
+
+
+def _graph(rows=None):
+    from sessions_graph.core import SessionsGraph
+
+    g = SessionsGraph.__new__(SessionsGraph)
+    g._db = _stub_db(rows)
+    return g
+
+
+class TestSessionsGraphCore:
+    def test_save_memory_runs_two_queries(self):
+        g = _graph()
+        mem = g.save_memory("alice", "Prefers dark mode")
+
+        assert mem.user_id == "alice"
+        assert mem.content == "Prefers dark mode"
+        assert g._db.query.call_count == 1  # no session_id → one query only
+
+    def test_save_memory_with_session_runs_two_queries(self):
+        g = _graph()
+        g.save_memory("alice", "Fact", session_id="s-1")
+        assert g._db.query.call_count == 2  # main + provenance
+
+    def test_save_memory_rejects_empty_content(self):
+        g = _graph()
+        with pytest.raises(MemoryValidationError):
+            g.save_memory("alice", "")
+
+    def test_get_memories_returns_empty_list(self):
+        g = _graph(rows=[])
+        result = g.get_memories("alice")
+        assert result == []
+
+    def test_get_memories_maps_rows(self):
+        rows = [
+            {
+                "memory_id": "m-1",
+                "user_id": "alice",
+                "content": "Prefers Python",
+                "created_at": "2026-01-01T00:00:00+00:00",
+                "session_id": None,
+            }
+        ]
+        g = _graph(rows=rows)
+        result = g.get_memories("alice")
+        assert len(result) == 1
+        assert result[0].content == "Prefers Python"
+
+    def test_search_memories_skips_empty_query(self):
+        g = _graph()
+        result = g.search_memories("alice", "")
+        assert result == []
+        g._db.query.assert_not_called()
+
+    def test_delete_memory_calls_detach_delete(self):
+        g = _graph()
+        g.delete_memory("m-1")
+        query_text = g._db.query.call_args.args[0]
+        assert "DETACH DELETE" in query_text
+
+    def test_update_memory_returns_none_when_not_found(self):
+        g = _graph(rows=[])
+        result = g.update_memory("m-1", "new content")
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# connector
+# ---------------------------------------------------------------------------
+
+
+class TestSessionsGraphConnector:
+    def _make(self):
+        pytest.importorskip("agent_context_graph", reason="agent-context-graph not installed")
+        from sessions_graph.connector import SessionsGraphConnector
+
+        from agent_context_graph.events import SessionEndEvent, SessionStartEvent
+
+        db = MagicMock()
+        db.query.return_value = []
+
+        from sessions_graph.core import SessionsGraph
+
+        graph = SessionsGraph.__new__(SessionsGraph)
+        graph._db = db
+
+        connector = SessionsGraphConnector(graph)
+        return connector, graph, db, SessionStartEvent, SessionEndEvent
+
+    def test_session_start_merges_user_and_session_nodes(self):
+        connector, _graph, db, SessionStartEvent, _ = self._make()
+
+        event = SessionStartEvent(session_id="s-1", user_id="alice")
+        connector.on_event(event)
+
+        assert connector.active_user_id == "alice"
+        assert connector.active_session_id == "s-1"
+        assert db.query.call_count == 2  # User MERGE + Session MERGE
+
+    def test_session_start_without_user_id_only_merges_session(self):
+        connector, _graph, db, SessionStartEvent, _ = self._make()
+
+        event = SessionStartEvent(session_id="s-1")
+        connector.on_event(event)
+
+        assert connector.active_user_id is None
+        assert connector.active_session_id == "s-1"
+        assert db.query.call_count == 1  # Session MERGE only
+
+    def test_session_end_clears_active_context(self):
+        connector, _graph, _db, SessionStartEvent, SessionEndEvent = self._make()
+
+        connector.on_event(SessionStartEvent(session_id="s-1", user_id="alice"))
+        connector.on_event(SessionEndEvent(session_id="s-1"))
+
+        assert connector.active_user_id is None
+        assert connector.active_session_id is None
+
+    def test_supports_session_events_only(self):
+        connector, _, _, SessionStartEvent, SessionEndEvent = self._make()
+        from agent_context_graph.events import ToolStartEvent
+
+        assert connector.supports(SessionStartEvent(session_id="s-1"))
+        assert connector.supports(SessionEndEvent(session_id="s-1"))
+        assert not connector.supports(ToolStartEvent(session_id="s-1", tool_name="read_file"))