dlightrag-memory 2.0.0__py3-none-any.whl

dlightrag_memory/memory.py

@@ -0,0 +1,260 @@
+# Copyright 2025-2026 Hanlian Lu. SPDX-License-Identifier: Apache-2.0
+"""The host-neutral Profile Memory façade."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+
+from dlightrag_memory.fusion import rrf_fuse
+from dlightrag_memory.models import (
+    MemoryKind,
+    MemoryOperation,
+    MemoryOperationReceipt,
+    MemoryProvenance,
+    MemoryRecord,
+)
+from dlightrag_memory.policy import (
+    RECALL_CHAR_BUDGET,
+    RECALL_TOP_K,
+    evaluate_memory_operation,
+)
+from dlightrag_memory.ports import SearchCandidate
+from dlightrag_memory.recall import recall_recency
+from dlightrag_memory.store import MemoryStore, OperationGuard
+
+_SEARCH_DEADLINE_SECONDS = 2.0
+_HEADER_CHARS = 160
+
+
+@dataclass(frozen=True, slots=True)
+class RecallResult:
+    """Structured query-aware recall result."""
+
+    records: tuple[MemoryRecord, ...]
+    strategy: str
+    candidates: tuple[SearchCandidate, ...] = ()
+    degraded: tuple[str, ...] = ()
+    content_chars: int = 0
+
+    @property
+    def skipped(self) -> bool:
+        return bool(self.degraded)
+
+
+class Memory:
+    """Cross-conversation owner Profile Memory behind one deep mutation seam."""
+
+    def __init__(self, store: MemoryStore) -> None:
+        self._store = store
+
+    async def apply(
+        self,
+        operation: MemoryOperation,
+        *,
+        guard: OperationGuard | None = None,
+    ) -> MemoryOperationReceipt:
+        """Validate and atomically settle one idempotent operation."""
+        evaluate_memory_operation(operation)
+        return await self._store.apply_operation(operation, guard=guard)
+
+    async def remember(
+        self,
+        *,
+        owner_id: str,
+        kind: MemoryKind,
+        body: str,
+        provenance: MemoryProvenance,
+        idempotency_key: str,
+        supersedes_id: str | None = None,
+        mutation_scope: str | None = None,
+        mutation_limit: int | None = None,
+        guard: OperationGuard | None = None,
+    ) -> MemoryOperationReceipt:
+        return await self.apply(
+            MemoryOperation(
+                owner_id=owner_id,
+                idempotency_key=idempotency_key,
+                action="remember",
+                provenance=provenance,
+                kind=kind,
+                body=body,
+                supersedes_id=supersedes_id,
+                mutation_scope=mutation_scope,
+                mutation_limit=mutation_limit,
+            ),
+            guard=guard,
+        )
+
+    async def forget(
+        self,
+        *,
+        owner_id: str,
+        provenance: MemoryProvenance,
+        idempotency_key: str,
+        memory_id: str | None = None,
+        body: str | None = None,
+        mutation_scope: str | None = None,
+        mutation_limit: int | None = None,
+        guard: OperationGuard | None = None,
+    ) -> MemoryOperationReceipt:
+        return await self.apply(
+            MemoryOperation(
+                owner_id=owner_id,
+                idempotency_key=idempotency_key,
+                action="forget",
+                provenance=provenance,
+                memory_id=memory_id,
+                body=body or "",
+                mutation_scope=mutation_scope,
+                mutation_limit=mutation_limit,
+            ),
+            guard=guard,
+        )
+
+    async def undo(
+        self,
+        *,
+        owner_id: str,
+        change_id: str,
+        provenance: MemoryProvenance,
+        idempotency_key: str,
+        guard: OperationGuard | None = None,
+    ) -> MemoryOperationReceipt:
+        return await self.apply(
+            MemoryOperation(
+                owner_id=owner_id,
+                idempotency_key=idempotency_key,
+                action="undo",
+                provenance=provenance,
+                target_change_id=change_id,
+            ),
+            guard=guard,
+        )
+
+    async def clear(
+        self,
+        *,
+        owner_id: str,
+        guard: OperationGuard | None = None,
+    ) -> int:
+        """Physically erase one owner's complete Profile Memory schema state."""
+        return await self._store.clear_owner(owner_id=owner_id, guard=guard)
+
+    async def count_active(self, *, owner_id: str) -> int:
+        return await self._store.count_active(owner_id=owner_id)
+
+    async def browse(
+        self,
+        *,
+        owner_id: str,
+        cursor: tuple[datetime, str] | None = None,
+        limit: int = 50,
+    ) -> tuple[tuple[MemoryRecord, ...], tuple[datetime, str] | None]:
+        return await self._store.list_active_page(owner_id=owner_id, after=cursor, limit=limit)
+
+    async def recall(
+        self,
+        *,
+        owner_id: str,
+        query: str,
+        top_k: int = RECALL_TOP_K,
+        char_budget: int = RECALL_CHAR_BUDGET,
+    ) -> RecallResult:
+        cap = max(1, min(int(top_k), 100))
+        budget = max(_HEADER_CHARS, int(char_budget))
+        try:
+            candidates = await asyncio.wait_for(
+                self._store.search_candidates(owner_id=owner_id, query=query, limit=cap),
+                timeout=_SEARCH_DEADLINE_SECONDS,
+            )
+        except TimeoutError:
+            page, _ = await self._store.list_active_page(owner_id=owner_id, limit=cap)
+            recent = _truncate_to_budget(list(page), budget=budget)
+            recent.sort(key=lambda record: (recall_recency(record), record.memory_id))
+            return RecallResult(
+                records=tuple(recent),
+                strategy="recent_fallback",
+                degraded=("search_timeout",),
+                content_chars=sum(len(record.body) for record in recent),
+            )
+
+        exact_ids: list[str] = []
+        fused_ids: dict[str, float] = {}
+        rankings: list[list[str]] = []
+        for leg in ("exact", "sparse", "dense"):
+            ranking: list[str] = []
+            for candidate in candidates:
+                if candidate.leg != leg or candidate.record.memory_id in ranking:
+                    continue
+                ranking.append(candidate.record.memory_id)
+            if leg == "exact":
+                exact_ids = ranking
+            else:
+                rankings.append(ranking)
+        fused_ids.update(rrf_fuse(rankings))
+
+        by_id = {candidate.record.memory_id: candidate.record for candidate in candidates}
+        exact_records = [by_id[memory_id] for memory_id in exact_ids if memory_id in by_id]
+        ranked_records = [
+            by_id[memory_id]
+            for memory_id, _ in sorted(
+                (
+                    (memory_id, score)
+                    for memory_id, score in fused_ids.items()
+                    if memory_id not in exact_ids
+                ),
+                key=lambda item: item[1],
+                reverse=True,
+            )
+            if memory_id in by_id
+        ]
+        ordered = _packing_prior([*exact_records, *ranked_records])[:cap]
+        ordered = _truncate_to_budget(ordered, budget=budget)
+        exact_set = set(exact_ids)
+        exact_block = [record for record in ordered if record.memory_id in exact_set]
+        rest = [record for record in ordered if record.memory_id not in exact_set]
+        exact_block.sort(key=lambda record: (recall_recency(record), record.memory_id))
+        rest.sort(key=lambda record: (recall_recency(record), record.memory_id))
+        ordered = [*exact_block, *rest]
+        return RecallResult(
+            records=tuple(ordered),
+            strategy="query_search",
+            candidates=tuple(candidates),
+            content_chars=sum(len(record.body) for record in ordered),
+        )
+
+    async def purge_superseded(self, *, older_than: datetime) -> int:
+        return await self._store.purge_superseded(older_than=older_than)
+
+
+def _packing_prior(records: list[MemoryRecord]) -> list[MemoryRecord]:
+    if not records:
+        return records
+    first_preference = next((record for record in records if record.kind == "preference"), None)
+    first_fact = next((record for record in records if record.kind == "fact"), None)
+    if first_preference is None or first_fact is None:
+        return records
+    kept = [first_preference, first_fact]
+    kept.extend(
+        record
+        for record in records
+        if record.memory_id not in {first_preference.memory_id, first_fact.memory_id}
+    )
+    return kept
+
+
+def _truncate_to_budget(records: list[MemoryRecord], *, budget: int) -> list[MemoryRecord]:
+    kept: list[MemoryRecord] = []
+    used = _HEADER_CHARS
+    for record in records:
+        cost = len(record.body)
+        if used + cost > budget and kept:
+            break
+        kept.append(record)
+        used += cost
+    return kept
+
+
+__all__ = ["Memory", "RecallResult"]

dlightrag_memory/models.py

@@ -0,0 +1,95 @@
+# Copyright 2025-2026 Hanlian Lu. SPDX-License-Identifier: Apache-2.0
+"""Owner-scoped Profile Memory records, operations, and receipts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+MemoryKind = Literal["preference", "fact"]
+MemoryStatus = Literal["active", "superseded", "forgotten"]
+MemoryOriginKind = Literal["answer_run", "management", "mcp", "undo"]
+MemoryOperationAction = Literal["remember", "forget", "undo"]
+MemoryOperationOutcome = Literal["changed", "unchanged", "conflict"]
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryProvenance:
+    """Trusted host-bound source of one Memory operation."""
+
+    origin_kind: MemoryOriginKind
+    origin_id: str
+    run_id: str | None = None
+    session_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryRecord:
+    """One owner-scoped, non-citable remembered preference or fact."""
+
+    owner_id: str
+    memory_id: str
+    kind: MemoryKind
+    body: str
+    provenance: MemoryProvenance
+    status: MemoryStatus = "active"
+    supersedes_id: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryOperation:
+    """One canonical, idempotent mutation request at the storage seam."""
+
+    owner_id: str
+    idempotency_key: str
+    action: MemoryOperationAction
+    provenance: MemoryProvenance
+    kind: MemoryKind | None = None
+    body: str = ""
+    memory_id: str | None = None
+    supersedes_id: str | None = None
+    target_change_id: str | None = None
+    mutation_scope: str | None = None
+    mutation_limit: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryOperationReceipt:
+    """Replay-stable result of one settled Memory operation."""
+
+    change_id: str
+    action: MemoryOperationAction
+    outcome: MemoryOperationOutcome
+    memory_ids: tuple[str, ...]
+    provenance: MemoryProvenance
+    kind: MemoryKind | None = None
+    body: str = ""
+    supersedes_id: str | None = None
+    target_change_id: str | None = None
+    mutation_scope: str | None = None
+    created_at: datetime | None = None
+
+    @property
+    def memory_id(self) -> str | None:
+        """The primary affected record, when the operation has one."""
+        return self.memory_ids[0] if self.memory_ids else None
+
+    @property
+    def changed(self) -> bool:
+        return self.outcome == "changed"
+
+
+__all__ = [
+    "MemoryKind",
+    "MemoryOperation",
+    "MemoryOperationAction",
+    "MemoryOperationOutcome",
+    "MemoryOperationReceipt",
+    "MemoryOriginKind",
+    "MemoryProvenance",
+    "MemoryRecord",
+    "MemoryStatus",
+]

dlightrag_memory/normalize.py

@@ -0,0 +1,24 @@
+# Copyright 2025-2026 Hanlian Lu. SPDX-License-Identifier: Apache-2.0
+"""Canonical body normalization for the exact-match recall leg.
+
+One pure function shared by every storage adapter so equality semantics never
+drift between backends: NFKC (fullwidth/halfwidth and compatibility forms),
+casefold, and internal-whitespace collapse. Language-agnostic — CJK fullwidth
+and Latin case both normalize here.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+
+_WHITESPACE = " \t\r\n"
+
+
+def normalized_body(text: str) -> str:
+    """Return one canonical comparison key for a memory body."""
+    folded = unicodedata.normalize("NFKC", text).casefold()
+    stripped = "".join(" " if char in _WHITESPACE else char for char in folded)
+    return " ".join(stripped.split())
+
+
+__all__ = ["normalized_body"]

