memmachine-server 0.2.2__tar.gz → 0.2.4__tar.gz

{memmachine_server-0.2.2 → memmachine_server-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memmachine-server
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -43,9 +43,16 @@ Dynamic: license-file
 
 <div align="center">
 
+![GitHub Release Version](https://img.shields.io/github/v/release/memmachine/memmachine?display_name=release)
 ![Discord](https://img.shields.io/discord/1412878659479666810)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/MemMachine/MemMachine)
 ![GitHub License](https://img.shields.io/github/license/MemMachine/MemMachine)
+<br/>
+![Docker Pulls](https://img.shields.io/docker/pulls/memmachine/memmachine)
+![GitHub Downloads](https://img.shields.io/github/downloads/memmachine/memmachine/total?label=GitHub%20Downloads)
+<br/>
+![PyPI Downloads - memmachine-client](https://img.shields.io/pypi/dm/memmachine-client?label=PyPI%20Downloads%3A%20memmachine-client)
+![PyPI Downloads - memmachine-server](https://img.shields.io/pypi/dm/memmachine-server?label=PyPI%20Downloads%3A%20memmachine-server)
 
 </div>
 

{memmachine_server-0.2.2 → memmachine_server-0.2.4}/README.md

@@ -2,9 +2,16 @@
 
 <div align="center">
 
+![GitHub Release Version](https://img.shields.io/github/v/release/memmachine/memmachine?display_name=release)
 ![Discord](https://img.shields.io/discord/1412878659479666810)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/MemMachine/MemMachine)
 ![GitHub License](https://img.shields.io/github/license/MemMachine/MemMachine)
+<br/>
+![Docker Pulls](https://img.shields.io/docker/pulls/memmachine/memmachine)
+![GitHub Downloads](https://img.shields.io/github/downloads/memmachine/memmachine/total?label=GitHub%20Downloads)
+<br/>
+![PyPI Downloads - memmachine-client](https://img.shields.io/pypi/dm/memmachine-client?label=PyPI%20Downloads%3A%20memmachine-client)
+![PyPI Downloads - memmachine-server](https://img.shields.io/pypi/dm/memmachine-server?label=PyPI%20Downloads%3A%20memmachine-server)
 
 </div>
 

{memmachine_server-0.2.2 → memmachine_server-0.2.4}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=68.0", "wheel"]
+requires = ["setuptools>=68.0", "wheel", "setuptools-scm>=8.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "memmachine-server"
-version = "v0.2.2"
+dynamic = ["version"]
 dependencies = [
     "alembic>=1.17.1",
     "asyncpg>=0.31.0",
@@ -96,3 +96,6 @@ packages = [
 
 [tool.setuptools.package-dir]
 "" = "src"
+
+[tool.setuptools_scm]
+root = "../.."

{memmachine_server-0.2.2 → memmachine_server-0.2.4}/src/memmachine/__init__.py

@@ -1,5 +1,6 @@
 """Public package exports and utilities for MemMachine."""
 
+from memmachine.common import api  # noqa: F401
 from memmachine.rest_client import MemMachineClient, Memory, Project
 
 try:

{memmachine_server-0.2.2 → memmachine_server-0.2.4}/src/memmachine/common/api/doc.py

@@ -1,5 +1,7 @@
 """API documentation strings for MemMachine server v2."""
 
+from __future__ import annotations
+
 from typing import ClassVar
 
 
@@ -77,6 +79,68 @@ class SpecDoc:
 
     EPISODE_COUNT = "The total number of episodic memories in the project."
 
+    EPISODE_CONTENT = "The content payload of the episode."
+
+    EPISODE_PRODUCER_ID = "Identifier of the episode producer."
+
+    EPISODE_PRODUCER_ROLE = "Role of the producer (e.g., user/assistant/system)."
+
+    EPISODE_PRODUCED_FOR_ID = "Identifier of the intended recipient of the episode."
+
+    EPISODE_TYPE = "The type of episode being stored (e.g., message)."
+
+    EPISODE_METADATA = "Optional metadata associated with the episode."
+
+    EPISODE_CREATED_AT = "Timestamp when the episode was created."
+
+    EPISODE_UID = "Unique identifier for the episode."
+
+    EPISODE_SCORE = "Optional relevance score for the episode."
+
+    EPISODE_SESSION_KEY = "Session key associated with the episode."
+
+    EPISODE_SEQUENCE_NUM = "Sequence number within the session."
+
+    EPISODE_CONTENT_TYPE = "Content type of the episode."
+
+    EPISODE_FILTERABLE_METADATA = "Metadata indexed for filtering."
+
+    SEMANTIC_SET_ID = "Identifier of the semantic set."
+
+    SEMANTIC_CATEGORY = "Category of the semantic feature."
+
+    SEMANTIC_TAG = "Tag associated with the semantic feature."
+
+    SEMANTIC_FEATURE_NAME = "Name of the semantic feature."
+
+    SEMANTIC_VALUE = "Value of the semantic feature."
+
+    SEMANTIC_METADATA = "Storage metadata for the semantic feature."
+
+    SEMANTIC_METADATA_CITATIONS = "Episode IDs cited by this semantic feature."
+
+    SEMANTIC_METADATA_ID = "Identifier for the semantic feature."
+
+    SEMANTIC_METADATA_OTHER = "Additional storage metadata for the semantic feature."
+
+    EPISODIC_SHORT_EPISODES = "Matched short-term episodic entries."
+
+    EPISODIC_SHORT_SUMMARY = "Summaries of matched short-term episodes."
+
+    EPISODIC_LONG_EPISODES = "Matched long-term episodic entries."
+
+    EPISODIC_LONG_TERM = "Long-term episodic search results."
+
+    EPISODIC_SHORT_TERM = "Short-term episodic search results."
+
+    SEARCH_EPISODIC_MEMORY = "Episodic memory search results."
+
+    SEARCH_SEMANTIC_MEMORY = "Semantic memory search results."
+
+    LIST_EPISODIC_MEMORY = "Listed episodic memory entries."
+
+    LIST_SEMANTIC_MEMORY = "Listed semantic memory entries."
+
     MEMORY_CONTENT = "The content or text of the message."
 
     MEMORY_PRODUCER = """
@@ -128,6 +192,10 @@ class SpecDoc:
     The maximum number of memories to return in the search results.
     """
 
+    SCORE_THRESHOLD = """
+    The minimum score for a memory to be included in the search results. Defaults to -inf (no threshold) represented as None. Meaningful only for certain ranking methods.
+    """
+
     QUERY = """
     The natural language query used for semantic memory search. This should be
     a descriptive string of the information you are looking for.
@@ -195,6 +263,12 @@ class SpecDoc:
     ERROR_INTERNAL = """
     The real error that triggered the exception, for internal debugging."""
 
+    SERVER_VERSION = """
+    The version of the MemMachine server."""
+
+    CLIENT_VERSION = """
+    The version of the MemMachine client."""
+
 
 class Examples:
     """Common examples for API fields."""
@@ -208,6 +282,7 @@ class Examples:
     RERANKER: ClassVar[list[str]] = ["bge-reranker-large", "my-custom-reranker"]
     EMBEDDER: ClassVar[list[str]] = ["bge-base-en", "my-embedder"]
     TOP_K: ClassVar[list[int]] = [5, 10, 20]
+    SCORE_THRESHOLD: ClassVar[list[float | None]] = [0.0, 0.5, None]
     QUERY: ClassVar[list[str]] = [
         "What was the user's last conversation about finance?"
     ]
@@ -223,6 +298,8 @@ class Examples:
     SEMANTIC_ID: ClassVar[list[str]] = ["12", "23"]
     SEMANTIC_IDS: ClassVar[list[list[str]]] = [["123", "345"], ["23"]]
     SEARCH_RESULT_STATUS: ClassVar[list[int]] = [0]
+    SERVER_VERSION: ClassVar[list[str]] = ["0.1.2", "0.2.0"]
+    CLIENT_VERSION: ClassVar[list[str]] = ["0.1.2", "0.2.0"]
 
 
 class RouterDoc:

{memmachine_server-0.2.2 → memmachine_server-0.2.4}/src/memmachine/common/api/spec.py

@@ -1,14 +1,37 @@
 """API v2 specification models for request and response structures."""
 
 import logging
-from datetime import UTC, datetime
-from typing import Annotated, Any, Self
+from datetime import datetime, timezone
+from enum import Enum
 
-import regex
-from pydantic import AfterValidator, BaseModel, Field, field_validator, model_validator
+# Python 3.11+ has UTC as a constant, Python 3.10 uses timezone.utc
+try:
+    from datetime import UTC
+except ImportError:
+    UTC = timezone.utc
+
+from typing import Annotated, Any
 
-from memmachine.common.api import EpisodeType, MemoryType
-from memmachine.common.api.doc import Examples, SpecDoc
+# Python 3.11+ has Self in typing, Python 3.10 uses typing_extensions
+try:
+    from typing import Self
+except ImportError:
+    from typing_extensions import Self
+
+import regex
+from pydantic import (
+    AfterValidator,
+    AwareDatetime,
+    BaseModel,
+    ConfigDict,
+    Field,
+    JsonValue,
+    field_validator,
+    model_validator,
+)
+
+from . import EpisodeType, MemoryType
+from .doc import Examples, SpecDoc
 
 DEFAULT_ORG_AND_PROJECT_ID = "universal"
 
@@ -16,6 +39,179 @@ DEFAULT_ORG_AND_PROJECT_ID = "universal"
 logger = logging.getLogger(__name__)
 
 
+# --------------------------------------------------------------------------------------
+# Client-safe DTOs
+#
+# NOTE:
+# These models intentionally live in this API spec module (and do NOT import the
+# internal/core models) so that the client distribution can import the API schema
+# without pulling in server-only packages.
+# --------------------------------------------------------------------------------------
+
+EpisodeIdT = str
+
+
+class ContentType(Enum):
+    """Enumeration for the type of content within an Episode."""
+
+    STRING = "string"
+
+
+class EpisodeEntry(BaseModel):
+    """Payload used when creating a new episode entry."""
+
+    content: Annotated[
+        str,
+        Field(..., description=SpecDoc.EPISODE_CONTENT),
+    ]
+    producer_id: Annotated[
+        str,
+        Field(..., description=SpecDoc.EPISODE_PRODUCER_ID),
+    ]
+    producer_role: Annotated[
+        str,
+        Field(..., description=SpecDoc.EPISODE_PRODUCER_ROLE),
+    ]
+    produced_for_id: Annotated[
+        str | None,
+        Field(default=None, description=SpecDoc.EPISODE_PRODUCED_FOR_ID),
+    ]
+    episode_type: Annotated[
+        EpisodeType | None,
+        Field(default=None, description=SpecDoc.EPISODE_TYPE),
+    ]
+    metadata: Annotated[
+        dict[str, JsonValue] | None,
+        Field(default=None, description=SpecDoc.EPISODE_METADATA),
+    ]
+    created_at: Annotated[
+        AwareDatetime | None,
+        Field(default=None, description=SpecDoc.EPISODE_CREATED_AT),
+    ]
+
+
+class EpisodeResponse(EpisodeEntry):
+    """Episode data returned in search responses."""
+
+    uid: Annotated[
+        EpisodeIdT,
+        Field(..., description=SpecDoc.EPISODE_UID),
+    ]
+    score: Annotated[
+        float | None,
+        Field(default=None, description=SpecDoc.EPISODE_SCORE),
+    ]
+
+
+class Episode(BaseModel):
+    """Episode data returned in list responses."""
+
+    uid: Annotated[
+        EpisodeIdT,
+        Field(..., description=SpecDoc.EPISODE_UID),
+    ]
+    content: Annotated[
+        str,
+        Field(..., description=SpecDoc.EPISODE_CONTENT),
+    ]
+    session_key: Annotated[
+        str,
+        Field(..., description=SpecDoc.EPISODE_SESSION_KEY),
+    ]
+    created_at: Annotated[
+        AwareDatetime,
+        Field(..., description=SpecDoc.EPISODE_CREATED_AT),
+    ]
+
+    producer_id: Annotated[
+        str,
+        Field(..., description=SpecDoc.EPISODE_PRODUCER_ID),
+    ]
+    producer_role: Annotated[
+        str,
+        Field(..., description=SpecDoc.EPISODE_PRODUCER_ROLE),
+    ]
+    produced_for_id: Annotated[
+        str | None,
+        Field(default=None, description=SpecDoc.EPISODE_PRODUCED_FOR_ID),
+    ]
+
+    sequence_num: Annotated[
+        int,
+        Field(default=0, description=SpecDoc.EPISODE_SEQUENCE_NUM),
+    ]
+
+    episode_type: Annotated[
+        EpisodeType,
+        Field(default=EpisodeType.MESSAGE, description=SpecDoc.EPISODE_TYPE),
+    ]
+    content_type: Annotated[
+        ContentType,
+        Field(default=ContentType.STRING, description=SpecDoc.EPISODE_CONTENT_TYPE),
+    ]
+    filterable_metadata: Annotated[
+        dict[str, Any] | None,
+        Field(default=None, description=SpecDoc.EPISODE_FILTERABLE_METADATA),
+    ]
+    metadata: Annotated[
+        dict[str, JsonValue] | None,
+        Field(default=None, description=SpecDoc.EPISODE_METADATA),
+    ]
+
+    def __hash__(self) -> int:
+        """Hash an episode by its UID."""
+        return hash(self.uid)
+
+
+SetIdT = str
+FeatureIdT = str
+
+
+class SemanticFeature(BaseModel):
+    """Semantic memory entry returned in API responses."""
+
+    class Metadata(BaseModel):
+        """Storage metadata for a semantic feature, including id and citations."""
+
+        citations: Annotated[
+            list[EpisodeIdT] | None,
+            Field(default=None, description=SpecDoc.SEMANTIC_METADATA_CITATIONS),
+        ]
+        id: Annotated[
+            FeatureIdT | None,
+            Field(default=None, description=SpecDoc.SEMANTIC_METADATA_ID),
+        ]
+        other: Annotated[
+            dict[str, Any] | None,
+            Field(default=None, description=SpecDoc.SEMANTIC_METADATA_OTHER),
+        ]
+
+    set_id: Annotated[
+        SetIdT | None,
+        Field(default=None, description=SpecDoc.SEMANTIC_SET_ID),
+    ]
+    category: Annotated[
+        str,
+        Field(..., description=SpecDoc.SEMANTIC_CATEGORY),
+    ]
+    tag: Annotated[
+        str,
+        Field(..., description=SpecDoc.SEMANTIC_TAG),
+    ]
+    feature_name: Annotated[
+        str,
+        Field(..., description=SpecDoc.SEMANTIC_FEATURE_NAME),
+    ]
+    value: Annotated[
+        str,
+        Field(..., description=SpecDoc.SEMANTIC_VALUE),
+    ]
+    metadata: Annotated[
+        Metadata,
+        Field(default_factory=Metadata, description=SpecDoc.SEMANTIC_METADATA),
+    ]
+
+
 class InvalidNameError(ValueError):
     """Custom error for invalid names."""
 
@@ -240,6 +436,7 @@ class DeleteProjectSpec(BaseModel):
     ]
 
 
+# Type alias for timestamp input
 TimestampInput = datetime | int | float | str | None
 
 
@@ -392,6 +589,14 @@ class SearchMemoriesSpec(_WithOrgAndProj):
             examples=Examples.FILTER_MEM,
         ),
     ]
+    score_threshold: Annotated[
+        float | None,
+        Field(
+            default=None,
+            description=SpecDoc.SCORE_THRESHOLD,
+            examples=Examples.SCORE_THRESHOLD,
+        ),
+    ]
     types: Annotated[
         list[MemoryType],
         Field(
@@ -526,7 +731,77 @@ class SearchResult(BaseModel):
         ),
     ]
     content: Annotated[
-        dict[str, Any],
+        "SearchResultContent",
+        Field(
+            ...,
+            description=SpecDoc.CONTENT,
+        ),
+    ]
+
+
+class EpisodicSearchShortTermMemory(BaseModel):
+    """Short-term episodic memory search results."""
+
+    episodes: Annotated[
+        list[EpisodeResponse],
+        Field(..., description=SpecDoc.EPISODIC_SHORT_EPISODES),
+    ]
+    episode_summary: Annotated[
+        list[str],
+        Field(..., description=SpecDoc.EPISODIC_SHORT_SUMMARY),
+    ]
+
+
+class EpisodicSearchLongTermMemory(BaseModel):
+    """Long-term episodic memory search results."""
+
+    episodes: Annotated[
+        list[EpisodeResponse],
+        Field(..., description=SpecDoc.EPISODIC_LONG_EPISODES),
+    ]
+
+
+class EpisodicSearchResult(BaseModel):
+    """Episodic payload returned by `/memories/search`."""
+
+    long_term_memory: Annotated[
+        EpisodicSearchLongTermMemory,
+        Field(..., description=SpecDoc.EPISODIC_LONG_TERM),
+    ]
+    short_term_memory: Annotated[
+        EpisodicSearchShortTermMemory,
+        Field(..., description=SpecDoc.EPISODIC_SHORT_TERM),
+    ]
+
+
+class SearchResultContent(BaseModel):
+    """Payload for SearchResult.content returned by `/memories/search`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    episodic_memory: Annotated[
+        EpisodicSearchResult | None,
+        Field(default=None, description=SpecDoc.SEARCH_EPISODIC_MEMORY),
+    ]
+    semantic_memory: Annotated[
+        list[SemanticFeature] | None,
+        Field(default=None, description=SpecDoc.SEARCH_SEMANTIC_MEMORY),
+    ]
+
+
+class ListResult(BaseModel):
+    """Response model for memory list results."""
+
+    status: Annotated[
+        int,
+        Field(
+            default=0,
+            description=SpecDoc.STATUS,
+            examples=Examples.SEARCH_RESULT_STATUS,
+        ),
+    ]
+    content: Annotated[
+        "ListResultContent",
         Field(
             ...,
             description=SpecDoc.CONTENT,
@@ -534,6 +809,21 @@ class SearchResult(BaseModel):
     ]
 
 
+class ListResultContent(BaseModel):
+    """Payload for ListResult.content returned by `/memories/list`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    episodic_memory: Annotated[
+        list[Episode] | None,
+        Field(default=None, description=SpecDoc.LIST_EPISODIC_MEMORY),
+    ]
+    semantic_memory: Annotated[
+        list[SemanticFeature] | None,
+        Field(default=None, description=SpecDoc.LIST_SEMANTIC_MEMORY),
+    ]
+
+
 class RestErrorModel(BaseModel):
     """Model representing an error response."""
 
@@ -573,3 +863,33 @@ class RestErrorModel(BaseModel):
             description=SpecDoc.ERROR_TRACE,
         ),
     ]
+
+
+class Version(BaseModel):
+    """Model representing version information."""
+
+    server_version: Annotated[
+        str,
+        Field(
+            ...,
+            description=SpecDoc.SERVER_VERSION,
+            examples=Examples.SERVER_VERSION,
+        ),
+    ]
+    client_version: Annotated[
+        str,
+        Field(
+            ...,
+            description=SpecDoc.CLIENT_VERSION,
+            examples=Examples.CLIENT_VERSION,
+        ),
+    ]
+
+    def __str__(self) -> str:
+        """Return the version as a string."""
+        return "\n".join(
+            [
+                f"server: {self.server_version}",
+                f"client: {self.client_version}",
+            ]
+        )

memmachine_server-0.2.4/src/memmachine/common/api/version.py

@@ -0,0 +1,21 @@
+"""version information."""
+
+import contextlib
+from importlib.metadata import PackageNotFoundError, version
+
+from memmachine.common.api.spec import Version
+
+
+def _get_package_version(package_name: str) -> str:
+    ret = "not available"
+    with contextlib.suppress(PackageNotFoundError):
+        ret = version(package_name)
+    return ret
+
+
+def get_version() -> Version:
+    """Get the server and client version information."""
+    return Version(
+        server_version=_get_package_version("memmachine-server"),
+        client_version=_get_package_version("memmachine-client"),
+    )

{memmachine_server-0.2.2 → memmachine_server-0.2.4}/src/memmachine/common/configuration/database_conf.py

@@ -32,6 +32,34 @@ class Neo4jConf(YamlSerializableMixin, PasswordMixin):
         default=False,
         description="Whether to force exact similarity search",
     )
+    range_index_creation_threshold: int | None = Field(
+        default=None,
+        description=(
+            "Minimum number of entities in a collection or relationship "
+            "required before Neo4j automatically creates a range index."
+        ),
+    )
+    vector_index_creation_threshold: int | None = Field(
+        default=None,
+        description=(
+            "Minimum number of entities in a collection or relationship "
+            "required before Neo4j automatically creates a vector index."
+        ),
+    )
+    max_connection_pool_size: int | None = Field(
+        default=None,
+        description=(
+            "Maximum number of connections to maintain in the connection pool. "
+            "Internal default is 100."
+        ),
+    )
+    connection_acquisition_timeout: float | None = Field(
+        default=None,
+        description=(
+            "Maximum time in seconds to wait for a connection from the pool. "
+            "Internal default is 60.0."
+        ),
+    )
 
     def get_uri(self) -> str:
         if self.uri:
@@ -60,6 +88,21 @@ class SqlAlchemyConf(YamlSerializableMixin, PasswordMixin):
         ),
     )
     db_name: str | None = Field(default=None, description="DB name")
+    pool_size: int | None = Field(
+        default=None,
+        description=(
+            "Number of persistent connections to maintain in the connection pool. "
+            "If set, the pool will keep up to this many open connections ready for use."
+        ),
+    )
+    max_overflow: int | None = Field(
+        default=None,
+        description=(
+            "Maximum number of temporary connections allowed above `pool_size` during "
+            "traffic spikes. These overflow connections are created on demand and "
+            "disposed of when no longer needed."
+        ),
+    )
 
     @property
     def schema_part(self) -> str: