korely-memory 0.1.0__py3-none-any.whl

korely_memory/__init__.py

@@ -0,0 +1,64 @@
+"""korely-memory — the Python SDK for Korely Agents.
+
+A typed, dependency-free client over the Korely REST API. Every method maps
+1:1 onto an endpoint; the moat (typed bi-temporal facts, contradiction
+checking) runs server-side.
+
+    from korely_memory import Korely
+
+    korely = Korely(api_key="kor_live_...", region="eu")
+    korely.add("User prefers TypeScript", agent_id="coding-assistant")
+    ctx = korely.get_context(query="what does the user like?", user_id="dana")
+"""
+from .client import Korely, __version__
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    KorelyError,
+    NamespaceForbiddenError,
+    NotFoundError,
+    QuotaExceededError,
+    StaleWriteError,
+)
+from .models import (
+    BatchJob,
+    BulkReceipt,
+    Context,
+    DeleteReceipt,
+    Fact,
+    HistoryEvent,
+    Memory,
+    MemoryHistory,
+    MemoryPage,
+    Profile,
+    SearchHit,
+    UserScope,
+    UsersPage,
+)
+
+__all__ = [
+    "Korely",
+    "__version__",
+    # exceptions
+    "KorelyError",
+    "AuthenticationError",
+    "NamespaceForbiddenError",
+    "NotFoundError",
+    "StaleWriteError",
+    "QuotaExceededError",
+    "APIError",
+    # models
+    "Memory",
+    "Fact",
+    "SearchHit",
+    "MemoryPage",
+    "DeleteReceipt",
+    "BulkReceipt",
+    "Context",
+    "BatchJob",
+    "Profile",
+    "HistoryEvent",
+    "MemoryHistory",
+    "UserScope",
+    "UsersPage",
+]

korely_memory/client.py

@@ -0,0 +1,308 @@
+"""The Korely client. A thin, dependency-free HTTP wrapper: every method maps
+1:1 onto a REST endpoint (see /agents/docs/surfaces/sdk). All the intelligence
+— embeddings, entity + typed-fact extraction, contradiction checking — runs
+server-side, so this stays a small client over stdlib urllib."""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, List, Optional
+from urllib import error as _urlerror
+from urllib import parse as _urlparse
+from urllib import request as _urlrequest
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    KorelyError,
+    NamespaceForbiddenError,
+    NotFoundError,
+    QuotaExceededError,
+    StaleWriteError,
+)
+from .models import (
+    BatchJob,
+    BulkReceipt,
+    Context,
+    DeleteReceipt,
+    Fact,
+    Memory,
+    MemoryHistory,
+    MemoryPage,
+    Profile,
+    SearchHit,
+    UserScope,
+    UsersPage,
+)
+
+__version__ = "0.1.0"
+
+# All keys are the EU region; data is stored and processed in the EU.
+_REGIONS = {"eu": "https://api.korely.ai"}
+
+
+def _clean(d: dict) -> dict:
+    """Drop None values so we never send null params/body fields."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _coerce_content(content: Any) -> str:
+    """add() accepts a string OR a list of chat messages
+    [{"role": ..., "content": ...}] (Mem0/Supermemory shape). A message list is
+    joined into one text block (``role: content`` per line) before sending —
+    the server stores and mines the resulting text. Empty or role-only messages
+    are dropped (no dangling ``role:`` lines)."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, (list, tuple)):
+        parts: List[str] = []
+        for m in content:
+            if isinstance(m, dict):
+                role = (m.get("role") or "").strip()
+                body = m.get("content")
+                body = "" if body is None else str(body).strip()
+                if role and body:
+                    parts.append(f"{role}: {body}")
+                elif body:
+                    parts.append(body)
+                # role-only / empty message → dropped
+            else:
+                s = str(m).strip()
+                if s:
+                    parts.append(s)
+        return "\n".join(parts)
+    return str(content)
+
+
+class Korely:
+    """Typed client over the Korely REST API.
+
+    >>> korely = Korely(api_key="kor_live_...", region="eu")
+    >>> korely.add("User prefers TypeScript", agent_id="coding-assistant")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        region: str = "eu",
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key or os.environ.get("KORELY_API_KEY")
+        if not self.api_key:
+            raise KorelyError(
+                "No API key. Pass api_key='kor_live_...' or set KORELY_API_KEY."
+            )
+        self.base_url = (base_url or _REGIONS.get(region) or _REGIONS["eu"]).rstrip("/")
+        self.timeout = timeout
+
+    # ── low-level transport (the one seam tests override) ──────────────────
+    def _send(self, method: str, path: str, *, params: Optional[dict] = None,
+              json_body: Optional[Any] = None) -> "tuple[int, dict]":
+        url = self.base_url + path
+        if params:
+            qs = _urlparse.urlencode(_clean(params), doseq=True)
+            if qs:
+                url += "?" + qs
+        data = json.dumps(json_body).encode("utf-8") if json_body is not None else None
+        headers = {
+            "Authorization": "Bearer " + self.api_key,
+            "Accept": "application/json",
+            "User-Agent": "korely-memory-python/" + __version__,
+        }
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = _urlrequest.Request(url, data=data, method=method, headers=headers)
+        try:
+            with _urlrequest.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                status = getattr(resp, "status", resp.getcode())
+                return status, (json.loads(raw) if raw else {})
+        except _urlerror.HTTPError as e:
+            raw = e.read()
+            try:
+                parsed = json.loads(raw) if raw else {}
+            except ValueError:
+                parsed = {"message": raw.decode("utf-8", "replace")}
+            if not isinstance(parsed, dict):
+                parsed = {"message": str(parsed)}
+            retry_after = e.headers.get("Retry-After") if e.headers else None
+            parsed.setdefault("_retry_after", retry_after)
+            return e.code, parsed
+        except _urlerror.URLError as e:
+            raise KorelyError("Connection error: " + str(e.reason))
+
+    def _call(self, method: str, path: str, *, params: Optional[dict] = None,
+              json_body: Optional[Any] = None) -> dict:
+        status, body = self._send(method, path, params=params, json_body=json_body)
+        if status >= 400:
+            self._raise(status, body if isinstance(body, dict) else {})
+        return body if isinstance(body, dict) else {}
+
+    @staticmethod
+    def _raise(status: int, body: dict) -> None:
+        code = body.get("code")
+        msg = body.get("message") or code or ("HTTP " + str(status))
+        if status == 401:
+            raise AuthenticationError(msg, status=status, code=code)
+        if status == 403:
+            raise NamespaceForbiddenError(msg, status=status, code=code)
+        if status == 404:
+            raise NotFoundError(msg, status=status, code=code)
+        if status == 409:
+            raise StaleWriteError(msg, status=status, code=code)
+        if status == 429:
+            ra = body.get("_retry_after") or body.get("retry_after")
+            try:
+                ra = int(ra) if ra is not None else None
+            except (ValueError, TypeError):
+                ra = None
+            raise QuotaExceededError(msg, status=status, code=code, retry_after=ra)
+        raise APIError(msg, status=status, code=code)
+
+    # ── memories ───────────────────────────────────────────────────────────
+    def add(self, content: "str | list", *, agent_id: Optional[str] = None,
+            user_id: Optional[str] = None, run_id: Optional[str] = None,
+            metadata: Optional[dict] = None) -> Memory:
+        """POST /v1/memories — store a memory; returns it with extracted facts.
+
+        ``content`` is a string, or a list of chat messages
+        ``[{"role": ..., "content": ...}]`` (Mem0/Supermemory shape), which is
+        joined into one text block before sending."""
+        text = _coerce_content(content)
+        if not text.strip():
+            raise KorelyError("content is empty — pass a non-blank string or messages with content.")
+        body = self._call("POST", "/v1/memories", json_body=_clean({
+            "content": text, "agent_id": agent_id, "user_id": user_id,
+            "run_id": run_id, "metadata": metadata,
+        }))
+        return Memory.from_dict(body)
+
+    def search(self, query: str, *, user_id: Optional[str] = None,
+               agent_id: Optional[str] = None, limit: int = 10) -> List[SearchHit]:
+        """POST /v1/memories/search — hybrid retrieval, ranked by score."""
+        body = self._call("POST", "/v1/memories/search", json_body=_clean({
+            "query": query, "user_id": user_id, "agent_id": agent_id, "limit": limit,
+        }))
+        return [SearchHit.from_dict(h) for h in body.get("results", [])]
+
+    def get_all(self, *, user_id: Optional[str] = None, agent_id: Optional[str] = None,
+                limit: int = 50, offset: int = 0) -> MemoryPage:
+        """GET /v1/memories — list a scope, newest first."""
+        body = self._call("GET", "/v1/memories", params=_clean({
+            "user_id": user_id, "agent_id": agent_id, "limit": limit, "offset": offset,
+        }))
+        return MemoryPage.from_dict(body)
+
+    def get(self, memory_id: str) -> Memory:
+        """GET /v1/memories/:id — full content, metadata, extracted facts."""
+        return Memory.from_dict(self._call("GET", "/v1/memories/" + memory_id))
+
+    def update(self, memory_id: str, *, content: str,
+               expected_updated_at: Optional[str] = None) -> Memory:
+        """PATCH /v1/memories/:id — re-runs extraction. Pass
+        ``expected_updated_at`` for optimistic concurrency (raises
+        StaleWriteError instead of clobbering)."""
+        body = self._call("PATCH", "/v1/memories/" + memory_id, json_body=_clean({
+            "content": content, "expected_updated_at": expected_updated_at,
+        }))
+        return Memory.from_dict(body)
+
+    def delete(self, memory_id: str) -> DeleteReceipt:
+        """DELETE /v1/memories/:id — forget one memory (audited invalidation)."""
+        return DeleteReceipt.from_dict(self._call("DELETE", "/v1/memories/" + memory_id))
+
+    def delete_all(self, *, user_id: str) -> BulkReceipt:
+        """DELETE /v1/users/:user_id/memories — forget every memory + fact for
+        one end user in a single call."""
+        return BulkReceipt.from_dict(
+            self._call("DELETE", "/v1/users/" + user_id + "/memories")
+        )
+
+    def history(self, memory_id: str) -> MemoryHistory:
+        """GET /v1/memories/:id/history — the lifecycle timeline of a memory:
+        created / updated / deleted, plus every typed fact it produced (and the
+        moment each was learned or superseded)."""
+        return MemoryHistory.from_dict(
+            self._call("GET", "/v1/memories/" + memory_id + "/history")
+        )
+
+    def users(self, *, agent_id: Optional[str] = None, limit: int = 50,
+              offset: int = 0) -> UsersPage:
+        """GET /v1/users — the end users you've stored data for (the distinct
+        ``user_id`` namespaces), each with active memory + fact counts and
+        last-active time. The default (null) namespace is omitted. Returns a
+        UsersPage: iterable like a list, with ``.total`` for pagination."""
+        body = self._call("GET", "/v1/users", params=_clean({
+            "agent_id": agent_id, "limit": limit, "offset": offset,
+        }))
+        return UsersPage.from_dict(body)
+
+    # ── facts ────────────────────────────────────────────────────────────────
+    def get_facts(self, *, subject: Optional[str] = None, entity: Optional[str] = None,
+                  predicate: Optional[str] = None, predicate_family: Optional[str] = None,
+                  include_invalidated: bool = False, as_of: Optional[str] = None,
+                  user_id: Optional[str] = None, agent_id: Optional[str] = None,
+                  limit: int = 50, offset: int = 0) -> List[Fact]:
+        """GET /v1/facts — typed (subject, predicate, object) triples with
+        bi-temporal validity. Pass ``as_of`` (ISO date) for a point-in-time
+        query: what was true on that date."""
+        params = _clean({
+            "subject": subject, "entity": entity, "predicate": predicate,
+            "predicate_family": predicate_family, "as_of": as_of,
+            "user_id": user_id, "agent_id": agent_id, "limit": limit, "offset": offset,
+        })
+        if include_invalidated:
+            params["include_invalidated"] = "true"
+        body = self._call("GET", "/v1/facts", params=params)
+        return [Fact.from_dict(f) for f in body.get("facts", [])]
+
+    def add_fact_triple(self, subject: str, predicate: str, object: str, *,
+                        user_id: Optional[str] = None, agent_id: Optional[str] = None,
+                        run_id: Optional[str] = None, subject_type: str = "unknown",
+                        object_is_literal: bool = False, confidence: float = 0.9,
+                        valid_from: Optional[str] = None) -> Fact:
+        """POST /v1/facts — write a typed (subject, predicate, object) triple
+        directly, skipping extraction. The server runs the contradiction check
+        and the fact is bi-temporal: pass ``valid_from`` (ISO date) for a
+        historical fact. Returns the written Fact, with ``invalidated`` listing
+        any fact ids it superseded."""
+        body = self._call("POST", "/v1/facts", json_body=_clean({
+            "subject": subject, "predicate": predicate, "object": object,
+            "user_id": user_id, "agent_id": agent_id, "run_id": run_id,
+            "subject_type": subject_type, "object_is_literal": object_is_literal,
+            "confidence": confidence, "valid_from": valid_from,
+        }))
+        return Fact.from_dict(body)
+
+    def get_profile(self, *, user_id: str, agent_id: Optional[str] = None,
+                    as_of: Optional[str] = None) -> Profile:
+        """GET /v1/profile — the assembled profile of one end user: the active
+        typed facts known about them, the end user's own facts first, grouped by
+        predicate family. ``user_id`` is required. Pass ``as_of`` (ISO date) for
+        the point-in-time profile ("what we knew on 2026-03-01")."""
+        body = self._call("GET", "/v1/profile", params=_clean({
+            "user_id": user_id, "agent_id": agent_id, "as_of": as_of,
+        }))
+        return Profile.from_dict(body)
+
+    # ── context ──────────────────────────────────────────────────────────────
+    def get_context(self, *, query: str, user_id: Optional[str] = None,
+                    agent_id: Optional[str] = None, token_budget: int = 800) -> Context:
+        """GET /v1/context — one call that assembles a prompt-ready context
+        block (profile + relevant facts + memories) within a token budget."""
+        body = self._call("GET", "/v1/context", params=_clean({
+            "query": query, "user_id": user_id, "agent_id": agent_id,
+            "token_budget": token_budget,
+        }))
+        return Context.from_dict(body)
+
+    # ── batch ────────────────────────────────────────────────────────────────
+    def batch(self, memories: List[dict]) -> BatchJob:
+        """POST /v1/batch — bulk import (up to 500 memory objects), async."""
+        body = self._call("POST", "/v1/batch", json_body={"memories": list(memories)})
+        return BatchJob.from_dict(body)
+
+    def batch_status(self, job_id: str) -> BatchJob:
+        """GET /v1/batch/:id — poll an import job."""
+        return BatchJob.from_dict(self._call("GET", "/v1/batch/" + job_id))

korely_memory/exceptions.py

@@ -0,0 +1,45 @@
+"""Typed exceptions mapping 1:1 onto the REST error codes. All subclass
+``KorelyError`` so a caller can catch everything with one except."""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class KorelyError(Exception):
+    """Base for every error the SDK raises."""
+
+    def __init__(self, message: str = "", *, status: Optional[int] = None, code: Optional[str] = None):
+        super().__init__(message or code or "Korely error")
+        self.message = message
+        self.status = status
+        self.code = code
+
+
+class AuthenticationError(KorelyError):
+    """401 — missing, malformed, or revoked API key."""
+
+
+class NamespaceForbiddenError(KorelyError):
+    """403 — the key lacks the scope required for this call."""
+
+
+class NotFoundError(KorelyError):
+    """404 — memory or fact id does not exist, or was forgotten."""
+
+
+class StaleWriteError(KorelyError):
+    """409 — update() with an expected_updated_at older than the record."""
+
+
+class QuotaExceededError(KorelyError):
+    """429 — past the soft cap. Carries ``retry_after`` in seconds when the
+    server sent a Retry-After header."""
+
+    def __init__(self, message: str = "", *, status: Optional[int] = None,
+                 code: Optional[str] = None, retry_after: Optional[int] = None):
+        super().__init__(message, status=status, code=code)
+        self.retry_after = retry_after
+
+
+class APIError(KorelyError):
+    """Any other non-2xx response (validation 422, server 5xx, …)."""

korely_memory/models.py

@@ -0,0 +1,239 @@
+"""Response models. The JSON shapes from the REST API reference are the
+attribute shapes here — each ``from_dict`` keeps documented fields and ignores
+anything new, so a server that returns a superset never breaks an old SDK."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any, List, Optional
+
+
+def _take(cls, d: Optional[dict]) -> dict:
+    """Keep only the keys that are declared fields of ``cls``."""
+    names = {f.name for f in fields(cls)}
+    return {k: v for k, v in (d or {}).items() if k in names}
+
+
+@dataclass
+class Fact:
+    id: Optional[str] = None
+    subject: Optional[str] = None
+    predicate: Optional[str] = None
+    object: Optional[str] = None
+    predicate_family: Optional[str] = None
+    subject_type: Optional[str] = None
+    predicate_raw: Optional[str] = None
+    object_is_literal: Optional[bool] = None
+    confidence: Optional[float] = None
+    user_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    valid_from: Optional[str] = None
+    invalid_at: Optional[str] = None
+    invalidated_by: Optional[str] = None
+    # write-shape only: ids this fact superseded (from add()/update())
+    invalidated: List[str] = field(default_factory=list)
+    source_memory_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Fact":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class Memory:
+    id: Optional[str] = None
+    content: Optional[str] = None
+    user_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    run_id: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    facts: List[Fact] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Memory":
+        d = dict(d or {})
+        facts = [Fact.from_dict(f) for f in (d.get("facts") or [])]
+        obj = cls(**_take(cls, d))
+        obj.facts = facts
+        return obj
+
+
+@dataclass
+class SearchHit:
+    id: Optional[str] = None
+    score: Optional[float] = None
+    snippet: Optional[str] = None
+    user_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SearchHit":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class MemoryPage:
+    """Iterable page of memories with a ``total`` count."""
+    memories: List[Memory] = field(default_factory=list)
+    total: int = 0
+
+    def __iter__(self):
+        return iter(self.memories)
+
+    def __len__(self) -> int:
+        return len(self.memories)
+
+    def __getitem__(self, i):
+        return self.memories[i]
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "MemoryPage":
+        d = d or {}
+        return cls(
+            memories=[Memory.from_dict(m) for m in (d.get("memories") or [])],
+            total=int(d.get("total", 0)),
+        )
+
+
+@dataclass
+class DeleteReceipt:
+    id: Optional[str] = None
+    status: Optional[str] = None
+    facts_invalidated: Optional[int] = None
+    audit_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DeleteReceipt":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class BulkReceipt:
+    user_id: Optional[str] = None
+    memories_forgotten: Optional[int] = None
+    facts_invalidated: Optional[int] = None
+    audit_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BulkReceipt":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class Context:
+    context: str = ""
+    tokens: int = 0
+    sources: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Context":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class BatchJob:
+    id: Optional[str] = None
+    status: Optional[str] = None
+    received: Optional[int] = None
+    imported: Optional[int] = None
+    failed: Optional[int] = None
+    errors: List[Any] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BatchJob":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class Profile:
+    """The assembled profile of one end user: active typed facts known about
+    them, the end user's own facts first, plus a ``by_family`` grouping.
+    ``as_of`` echoes a point-in-time request. ``truncated`` is True when
+    ``total`` exceeds the number of facts returned (the profile is capped at 200)."""
+    user_id: Optional[str] = None
+    as_of: Optional[str] = None
+    facts: List[Fact] = field(default_factory=list)
+    by_family: dict = field(default_factory=dict)
+    total: int = 0
+    truncated: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Profile":
+        d = dict(d or {})
+        facts = [Fact.from_dict(f) for f in (d.get("facts") or [])]
+        by_family = {
+            k: [Fact.from_dict(f) for f in (v or [])]
+            for k, v in (d.get("by_family") or {}).items()
+        }
+        obj = cls(**_take(cls, d))
+        obj.facts = facts
+        obj.by_family = by_family
+        return obj
+
+
+@dataclass
+class HistoryEvent:
+    """One point on a memory's timeline: created | updated | fact_extracted |
+    fact_invalidated | deleted. ``fact`` / ``fact_id`` are set on fact events."""
+    event: Optional[str] = None
+    at: Optional[str] = None
+    fact: Optional[str] = None
+    fact_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "HistoryEvent":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class MemoryHistory:
+    id: Optional[str] = None
+    events: List[HistoryEvent] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "MemoryHistory":
+        d = dict(d or {})
+        events = [HistoryEvent.from_dict(e) for e in (d.get("events") or [])]
+        obj = cls(**_take(cls, d))
+        obj.events = events
+        return obj
+
+
+@dataclass
+class UserScope:
+    """One end user the developer has stored data for, with counts."""
+    user_id: Optional[str] = None
+    memories: int = 0
+    facts: int = 0
+    last_active: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "UserScope":
+        return cls(**_take(cls, d))
+
+
+@dataclass
+class UsersPage:
+    """Iterable page of end users with a ``total`` count (for pagination)."""
+    users: List[UserScope] = field(default_factory=list)
+    total: int = 0
+
+    def __iter__(self):
+        return iter(self.users)
+
+    def __len__(self) -> int:
+        return len(self.users)
+
+    def __getitem__(self, i):
+        return self.users[i]
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "UsersPage":
+        d = d or {}
+        return cls(
+            users=[UserScope.from_dict(u) for u in (d.get("users") or [])],
+            total=int(d.get("total", 0)),
+        )

korely_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: korely-memory
+Version: 0.1.0
+Summary: Python SDK for Korely Agents — memory for AI agents with bi-temporal typed facts.
+Project-URL: Homepage, https://korely.ai/agents
+Project-URL: Documentation, https://korely.ai/agents/docs/surfaces/sdk
+Project-URL: API Reference, https://korely.ai/agents/docs/api-reference
+Author: Korely
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,knowledge-graph,llm,memory,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# korely-memory
+
+The Python SDK for [Korely Agents](https://korely.ai/agents) — memory for AI
+agents, with bi-temporal typed facts and contradiction checking built in.
+
+A typed, **zero-dependency** client over the Korely REST API. Every method maps
+1:1 onto an endpoint, so anything you can do with curl you can do here, and the
+JSON shapes in the [API reference](https://korely.ai/agents/docs/api-reference)
+are the attribute shapes you get back. All the intelligence — embeddings, entity
+and typed-fact extraction, contradiction checking, bi-temporal validity — runs
+server-side, so your install stays small and your process stays light.
+
+## Install
+
+```bash
+pip install korely-memory
+```
+
+Python 3.9 or later.
+
+## Quickstart
+
+```python
+from korely_memory import Korely
+
+korely = Korely(api_key="kor_live_...", region="eu")
+# or read the key from the environment (KORELY_API_KEY)
+korely = Korely(region="eu")
+
+# Remember — the write path extracts facts and resolves contradictions
+korely.add("User prefers TypeScript with strict mode", agent_id="coding-assistant")
+korely.add("Actually I switched to Rust", agent_id="coding-assistant")
+
+# Recall — superseded facts drop out automatically
+for hit in korely.search("user's preferred language", limit=5):
+    print(hit.id, hit.score, hit.snippet)
+
+# One-call, prompt-ready context for your LLM
+ctx = korely.get_context(query="plan the project", user_id="dana", token_budget=800)
+messages = [{"role": "system", "content": f"You are helpful.\n\n{ctx.context}"}]
+```
+
+## Methods
+
+Every method wraps exactly one REST endpoint.
+
+| Method | Endpoint |
+|---|---|
+| `add(content, *, agent_id=, user_id=, run_id=, metadata=)` | `POST /v1/memories` |
+| `search(query, *, user_id=, agent_id=, limit=)` | `POST /v1/memories/search` |
+| `get_all(*, user_id=, agent_id=, limit=, offset=)` | `GET /v1/memories` |
+| `get(memory_id)` | `GET /v1/memories/:id` |
+| `update(memory_id, *, content, expected_updated_at=)` | `PATCH /v1/memories/:id` |
+| `delete(memory_id)` | `DELETE /v1/memories/:id` |
+| `delete_all(*, user_id)` | `DELETE /v1/users/:user_id/memories` |
+| `get_facts(*, subject=, entity=, predicate=, predicate_family=, include_invalidated=, as_of=, …)` | `GET /v1/facts` |
+| `get_context(*, query, user_id=, agent_id=, token_budget=)` | `GET /v1/context` |
+| `batch(memories)` | `POST /v1/batch` |
+| `batch_status(job_id)` | `GET /v1/batch/:id` |
+
+## Bi-temporal facts
+
+The differentiator: typed `(subject, predicate, object)` facts with validity over
+time. Ask what was true on any date.
+
+```python
+# Current state
+facts = korely.get_facts(entity="Northwind Hosting")
+print(facts[0].object)      # 50 euro per month
+print(facts[0].invalid_at)  # None — active
+
+# Point-in-time: what did we believe on June 1?
+facts = korely.get_facts(entity="Northwind Hosting", as_of="2026-06-01")
+print(facts[0].object)      # 40 euro per month
+```
+
+## Scoping
+
+Three identifiers, three levels of scope — the same everywhere (SDK, REST, MCP):
+
+- `agent_id` — your application or agent (one namespace per product surface)
+- `user_id` — your end user (free-form string; **unlimited on every tier**)
+- `run_id` — one session or run (sub-scope inside a user)
+
+```python
+korely.add("Asked to be contacted on Slack", agent_id="support-bot", user_id="customer-4812")
+results = korely.search("contact preference", user_id="customer-4812")
+```
+
+> Always pass `user_id` on reads in multi-tenant products. Filters are additive
+> (AND); a search without `user_id` spans every end user in the namespace.
+
+## Error handling
+
+The SDK raises typed exceptions that map onto the REST error codes; all subclass
+`KorelyError`.
+
+```python
+import time
+from korely_memory import Korely, AuthenticationError, NotFoundError, QuotaExceededError
+
+korely = Korely(api_key="kor_live_...")
+try:
+    memory = korely.get("mem_8f2c1a")
+except AuthenticationError:
+    raise                       # 401 — check or rotate the key
+except NotFoundError:
+    memory = None               # 404 — forgotten or never existed
+except QuotaExceededError as err:
+    time.sleep(err.retry_after) # 429 — back off and retry
+    memory = korely.get("mem_8f2c1a")
+```
+
+| Exception | Status |
+|---|---|
+| `AuthenticationError` | 401 |
+| `NamespaceForbiddenError` | 403 |
+| `NotFoundError` | 404 |
+| `StaleWriteError` | 409 |
+| `QuotaExceededError` (`.retry_after`) | 429 |
+| `APIError` | other |
+
+## Links
+
+- [SDK docs](https://korely.ai/agents/docs/surfaces/sdk)
+- [API reference](https://korely.ai/agents/docs/api-reference)
+- [Cookbook: a chatbot that remembers](https://korely.ai/agents/docs/cookbooks/chatbot-that-remembers)
+
+MIT licensed.

korely_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+korely_memory/__init__.py,sha256=9Z-JDrMxbArveYT7I8jAiRZP90-7c2pZ0ECMGe46YdM,1381
+korely_memory/client.py,sha256=9KLZdqQ8JRPkxDzg0Q2zaVOM00CkvkBh8VD0kOtKXHw,14820
+korely_memory/exceptions.py,sha256=ZGQ6JlHHg_GK4dGIoQ_XgdcG-op1OwCZsor5xaA94kc,1487
+korely_memory/models.py,sha256=2i18KOwxIv_Oa8_JX2jjI7M0CdBGdCQvP-CSZD45bwY,6797
+korely_memory-0.1.0.dist-info/METADATA,sha256=mhTImbj9Ncl0WNP47XZTgROZrhpfWepKTQZj2i6EX2o,5622
+korely_memory-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+korely_memory-0.1.0.dist-info/licenses/LICENSE,sha256=Vnh2NMMPMN9gYAuxdKa2IMnhZAHWfOhDN-Fw2xbr5K0,1063
+korely_memory-0.1.0.dist-info/RECORD,,

korely_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

korely_memory-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Korely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.