dlightrag_memory/policy.py

@@ -0,0 +1,82 @@
+# Copyright 2025-2026 Hanlian Lu. SPDX-License-Identifier: Apache-2.0
+"""Closed Profile Memory operation checklist and fixed safety bounds."""
+
+from __future__ import annotations
+
+import re
+
+from dlightrag_memory.errors import MemoryWriteRejectedError
+from dlightrag_memory.models import MemoryOperation
+
+MEMORY_BODY_LIMIT = 500
+RECALL_TOP_K = 10
+RECALL_CHAR_BUDGET = 4000
+MEMORY_SUPERSEDE_RETENTION_DAYS = 365
+
+_CITATION_MARK = re.compile(r"\[\d+(?:-\d+)?\]")
+_PRIVATE_KEY_MARK = re.compile(r"-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----", re.IGNORECASE)
+_TOKEN_MARK = re.compile(
+    r"(?:\bAKIA[0-9A-Z]{16}\b|\bgh[opusr]_[A-Za-z0-9_]{20,}\b|"
+    r"\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{20,}\b|"
+    r"\bsk-[A-Za-z0-9_-]{20,}\b)"
+)
+
+
+def evaluate_memory_operation(operation: MemoryOperation) -> None:
+    """Validate one operation before any storage mutation."""
+    if not operation.owner_id.strip():
+        raise MemoryWriteRejectedError("A Memory operation needs an owner.")
+    if not operation.idempotency_key.strip():
+        raise MemoryWriteRejectedError("A Memory operation needs an idempotency key.")
+    if len(operation.idempotency_key) > 255:
+        raise MemoryWriteRejectedError("Memory idempotency keys cannot exceed 255 characters.")
+    if not operation.provenance.origin_id.strip():
+        raise MemoryWriteRejectedError("A Memory operation needs trusted provenance.")
+    if operation.mutation_limit is not None and operation.mutation_limit < 1:
+        raise MemoryWriteRejectedError("A Memory mutation limit must be positive.")
+    if (operation.mutation_scope is None) != (operation.mutation_limit is None):
+        raise MemoryWriteRejectedError("Memory mutation scope and limit must be provided together.")
+
+    body = operation.body.strip()
+    if operation.action == "remember":
+        if operation.kind not in {"preference", "fact"}:
+            raise MemoryWriteRejectedError("Memory kind must be preference or fact.")
+        if not body:
+            raise MemoryWriteRejectedError("Memory body cannot be empty.")
+        if len(body) > MEMORY_BODY_LIMIT:
+            raise MemoryWriteRejectedError(
+                f"Memory body cannot exceed {MEMORY_BODY_LIMIT} characters."
+            )
+        if operation.memory_id is not None or operation.target_change_id is not None:
+            raise MemoryWriteRejectedError("Remember received an incompatible target.")
+        if _CITATION_MARK.search(body):
+            raise MemoryWriteRejectedError("Memory body cannot carry citation markers.")
+        if _PRIVATE_KEY_MARK.search(body) or _TOKEN_MARK.search(body):
+            raise MemoryWriteRejectedError("Credentials and private keys cannot be remembered.")
+        return
+
+    if operation.action == "forget":
+        selectors = sum(bool(value and value.strip()) for value in (operation.memory_id, body))
+        if selectors != 1:
+            raise MemoryWriteRejectedError("Forget needs exactly one memory id or exact body.")
+        if any((operation.kind, operation.supersedes_id, operation.target_change_id)):
+            raise MemoryWriteRejectedError("Forget received an incompatible target.")
+        return
+
+    if operation.action == "undo":
+        if not (operation.target_change_id or "").strip():
+            raise MemoryWriteRejectedError("Undo needs a change id.")
+        if any((operation.kind, body, operation.memory_id, operation.supersedes_id)):
+            raise MemoryWriteRejectedError("Undo received an incompatible target.")
+        return
+
+    raise MemoryWriteRejectedError("Unknown Memory operation.")
+
+
+__all__ = [
+    "MEMORY_BODY_LIMIT",
+    "MEMORY_SUPERSEDE_RETENTION_DAYS",
+    "RECALL_CHAR_BUDGET",
+    "RECALL_TOP_K",
+    "evaluate_memory_operation",
+]

