memmachine-server 0.3.8__tar.gz → 0.3.9__tar.gz

{memmachine_server-0.3.8 → memmachine_server-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memmachine-server
-Version: 0.3.8
+Version: 0.3.9
 Summary: MemMachine Server - The complete MemMachine memory system server with episodic and profile memory
 Author-email: MemMachine <noreply@memmachine.ai>
 License-Expression: Apache-2.0
@@ -31,7 +31,7 @@ Requires-Dist: langchain-aws>=0.2.33
 Requires-Dist: neo4j>=5.28.2
 Requires-Dist: nltk>=3.9.4
 Requires-Dist: openai>=2.21.0
-Requires-Dist: pgvector>=0.4.1
+Requires-Dist: pgvector>=0.4.2
 Requires-Dist: prometheus-client>=0.22.1
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: pyyaml>=6.0.2

{memmachine_server-0.3.8 → memmachine_server-0.3.9}/pyproject.toml

@@ -22,7 +22,7 @@ dependencies = [
     "neo4j>=5.28.2",
     "nltk>=3.9.4",
     "openai>=2.21.0",
-    "pgvector>=0.4.1",
+    "pgvector>=0.4.2",
     "prometheus-client>=0.22.1",
     "pydantic>=2.11.7",
     "pyyaml>=6.0.2",

{memmachine_server-0.3.8 → memmachine_server-0.3.9}/server_tests/memmachine_server/common/configuration/test_configuration.py

@@ -10,8 +10,13 @@ from memmachine_server.common.configuration import (
     EpisodicMemoryConfPartial,
 )
 from memmachine_server.common.configuration.episodic_config import (
+    DeclarativeLongTermMemoryConf,
+    EpisodicMemoryConf,
+    EventLongTermMemoryConf,
     LongTermMemoryConfPartial,
+    PassthroughSegmenterConf,
     ShortTermMemoryConfPartial,
+    WholeTextDeriverConf,
 )
 from memmachine_server.common.configuration.log_conf import LogLevel
 
@@ -34,6 +39,7 @@ def test_update_long_term_memory_conf(long_term_memory_conf: LongTermMemoryConfP
     )
 
     updated = specific.merge(long_term_memory_conf)
+    assert isinstance(updated, DeclarativeLongTermMemoryConf)
     assert updated.session_id == "session_123"
     assert updated.embedder == "embedder_v2"
     assert updated.reranker == "reranker_v1"
@@ -219,3 +225,168 @@ def test_save_raises_error_when_no_path():
 
     with pytest.raises(ValueError, match="No path provided"):
         conf_no_path.save()
+
+
+# --- Backwards-compat: long-term-memory backend discriminator ---
+
+
+def _ltm_minimal_short_term_block() -> dict:
+    return {
+        "session_key": "s",
+        "llm_model": "m",
+        "summary_prompt_system": "x",
+        "summary_prompt_user": "y",
+    }
+
+
+def test_old_param_data_without_backend_loads_as_declarative():
+    """Old persisted session param_data (no `backend`) round-trips as declarative.
+
+    Reproduces the historical session_data_manager_sql_impl.py:306 path:
+    `EpisodicMemoryConf(**session.param_data)` for a row written before the
+    backend discriminator existed.
+    """
+    old_param_data = {
+        "session_key": "old_session",
+        "long_term_memory": {
+            "session_id": "old_session",
+            "embedder": "openai_embedder",
+            "reranker": "my_reranker_id",
+            "vector_graph_store": "my_storage_id",
+        },
+        "short_term_memory": _ltm_minimal_short_term_block(),
+        "long_term_memory_enabled": True,
+        "short_term_memory_enabled": True,
+        "enabled": True,
+    }
+
+    conf = EpisodicMemoryConf.model_validate(old_param_data)
+    assert isinstance(conf.long_term_memory, DeclarativeLongTermMemoryConf)
+    assert conf.long_term_memory.backend == "declarative"
+    assert conf.long_term_memory.embedder == "openai_embedder"
+    assert conf.long_term_memory.vector_graph_store == "my_storage_id"
+
+
+def test_episodic_memory_conf_with_explicit_event_backend_loads_as_event():
+    data = {
+        "session_key": "s",
+        "long_term_memory": {
+            "backend": "event",
+            "session_id": "s",
+            "vector_store": "vstore",
+            "segment_store": "pg_engine",
+            "embedder": "openai_embedder",
+        },
+        "short_term_memory": _ltm_minimal_short_term_block(),
+    }
+
+    conf = EpisodicMemoryConf.model_validate(data)
+    assert isinstance(conf.long_term_memory, EventLongTermMemoryConf)
+    assert conf.long_term_memory.vector_store == "vstore"
+    assert conf.long_term_memory.segment_store == "pg_engine"
+    # Default sub-configs.
+    assert isinstance(conf.long_term_memory.segmenter, PassthroughSegmenterConf)
+    assert isinstance(conf.long_term_memory.deriver, WholeTextDeriverConf)
+    # Reranker is optional on the event backend.
+    assert conf.long_term_memory.reranker is None
+
+
+def test_episodic_memory_conf_with_explicit_declarative_backend_loads_as_declarative():
+    data = {
+        "session_key": "s",
+        "long_term_memory": {
+            "backend": "declarative",
+            "session_id": "s",
+            "vector_graph_store": "g",
+            "embedder": "e",
+            "reranker": "r",
+        },
+        "short_term_memory": _ltm_minimal_short_term_block(),
+    }
+
+    conf = EpisodicMemoryConf.model_validate(data)
+    assert isinstance(conf.long_term_memory, DeclarativeLongTermMemoryConf)
+    assert conf.long_term_memory.vector_graph_store == "g"
+
+
+def test_partial_merge_with_no_backend_resolves_to_declarative():
+    """LongTermMemoryConfPartial.merge() defaults missing backend to declarative."""
+    base = LongTermMemoryConfPartial(
+        session_id="s",
+        embedder="e",
+        reranker="r",
+        vector_graph_store="g",
+    )
+    override = LongTermMemoryConfPartial(embedder="e2")
+
+    merged = override.merge(base)
+    assert isinstance(merged, DeclarativeLongTermMemoryConf)
+    assert merged.embedder == "e2"
+    assert merged.reranker == "r"
+    assert merged.vector_graph_store == "g"
+
+
+def test_partial_merge_with_event_backend_resolves_to_event():
+    base = LongTermMemoryConfPartial(
+        backend="event",
+        session_id="s",
+        embedder="e",
+        vector_store="v",
+        segment_store="seg",
+    )
+    override = LongTermMemoryConfPartial()
+
+    merged = override.merge(base)
+    assert isinstance(merged, EventLongTermMemoryConf)
+    assert merged.vector_store == "v"
+    assert merged.segment_store == "seg"
+    assert merged.embedder == "e"
+    assert merged.reranker is None
+
+
+def test_partial_merge_explicit_declarative_backend():
+    base = LongTermMemoryConfPartial(
+        backend="declarative",
+        session_id="s",
+        embedder="e",
+        reranker="r",
+        vector_graph_store="g",
+    )
+    merged = LongTermMemoryConfPartial().merge(base)
+    assert isinstance(merged, DeclarativeLongTermMemoryConf)
+
+
+def test_partial_merge_primary_backend_wins_over_fallback():
+    """Primary backend takes precedence over fallback."""
+    primary = LongTermMemoryConfPartial(
+        backend="event",
+        session_id="s",
+        embedder="e",
+        vector_store="v",
+        segment_store="seg",
+    )
+    fallback = LongTermMemoryConfPartial(
+        backend="declarative",
+        session_id="s",
+        embedder="e",
+        reranker="r",
+        vector_graph_store="g",
+    )
+    merged = primary.merge(fallback)
+    assert isinstance(merged, EventLongTermMemoryConf)
+
+
+def test_existing_sample_yaml_loads_as_declarative_via_full_configuration():
+    """Existing sample YAMLs (no `backend` field) load through Configuration."""
+    config_path = find_config_file("episodic_memory_config.cpu.sample")
+    conf = Configuration.load_yml_file(str(config_path))
+    assert conf.episodic_memory.long_term_memory is not None
+    # Configuration.episodic_memory is the partial; backend stays None on load.
+    assert conf.episodic_memory.long_term_memory.backend is None
+    # ...and merging the LTM partial alone resolves to declarative.
+    ltm_merged = LongTermMemoryConfPartial(session_id="test_session").merge(
+        conf.episodic_memory.long_term_memory
+    )
+    assert isinstance(ltm_merged, DeclarativeLongTermMemoryConf)
+    assert ltm_merged.embedder == "openai_embedder"
+    assert ltm_merged.vector_graph_store == "my_storage_id"

{memmachine_server-0.3.8 → memmachine_server-0.3.9}/server_tests/memmachine_server/common/episode_store/test_episode_storage.py

@@ -105,6 +105,26 @@ async def test_add_and_get_history(episode_storage: EpisodeStorage):
     assert history.episode_type == EpisodeType.MESSAGE
 
 
+@pytest.mark.asyncio
+async def test_get_episodes_batch(episode_storage: EpisodeStorage):
+    first = await create_history_entry(episode_storage, content="first")
+    second = await create_history_entry(episode_storage, content="second")
+    third = await create_history_entry(episode_storage, content="third")
+
+    try:
+        # All present; duplicates are deduped; missing IDs are absent.
+        fetched = await episode_storage.get_episodes([first, third, first, "999999999"])
+        by_uid = {ep.uid: ep for ep in fetched}
+        assert set(by_uid.keys()) == {first, third}
+        assert by_uid[first].content == "first"
+        assert by_uid[third].content == "third"
+
+        # Empty input returns empty list without hitting the DB.
+        assert await episode_storage.get_episodes([]) == []
+    finally:
+        await episode_storage.delete_episodes([first, second, third])
+
+
 @pytest.mark.asyncio
 async def test_add_multiple_episodes_returns_models(
     episode_storage: EpisodeStorage,

{memmachine_server-0.3.8 → memmachine_server-0.3.9}/server_tests/memmachine_server/common/session_manager/test_session_manager.py

@@ -6,8 +6,8 @@ from pydantic import JsonValue
 from sqlalchemy.ext.asyncio import AsyncEngine
 
 from memmachine_server.common.configuration.episodic_config import (
+    DeclarativeLongTermMemoryConf,
     EpisodicMemoryConf,
-    LongTermMemoryConf,
     ShortTermMemoryConf,
 )
 from memmachine_server.common.errors import (
@@ -61,7 +61,7 @@ def episodic_memory_conf():
     """Fixture for a dummy EpisodicMemoryConf object."""
     return EpisodicMemoryConf(
         session_key="test_session",
-        long_term_memory=LongTermMemoryConf(
+        long_term_memory=DeclarativeLongTermMemoryConf(
             session_id="test_session",
             vector_graph_store="test_store",
             embedder="test_embedder",

{memmachine_server-0.3.8 → memmachine_server-0.3.9}/server_tests/memmachine_server/episodic_memory/event_memory/conftest.py

@@ -116,11 +116,17 @@ class InMemorySegmentStorePartition(SegmentStorePartition):
 
     @staticmethod
     def _normalize_segment_field(field: str) -> str:
-        """Translate canonical filter field names to raw segment property keys."""
+        """Translate canonical filter field names to raw segment property keys.
+
+        Mirrors SQLAlchemySegmentStorePartition._resolve_segment_field:
+        - `m.<key>` / `metadata.<key>` → user metadata, bare key.
+        - any other bare name → system field, `_<field>` (matches the
+          LongTermMemory event-backend property layout).
+        """
         internal_name, is_user_metadata = normalize_filter_field(field)
         if is_user_metadata:
             return demangle_user_metadata_key(internal_name)
-        return field
+        return f"_{field}"
 
     @override
     async def get_segment_uuids_by_event_uuids(

{memmachine_server-0.3.8 → memmachine_server-0.3.9}/server_tests/memmachine_server/episodic_memory/event_memory/segment_store/test_sqlalchemy_segment_store.py

@@ -399,7 +399,13 @@ async def test_contexts_property_filter(
 async def test_contexts_filter_by_context_producer(
     partition: SQLAlchemySegmentStorePartition,
 ) -> None:
-    """Filter using ``context.producer`` is not supported."""
+    """`context.producer` is not a stored property; the filter just matches nothing.
+
+    Bare names that aren't `timestamp` are looked up as `_<name>` in the JSON
+    properties (matching EventMemory's `_to_vector_record_property` convention
+    for system fields). `context.producer` becomes `_context.producer`, which
+    isn't a stored key on any segment, so the filter returns no contexts.
+    """
     ep = uuid4()
     s0 = _seg(
         event_uuid=ep,
@@ -422,20 +428,20 @@ async def test_contexts_filter_by_context_producer(
     await partition.add_segments(_links(s0, s1, s2))
 
     filt = Comparison(field="context.producer", op="=", value="Alice")
-    with pytest.raises(ValueError, match="Unknown filter field"):
-        await partition.get_segment_contexts(
-            [s0.uuid],
-            max_backward_segments=5,
-            max_forward_segments=5,
-            property_filter=filt,
-        )
+    contexts = await partition.get_segment_contexts(
+        [s0.uuid],
+        max_backward_segments=5,
+        max_forward_segments=5,
+        property_filter=filt,
+    )
+    assert contexts == {}
 
 
 @pytest.mark.asyncio
 async def test_contexts_filter_by_context_type(
     partition: SQLAlchemySegmentStorePartition,
 ) -> None:
-    """Filter using ``context.context_type`` is not supported."""
+    """`context.context_type` is not a stored property; filter matches nothing."""
     ep = uuid4()
     s0 = _seg(
         event_uuid=ep,
@@ -458,13 +464,13 @@ async def test_contexts_filter_by_context_type(
     await partition.add_segments(_links(s0, s1, s2))
 
     filt = Comparison(field="context.context_type", op="=", value="producer")
-    with pytest.raises(ValueError, match="Unknown filter field"):
-        await partition.get_segment_contexts(
-            [s0.uuid],
-            max_backward_segments=5,
-            max_forward_segments=5,
-            property_filter=filt,
-        )
+    contexts = await partition.get_segment_contexts(
+        [s0.uuid],
+        max_backward_segments=5,
+        max_forward_segments=5,
+        property_filter=filt,
+    )
+    assert contexts == {}
 
 
 @pytest.mark.asyncio

memmachine_server-0.3.9/server_tests/memmachine_server/episodic_memory/event_memory/segmenter/test_passthrough_segmenter.py

@@ -0,0 +1,92 @@
+"""Tests for PassthroughSegmenter."""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+import pytest
+
+from memmachine_server.episodic_memory.event_memory.data_types import (
+    Event,
+    NullContext,
+    ProducerContext,
+    TextBlock,
+)
+from memmachine_server.episodic_memory.event_memory.segmenter.passthrough_segmenter import (
+    PassthroughSegmenter,
+)
+
+pytestmark = pytest.mark.asyncio
+
+_TS = datetime(2026, 1, 15, 10, 30, tzinfo=UTC)
+
+
+async def test_passthrough_emits_one_segment_per_block():
+    event = Event(
+        uuid=uuid4(),
+        timestamp=_TS,
+        context=ProducerContext(producer="alice"),
+        blocks=[
+            TextBlock(text="first block"),
+            TextBlock(text="second block"),
+            TextBlock(text="third block"),
+        ],
+        properties={"my_field": "value"},
+    )
+    segmenter = PassthroughSegmenter()
+
+    segments = await segmenter.segment(event)
+
+    assert len(segments) == 3
+    for index, segment in enumerate(segments):
+        assert segment.event_uuid == event.uuid
+        assert segment.index == index
+        assert segment.offset == 0
+        assert segment.timestamp == event.timestamp
+        assert segment.context == event.context
+        assert segment.properties == event.properties
+        assert segment.block.text == event.blocks[index].text
+
+
+async def test_passthrough_does_not_split_long_text():
+    """Each block is preserved verbatim, regardless of length."""
+    long_text = "lorem ipsum " * 1000
+    event = Event(
+        uuid=uuid4(),
+        timestamp=_TS,
+        context=NullContext(),
+        blocks=[TextBlock(text=long_text)],
+    )
+    segmenter = PassthroughSegmenter()
+
+    segments = await segmenter.segment(event)
+
+    assert len(segments) == 1
+    assert segments[0].block.text == long_text
+
+
+async def test_passthrough_empty_blocks_yields_no_segments():
+    event = Event(
+        uuid=uuid4(),
+        timestamp=_TS,
+        context=NullContext(),
+        blocks=[],
+    )
+    segmenter = PassthroughSegmenter()
+
+    segments = await segmenter.segment(event)
+
+    assert segments == []
+
+
+async def test_passthrough_each_segment_has_unique_uuid():
+    event = Event(
+        uuid=uuid4(),
+        timestamp=_TS,
+        context=NullContext(),
+        blocks=[TextBlock(text="a"), TextBlock(text="b")],
+    )
+    segmenter = PassthroughSegmenter()
+
+    segments = await segmenter.segment(event)
+
+    assert len({s.uuid for s in segments}) == len(segments)

memmachine_server-0.3.9/server_tests/memmachine_server/episodic_memory/long_term_memory/test_episode_to_event.py

@@ -0,0 +1,163 @@
+"""Unit tests for the Episode → Event translation in LongTermMemory."""
+
+from datetime import UTC, datetime
+from uuid import uuid5
+
+import pytest
+
+from memmachine_server.common.episode_store import (
+    ContentType,
+    Episode,
+    EpisodeType,
+)
+from memmachine_server.episodic_memory.event_memory.data_types import (
+    NullContext,
+    ProducerContext,
+    TextBlock,
+)
+from memmachine_server.episodic_memory.long_term_memory.long_term_memory import (
+    _EVENT_UUID_NAMESPACE,
+    LongTermMemory,
+)
+
+
+def _episode(
+    *,
+    uid: str = "ep1",
+    content: str = "hello",
+    producer_id: str = "alice",
+    producer_role: str = "user",
+    produced_for_id: str | None = None,
+    sequence_num: int = 0,
+    episode_type: EpisodeType = EpisodeType.MESSAGE,
+    filterable_metadata: dict | None = None,
+    metadata: dict | None = None,
+    session_key: str = "session-1",
+) -> Episode:
+    return Episode(
+        uid=uid,
+        content=content,
+        session_key=session_key,
+        created_at=datetime(2026, 1, 15, 12, 0, tzinfo=UTC),
+        producer_id=producer_id,
+        producer_role=producer_role,
+        produced_for_id=produced_for_id,
+        sequence_num=sequence_num,
+        episode_type=episode_type,
+        content_type=ContentType.STRING,
+        filterable_metadata=filterable_metadata,
+        metadata=metadata,
+    )
+
+
+def test_event_uuid_is_deterministic_uuid5_of_episode_uid():
+    episode = _episode(uid="abc-123")
+    event = LongTermMemory._episode_to_event(episode)
+    assert event.uuid == uuid5(_EVENT_UUID_NAMESPACE, "abc-123")
+    # Stable across calls.
+    assert LongTermMemory._episode_to_event(episode).uuid == event.uuid
+
+
+def test_message_episode_uses_producer_context():
+    episode = _episode(producer_id="alice", episode_type=EpisodeType.MESSAGE)
+    event = LongTermMemory._episode_to_event(episode)
+    assert isinstance(event.context, ProducerContext)
+    assert event.context.producer == "alice"
+
+
+def test_non_message_episode_uses_null_context():
+    # Use any non-MESSAGE EpisodeType. The enum is defined in
+    # memmachine_common.api; pick the first non-MESSAGE entry dynamically so
+    # this test doesn't break when the enum gains members.
+    non_message = next(
+        (t for t in EpisodeType if t is not EpisodeType.MESSAGE),
+        None,
+    )
+    if non_message is None:
+        # Only MESSAGE exists today; this branch will start exercising once
+        # additional Episode types are introduced. Skip rather than assert
+        # invariant we can't yet exercise.
+        pytest.skip("Only MESSAGE EpisodeType exists; nothing else to verify yet")
+    episode = _episode(episode_type=non_message)
+    event = LongTermMemory._episode_to_event(episode)
+    assert isinstance(event.context, NullContext)
+
+
+def test_event_has_single_text_block_with_episode_content():
+    episode = _episode(content="hello world")
+    event = LongTermMemory._episode_to_event(episode)
+    assert len(event.blocks) == 1
+    assert isinstance(event.blocks[0], TextBlock)
+    assert event.blocks[0].text == "hello world"
+
+
+def test_system_fields_are_underscore_prefixed():
+    episode = _episode(
+        uid="ep-1",
+        producer_id="alice",
+        producer_role="user",
+        produced_for_id="bob",
+        sequence_num=42,
+        session_key="sess-X",
+    )
+    event = LongTermMemory._episode_to_event(episode)
+    p = event.properties
+    assert p["_episode_uid"] == "ep-1"
+    assert p["_session_key"] == "sess-X"
+    assert p["_producer_id"] == "alice"
+    assert p["_producer_role"] == "user"
+    assert p["_produced_for_id"] == "bob"
+    assert p["_sequence_num"] == 42
+    assert p["_episode_type"] == "message"
+    assert p["_content_type"] == "string"
+    assert p["_created_at"] == episode.created_at
+
+
+def test_produced_for_id_omitted_when_none():
+    episode = _episode(produced_for_id=None)
+    event = LongTermMemory._episode_to_event(episode)
+    assert "_produced_for_id" not in event.properties
+
+
+def test_user_filterable_metadata_keys_are_bare():
+    episode = _episode(
+        filterable_metadata={"my_field": "value", "count": 7},
+    )
+    event = LongTermMemory._episode_to_event(episode)
+    p = event.properties
+    # User-defined keys land bare (no `_` prefix), so the v2 client filter API
+    # `m.my_field` resolves to vector-record property `my_field`.
+    assert p["my_field"] == "value"
+    assert p["count"] == 7
+
+
+def test_episode_to_event_rejects_underscore_prefixed_user_keys():
+    """Reserved `_`-prefixed user keys must be rejected at the event-backend
+    translation layer. Without this check a client could send
+    {"_producer_id": "victim", "_session_key": "other-session"} via
+    filterable_metadata, get its content indexed under those spoofed
+    identities, and impersonate the victim through search_scored's
+    property_filter API. We raise loudly so callers see the misuse instead
+    of silently dropping. (Event-backend only — the declarative backend
+    mangles user keys with a `metadata.` prefix and is unaffected.)
+    """
+    episode = _episode(
+        filterable_metadata={
+            "safe_key": "ok",
+            "_producer_id": "victim",
+            "_session_key": "other-session",
+            "_episode_uid": "spoofed-uid",
+        }
+    )
+    with pytest.raises(ValueError, match=r"reserved.*`_`-prefixed"):
+        LongTermMemory._episode_to_event(episode)
+
+
+def test_episode_to_event_allows_metadata_dot_prefixed_keys():
+    """The declarative backend mangles user keys with a `metadata.` prefix.
+    On the event backend, a literal `metadata.foo` key is just a regular
+    user property and must not be rejected.
+    """
+    episode = _episode(filterable_metadata={"metadata.foo": "bar"})
+    event = LongTermMemory._episode_to_event(episode)
+    assert event.properties["metadata.foo"] == "bar"