memry 0.2.0__py3-none-any.whl

memry/__init__.py

@@ -0,0 +1,36 @@
+"""Memry - the open, self-hostable memory layer for AI agents. https://memry.tech"""
+
+from .config import Config, DecayConfig, EmbeddingConfig, LLMConfig, RetrievalConfig
+from .models import (
+    AddAction,
+    AddResult,
+    CandidateFact,
+    ContextResult,
+    Episode,
+    Memory,
+    MemoryEvent,
+    Scope,
+    SearchResult,
+)
+from .store import MemoryStore
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "MemoryStore",
+    "Config",
+    "LLMConfig",
+    "EmbeddingConfig",
+    "RetrievalConfig",
+    "DecayConfig",
+    "Memory",
+    "Episode",
+    "MemoryEvent",
+    "Scope",
+    "SearchResult",
+    "AddResult",
+    "AddAction",
+    "CandidateFact",
+    "ContextResult",
+    "__version__",
+]

memry/backends/__init__.py

@@ -0,0 +1,18 @@
+from .base import MemoryBackend
+
+
+def build_backend(config) -> MemoryBackend:
+    if config.backend == "mem0":
+        from .mem0_adapter import Mem0Backend
+
+        return Mem0Backend(config)
+    if config.backend == "postgres":
+        from .postgres import PostgresBackend
+
+        return PostgresBackend(config)
+    from .local import LocalBackend
+
+    return LocalBackend(config.db_path, ann=config.ann)
+
+
+__all__ = ["MemoryBackend", "build_backend"]

memry/backends/ann.py