dlightrag_memory/ports.py

@@ -0,0 +1,79 @@
+# Copyright 2025-2026 Hanlian Lu. SPDX-License-Identifier: Apache-2.0
+"""Storage-neutral ports: text embedding and recall candidate shapes.
+
+These ports are the P4 substrate. ``TextEmbedder`` keeps dense recall optional
+and backend-independent; ``NullEmbedder`` is the zero-configuration default
+for standalone hosts (sparse + exact legs only). ``SearchCandidate`` is the
+leg-tagged candidate a storage adapter returns in per-leg rank order.
+PostgreSQL-specific connection and migration shapes live in ``_storage.pg``,
+not here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal, Protocol
+
+from dlightrag_memory.models import MemoryRecord
+
+type Vector = Sequence[float]
+
+
+class TextEmbedder(Protocol):
+    """Produce one embedding space for memory bodies.
+
+    ``embedding_fingerprint`` identifies the embedding model; an adapter
+    stores it with every vector so a model change invalidates the dense index
+    instead of silently comparing across spaces.
+    """
+
+    @property
+    def embedding_fingerprint(self) -> str: ...
+
+    dim: int
+
+    async def embed_documents(self, texts: Sequence[str]) -> Sequence[Vector]: ...
+
+    async def embed_query(self, text: str) -> Vector: ...
+
+
+class NullEmbedder:
+    """The zero-configuration embedder: dense recall stays off."""
+
+    dim = 0
+
+    @property
+    def embedding_fingerprint(self) -> str:
+        return "none"
+
+    async def aclose(self) -> None:
+        return None
+
+    async def embed_documents(self, texts: Sequence[str]) -> Sequence[Vector]:
+        raise RuntimeError("NullEmbedder produces no vectors; disable the dense leg")
+
+    async def embed_query(self, text: str) -> Vector:
+        raise RuntimeError("NullEmbedder produces no vectors; disable the dense leg")
+
+
+SearchLeg = Literal["dense", "sparse", "exact"]
+
+
+class SearchCandidate:
+    """One recalled record with its source leg and a comparable score."""
+
+    __slots__ = ("record", "leg", "score")
+
+    def __init__(self, *, record: MemoryRecord, leg: SearchLeg, score: float) -> None:
+        self.record = record
+        self.leg = leg
+        self.score = score
+
+
+__all__ = [
+    "NullEmbedder",
+    "SearchCandidate",
+    "SearchLeg",
+    "TextEmbedder",
+    "Vector",
+]

dlightrag_memory/postgres.py

@@ -0,0 +1,13 @@
+# Copyright 2025-2026 Hanlian Lu. SPDX-License-Identifier: Apache-2.0
+"""PostgreSQL storage entry point for the Memory package.
+
+Kept out of the package ``__init__`` so importing the core never drags the
+database adapter into an embedding host's import graph; hosts that use
+PostgreSQL import it directly:
+
+    from dlightrag_memory.postgres import PostgresMemoryStore
+"""
+
+from dlightrag_memory._storage.pg import PostgresMemoryStore
+
+__all__ = ["PostgresMemoryStore"]

dlightrag_memory/recall.py

@@ -0,0 +1,25 @@
+# Copyright 2025-2026 Hanlian Lu. SPDX-License-Identifier: Apache-2.0
+"""Recency ordering for record tie-breaks.
+
+Query relevance decides the candidate set (fusion in ``fusion.py``); time is
+never a score component — it only orders presentation and breaks ties, the
+same design MemMachine uses.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from dlightrag_memory.models import MemoryRecord
+
+
+def recall_recency(record: MemoryRecord) -> datetime:
+    """One record's standing-ordering timestamp."""
+    if record.updated_at is not None:
+        return record.updated_at
+    if record.created_at is not None:
+        return record.created_at
+    return datetime.min.replace(tzinfo=UTC)
+
+
+__all__ = ["recall_recency"]