@@ -0,0 +1,102 @@
+"""Optional HNSW sidecar index (usearch) for approximate nearest-neighbor
+search at scale.
+
+Install with ``pip install memry[ann]``. Without it - or below the configured
+row threshold - LocalBackend uses exact brute-force cosine, which is faster at
+small sizes anyway. The sidecar is a cache, never the source of truth: it can
+be deleted at any time and is rebuilt from SQLite (``memry reindex`` or lazily
+on model mismatch). ANN results are always exact-rescored before ranking.
+
+Keys are stable integers from the ``ann_keys`` table (SQLite rowids can be
+renumbered by VACUUM, so they are not used directly).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+try:  # pragma: no cover - environment dependent
+    from usearch.index import Index as _UsearchIndex
+
+    HAS_USEARCH = True
+except ImportError:  # pragma: no cover
+    _UsearchIndex = None
+    HAS_USEARCH = False
+
+
+class HnswSidecar:
+    """Persisted usearch index keyed by ann_keys.key."""
+
+    def __init__(self, db_path: str, dimensions: int, model_id: str) -> None:
+        self.dimensions = dimensions
+        self.model_id = model_id
+        self._persist = db_path != ":memory:"
+        self.index_path = Path(f"{db_path}.usearch") if self._persist else None
+        self.meta_path = Path(f"{db_path}.usearch.json") if self._persist else None
+        self.index = _UsearchIndex(ndim=dimensions, metric="cos")
+        self._loaded_ok = self._try_load()
+
+    @property
+    def size(self) -> int:
+        return len(self.index)
+
+    @property
+    def needs_rebuild(self) -> bool:
+        return not self._loaded_ok
+
+    def _try_load(self) -> bool:
+        if not self._persist or self.index_path is None or not self.index_path.exists():
+            return False
+        try:
+            meta = json.loads(self.meta_path.read_text(encoding="utf-8"))
+            if meta.get("model_id") != self.model_id or meta.get("dimensions") != self.dimensions:
+                return False
+            self.index.load(str(self.index_path))
+            return True
+        except Exception:
+            return False
+
+    def save(self) -> None:
+        if not self._persist or self.index_path is None:
+            return
+        try:
+            self.index.save(str(self.index_path))
+            self.meta_path.write_text(
+                json.dumps({"model_id": self.model_id, "dimensions": self.dimensions}),
+                encoding="utf-8",
+            )
+        except Exception:
+            pass  # the sidecar is a cache; persistence failures must not break writes
+
+    def add(self, key: int, vector: list[float]) -> None:
+        vec = np.asarray(vector, dtype=np.float32)
+        try:
+            if self.index.contains(key):
+                self.index.remove(key)
+            self.index.add(key, vec)
+        except Exception:
+            self._loaded_ok = False  # force rebuild on next opportunity
+
+    def remove(self, key: int) -> None:
+        try:
+            if self.index.contains(key):
+                self.index.remove(key)
+        except Exception:
+            self._loaded_ok = False
+
+    def search(self, vector: list[float], k: int) -> list[int]:
+        vec = np.asarray(vector, dtype=np.float32)
+        matches = self.index.search(vec, k)
+        keys = np.asarray(matches.keys).reshape(-1)
+        return [int(key) for key in keys]
+
+    def rebuild(self, items: list[tuple[int, bytes]]) -> None:
+        """items: (key, float32-blob) pairs for every active memory."""
+        self.index = _UsearchIndex(ndim=self.dimensions, metric="cos")
+        for key, blob in items:
+            self.index.add(key, np.frombuffer(blob, dtype=np.float32))
+        self._loaded_ok = True
+        self.save()

memry/backends/base.py

@@ -0,0 +1,173 @@
+"""Storage backend interface.
+
+The application layer (``MemoryStore``) and the intelligence layer only ever
+talk to this interface, so backends are replaceable: the default is the local
+SQLite engine; a Mem0 adapter ships as an optional interop/benchmark backend,
+and Postgres/Qdrant/etc. can be added without touching callers.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..models import Entity, EntityMention, Episode, Memory, MemoryEvent, MergeProposal, Scope
+
+
+class MemoryBackend(ABC):
+    """Persistence contract: episodes (raw), memories (derived), events (audit)."""
+
+    # -- episodes -------------------------------------------------------
+    @abstractmethod
+    def add_episodes(self, episodes: list[Episode]) -> None: ...
+
+    @abstractmethod
+    def list_episodes(self, scope: Scope, limit: int = 100) -> list[Episode]: ...
+
+    # -- memories -------------------------------------------------------
+    @abstractmethod
+    def insert_memory(self, memory: Memory, embedding: list[float] | None = None) -> Memory:
+        """Persist a new memory. Returns the stored memory (backends may
+        assign their own id)."""
+
+    @abstractmethod
+    def update_memory(
+        self,
+        memory_id: str,
+        *,
+        content: str | None = None,
+        embedding: list[float] | None = None,
+        embedding_model: str | None = None,
+        importance: float | None = None,
+        memory_type: str | None = None,
+        categories: list[str] | None = None,
+        entities: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        source_episode_ids: list[str] | None = None,
+    ) -> Memory | None: ...
+
+    @abstractmethod
+    def invalidate_memory(
+        self, memory_id: str, *, superseded_by: str | None = None
+    ) -> Memory | None:
+        """Temporal soft-delete: mark the memory as no longer valid."""
+
+    @abstractmethod
+    def delete_memory(self, memory_id: str) -> bool:
+        """Hard delete (rarely what you want; prefer invalidate)."""
+
+    @abstractmethod
+    def get_memory(self, memory_id: str) -> Memory | None: ...
+
+    @abstractmethod
+    def list_memories(
+        self,
+        scope: Scope,
+        *,
+        include_invalid: bool = False,
+        limit: int = 100,
+        offset: int = 0,
+        categories: list[str] | None = None,
+    ) -> list[Memory]: ...
+
+    # -- search primitives ---------------------------------------------
+    @abstractmethod
+    def vector_search(
+        self,
+        embedding: list[float],
+        embedding_model: str,
+        scope: Scope,
+        limit: int = 20,
+        include_invalid: bool = False,
+        categories: list[str] | None = None,
+    ) -> list[tuple[Memory, float]]:
+        """Cosine similarity over stored vectors (same embedding model only)."""
+
+    @abstractmethod
+    def keyword_search(
+        self,
+        query: str,
+        scope: Scope,
+        limit: int = 20,
+        include_invalid: bool = False,
+        categories: list[str] | None = None,
+    ) -> list[tuple[Memory, float]]:
+        """Full-text (BM25) search. Higher score = better."""
+
+    def native_search(
+        self, query: str, scope: Scope, limit: int = 20
+    ) -> list[tuple[Memory, float]] | None:
+        """Backends with their own fused retrieval (e.g. Mem0) return results
+        here; ``None`` means "use memry's hybrid fusion" (the default)."""
+        return None
+
+    # -- entities ---------------------------------------------------------
+    # Default implementations are no-ops so adapters without entity support
+    # (e.g. Mem0) stay valid; LocalBackend and PostgresBackend override all.
+    def insert_entity(self, entity: Entity) -> Entity:
+        return entity
+
+    def get_entity(self, entity_id: str) -> Entity | None:
+        return None
+
+    def find_entities(self, normalized: str, scope: Scope) -> list[Entity]:
+        """Active (unmerged) entities with this normalized name, in scope."""
+        return []
+
+    def list_entities(
+        self, scope: Scope, *, include_merged: bool = False, limit: int = 100
+    ) -> list[Entity]:
+        return []
+
+    def add_mention(self, mention: EntityMention) -> None:
+        return None
+
+    def entity_mentions(self, entity_id: str) -> list[EntityMention]:
+        return []
+
+    def entity_memories(self, entity_id: str, limit: int = 10) -> list[Memory]:
+        """Memories that mention this entity (following merges)."""
+        return []
+
+    def merge_entities(self, keep_id: str, merge_id: str) -> bool:
+        """Fold ``merge_id`` into ``keep_id`` (repoint mentions, mark merged)."""
+        return False
+
+    def add_proposal(self, proposal: MergeProposal) -> MergeProposal:
+        return proposal
+
+    def get_proposal(self, proposal_id: str) -> MergeProposal | None:
+        return None
+
+    def find_proposal(self, entity_a: str, entity_b: str) -> MergeProposal | None:
+        """Existing proposal for this unordered pair, any status."""
+        return None
+
+    def list_proposals(
+        self, scope: Scope, *, status: str | None = "proposed", limit: int = 100
+    ) -> list[MergeProposal]:
+        return []
+
+    def set_proposal_status(self, proposal_id: str, status: str) -> MergeProposal | None:
+        return None
+
+    # -- events / audit ---------------------------------------------------
+    @abstractmethod
+    def add_event(self, event: MemoryEvent) -> None: ...
+
+    @abstractmethod
+    def history(self, memory_id: str) -> list[MemoryEvent]: ...
+
+    # -- maintenance ------------------------------------------------------
+    @abstractmethod
+    def all_memories_iter(self, include_invalid: bool = True) -> list[Memory]:
+        """All memories, for reindexing/decay sweeps."""
+
+    @abstractmethod
+    def stats(self) -> dict[str, Any]: ...
+
+    @abstractmethod
+    def reset(self) -> None: ...
+
+    def close(self) -> None:  # pragma: no cover - trivial default
+        pass