remora-ai 0.1.0__tar.gz

remora_ai-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Node dependencies & outputs
+node_modules/
+.npm
+dist/
+
+# Python caches & build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+.pytest_cache/
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# OS / IDE
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Bun / Test logs
+*.log

remora_ai-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: remora-ai
+Version: 0.1.0
+Summary: Official Python SDK for Remora AI Memory Infrastructure
+Author-email: Remora Team <hello@remora.ai>
+License: MIT
+Keywords: agents,ai,crewai,embeddings,langchain,llm,mem0,memory,pgvector,vector-search
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Remora Python SDK (`remora-ai`)
+
+> **Developer-first AI Memory Infrastructure Client** for persistent, evolving agent memory.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install remora-ai
+```
+
+*(Note: The client uses Python standard library `urllib` internally, requiring zero extra dependencies!)*
+
+---
+
+## 🚀 Quickstart
+
+```python
+from remora import RemoraClient
+
+remora = RemoraClient(
+    api_key="rl_live_your_key_here",
+    base_url="http://localhost:3000"  # Defaults to http://localhost:3000
+)
+
+# 1. Ingest a conversation (async extraction with zero chatbot latency)
+remora.ingest(
+    user_id="usr_alice",
+    messages=[
+        {"role": "user", "content": "I am building a SaaS using Python and PostgreSQL."}
+    ]
+)
+
+# 2. Retrieve compact prompt-ready context before replying
+ctx = remora.context(
+    user_id="usr_alice",
+    query="What tech stack should I recommend?"
+)
+
+print(ctx.context_text)
+# Output:
+# Relevant user memories:
+# - User is building a SaaS using Python and PostgreSQL.
+# Use these memories only when relevant.
+
+# 3. Direct memory search with hybrid ranking scores
+memories = remora.search(
+    user_id="usr_alice",
+    query="programming language and database"
+)
+
+for m in memories:
+    print(f"- {m.content} (Score: {m.final_score})")
+    print(f"  Similarity: {m.score_breakdown.semantic_similarity}")
+```
+
+---
+
+## 🤖 Integration with OpenAI / LangChain
+
+```python
+from openai import OpenAI
+from remora import RemoraClient
+
+remora = RemoraClient(api_key="rl_live_...")
+openai = OpenAI()
+
+user_id = "usr_alice"
+user_message = "What database should I choose?"
+
+# 1. Fetch relevant persistent memories
+ctx = remora.context(user_id=user_id, query=user_message)
+
+# 2. Inject context into system prompt
+system_prompt = f"You are a helpful coding copilot.\n\n{ctx.context_text}"
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_message}
+    ]
+)
+
+print(response.choices[0].message.content)
+
+# 3. Asynchronously ingest the turn for future memory formation
+remora.ingest(
+    user_id=user_id,
+    messages=[
+        {"role": "user", "content": user_message},
+        {"role": "assistant", "content": response.choices[0].message.content}
+    ]
+)
+```
+
+---
+
+## 📚 API Reference
+
+- `remora.add(user_id, content, namespace="default", type="FACT", importance=0.5)`
+- `remora.search(user_id, query, limit=5)`
+- `remora.context(user_id, query, limit=5)`
+- `remora.ingest(user_id, messages, sync=False)`
+- `remora.get(memory_id)`
+- `remora.update(memory_id, content="...")`
+- `remora.delete(memory_id)`
+- `remora.delete_user_memories(user_id)`: GDPR / Privacy wipe
+- `remora.export_user_memories(user_id)`: Data portability export

remora_ai-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Remora Python SDK (`remora-ai`)
+
+> **Developer-first AI Memory Infrastructure Client** for persistent, evolving agent memory.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install remora-ai
+```
+
+*(Note: The client uses Python standard library `urllib` internally, requiring zero extra dependencies!)*
+
+---
+
+## 🚀 Quickstart
+
+```python
+from remora import RemoraClient
+
+remora = RemoraClient(
+    api_key="rl_live_your_key_here",
+    base_url="http://localhost:3000"  # Defaults to http://localhost:3000
+)
+
+# 1. Ingest a conversation (async extraction with zero chatbot latency)
+remora.ingest(
+    user_id="usr_alice",
+    messages=[
+        {"role": "user", "content": "I am building a SaaS using Python and PostgreSQL."}
+    ]
+)
+
+# 2. Retrieve compact prompt-ready context before replying
+ctx = remora.context(
+    user_id="usr_alice",
+    query="What tech stack should I recommend?"
+)
+
+print(ctx.context_text)
+# Output:
+# Relevant user memories:
+# - User is building a SaaS using Python and PostgreSQL.
+# Use these memories only when relevant.
+
+# 3. Direct memory search with hybrid ranking scores
+memories = remora.search(
+    user_id="usr_alice",
+    query="programming language and database"
+)
+
+for m in memories:
+    print(f"- {m.content} (Score: {m.final_score})")
+    print(f"  Similarity: {m.score_breakdown.semantic_similarity}")
+```
+
+---
+
+## 🤖 Integration with OpenAI / LangChain
+
+```python
+from openai import OpenAI
+from remora import RemoraClient
+
+remora = RemoraClient(api_key="rl_live_...")
+openai = OpenAI()
+
+user_id = "usr_alice"
+user_message = "What database should I choose?"
+
+# 1. Fetch relevant persistent memories
+ctx = remora.context(user_id=user_id, query=user_message)
+
+# 2. Inject context into system prompt
+system_prompt = f"You are a helpful coding copilot.\n\n{ctx.context_text}"
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_message}
+    ]
+)
+
+print(response.choices[0].message.content)
+
+# 3. Asynchronously ingest the turn for future memory formation
+remora.ingest(
+    user_id=user_id,
+    messages=[
+        {"role": "user", "content": user_message},
+        {"role": "assistant", "content": response.choices[0].message.content}
+    ]
+)
+```
+
+---
+
+## 📚 API Reference
+
+- `remora.add(user_id, content, namespace="default", type="FACT", importance=0.5)`
+- `remora.search(user_id, query, limit=5)`
+- `remora.context(user_id, query, limit=5)`
+- `remora.ingest(user_id, messages, sync=False)`
+- `remora.get(memory_id)`
+- `remora.update(memory_id, content="...")`
+- `remora.delete(memory_id)`
+- `remora.delete_user_memories(user_id)`: GDPR / Privacy wipe
+- `remora.export_user_memories(user_id)`: Data portability export

remora_ai-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remora-ai"
+version = "0.1.0"
+description = "Official Python SDK for Remora AI Memory Infrastructure"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Remora Team", email = "hello@remora.ai" }
+]
+keywords = [
+    "ai",
+    "memory",
+    "agents",
+    "llm",
+    "mem0",
+    "langchain",
+    "crewai",
+    "embeddings",
+    "vector-search",
+    "pgvector"
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["remora"]

remora_ai-0.1.0/remora/__init__.py

@@ -0,0 +1,38 @@
+"""
+Remora Python SDK
+~~~~~~~~~~~~~~~~~
+Official Python client library for Remora AI Memory Infrastructure.
+"""
+
+from .client import RemoraClient
+from .models import (
+    Memory,
+    RankedMemory,
+    ContextResult,
+    IngestResult,
+    ScoreBreakdown,
+    MemoryType,
+    MemoryStatus
+)
+from .exceptions import (
+    RemoraError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "RemoraClient",
+    "Memory",
+    "RankedMemory",
+    "ContextResult",
+    "IngestResult",
+    "ScoreBreakdown",
+    "MemoryType",
+    "MemoryStatus",
+    "RemoraError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError"
+]

remora_ai-0.1.0/remora/client.py

@@ -0,0 +1,214 @@
+import json
+import urllib.request
+import urllib.error
+from typing import Optional, List, Dict, Any, Union
+
+from .models import Memory, RankedMemory, ContextResult, IngestResult, MemoryType, MemoryStatus
+from .exceptions import RemoraError, AuthenticationError, NotFoundError, RateLimitError
+
+class RemoraClient:
+    """
+    Synchronous Python Client for Remora AI Memory Infrastructure.
+    Zero external dependencies required (uses standard library urllib).
+    """
+
+    def __init__(self, api_key: str, base_url: str = "http://localhost:3000", timeout: float = 30.0):
+        if not api_key:
+            raise AuthenticationError("RemoraClient: api_key is required.")
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, method: str, path: str, payload: Optional[Dict[str, Any]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": "remora-python-sdk/0.1.0"
+        }
+
+        data_bytes = None
+        if payload is not None:
+            data_bytes = json.dumps(payload).encode("utf-8")
+
+        req = urllib.request.Request(url, data=data_bytes, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                status_code = response.getcode()
+                body = response.read().decode("utf-8")
+                parsed = json.loads(body) if body else {}
+                return parsed.get("data", {})
+        except urllib.error.HTTPError as e:
+            raw_body = e.read().decode("utf-8") if e.fp else ""
+            error_json = {}
+            try:
+                error_json = json.loads(raw_body)
+            except Exception:
+                pass
+
+            message = error_json.get("message", f"HTTP Error {e.code}: {e.reason}")
+
+            if e.code == 401:
+                raise AuthenticationError(message, raw_response=error_json)
+            elif e.code == 404:
+                raise NotFoundError(message, raw_response=error_json)
+            elif e.code == 429:
+                retry_after = e.headers.get("Retry-After")
+                retry_sec = int(retry_after) if retry_after and retry_after.isdigit() else None
+                raise RateLimitError(message, retry_after=retry_sec, raw_response=error_json)
+            else:
+                raise RemoraError(message, status_code=e.code, raw_response=error_json)
+        except urllib.error.URLError as e:
+            raise RemoraError(f"Connection error to Remora at {url}: {e.reason}")
+
+    def add(
+        self,
+        user_id: str,
+        content: str,
+        namespace: str = "default",
+        type: MemoryType = "FACT",
+        importance: float = 0.5,
+        confidence: float = 1.0,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Memory:
+        """Store a durable memory for an end-user."""
+        payload = {
+            "user_id": user_id,
+            "content": content,
+            "namespace": namespace,
+            "type": type,
+            "importance": importance,
+            "confidence": confidence,
+            "metadata": metadata or {}
+        }
+        res = self._request("POST", "/v1/memories", payload)
+        return Memory.from_dict(res)
+
+    def search(
+        self,
+        user_id: str,
+        query: str,
+        namespace: Optional[str] = None,
+        limit: int = 5
+    ) -> List[RankedMemory]:
+        """Search memories with semantic vector similarity and hybrid ranking."""
+        payload: Dict[str, Any] = {
+            "user_id": user_id,
+            "query": query,
+            "limit": limit
+        }
+        if namespace:
+            payload["namespace"] = namespace
+
+        res = self._request("POST", "/v1/memories/search", payload)
+        if isinstance(res, list):
+            return [RankedMemory.from_dict(m) for m in res]
+        return []
+
+    def context(
+        self,
+        user_id: str,
+        query: str,
+        namespace: Optional[str] = None,
+        limit: int = 5
+    ) -> ContextResult:
+        """Retrieve prompt-ready formatted context text to inject directly into an LLM."""
+        payload: Dict[str, Any] = {
+            "user_id": user_id,
+            "query": query,
+            "limit": limit
+        }
+        if namespace:
+            payload["namespace"] = namespace
+
+        res = self._request("POST", "/v1/memories/context", payload)
+        return ContextResult.from_dict(res)
+
+    def ingest(
+        self,
+        user_id: str,
+        messages: List[Dict[str, str]],
+        namespace: str = "default",
+        sync: bool = False
+    ) -> IngestResult:
+        """
+        Extract memories automatically from raw conversation turns.
+        Defaults to sync=False (returns 202 Accepted + jobId with zero chatbot latency).
+        """
+        payload = {
+            "user_id": user_id,
+            "messages": messages,
+            "namespace": namespace,
+            "sync": sync
+        }
+        res = self._request("POST", "/v1/memories/ingest", payload)
+        return IngestResult.from_dict(res)
+
+    def get(self, memory_id: str) -> Memory:
+        """Get single memory by ID along with its evolution versions."""
+        res = self._request("GET", f"/v1/memories/{memory_id}")
+        return Memory.from_dict(res)
+
+    def update(
+        self,
+        memory_id: str,
+        content: Optional[str] = None,
+        importance: Optional[float] = None,
+        confidence: Optional[float] = None,
+        type: Optional[MemoryType] = None,
+        status: Optional[MemoryStatus] = None
+    ) -> Memory:
+        """Update a memory (automatically logs a MemoryVersion audit entry)."""
+        payload: Dict[str, Any] = {}
+        if content is not None:
+            payload["content"] = content
+        if importance is not None:
+            payload["importance"] = importance
+        if confidence is not None:
+            payload["confidence"] = confidence
+        if type is not None:
+            payload["type"] = type
+        if status is not None:
+            payload["status"] = status
+
+        res = self._request("PATCH", f"/v1/memories/{memory_id}", payload)
+        return Memory.from_dict(res)
+
+    def delete(self, memory_id: str) -> Memory:
+        """Soft-delete a memory."""
+        res = self._request("DELETE", f"/v1/memories/{memory_id}")
+        return Memory.from_dict(res)
+
+    def delete_user_memories(self, user_id: str) -> Dict[str, Any]:
+        """GDPR / Privacy: Delete all memories for an external user."""
+        return self._request("DELETE", f"/v1/memories/users/{user_id}")
+
+    def export_user_memories(self, user_id: str) -> Dict[str, Any]:
+        """Data Portability: Export all memories and version history for a user."""
+        return self._request("GET", f"/v1/memories/users/{user_id}/export")
+
+    def list(
+        self,
+        user_id: Optional[str] = None,
+        namespace: Optional[str] = None,
+        limit: int = 20,
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """List memories with optional pagination and filters."""
+        params = []
+        if user_id:
+            params.append(f"user_id={user_id}")
+        if namespace:
+            params.append(f"namespace={namespace}")
+        params.append(f"limit={limit}")
+        params.append(f"offset={offset}")
+
+        query = f"?{'&'.join(params)}" if params else ""
+        res = self._request("GET", f"/v1/memories{query}")
+        result = res if isinstance(res, dict) else {}
+        memories = [Memory.from_dict(m) for m in result.get("memories", [])]
+        return {
+            "total": result.get("total", 0),
+            "memories": memories
+        }

remora_ai-0.1.0/remora/exceptions.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+class RemoraError(Exception):
+    """Base exception for all Remora errors."""
+    def __init__(self, message: str, status_code: int = 500, raw_response: Optional[dict] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.raw_response = raw_response or {}
+
+class AuthenticationError(RemoraError):
+    """Raised when the API key is missing, invalid, expired, or revoked."""
+    def __init__(self, message: str = "Unauthorized: Invalid or missing API key.", raw_response: Optional[dict] = None):
+        super().__init__(message, status_code=401, raw_response=raw_response)
+
+class NotFoundError(RemoraError):
+    """Raised when a requested resource (e.g. memory ID) does not exist."""
+    def __init__(self, message: str = "Resource not found.", raw_response: Optional[dict] = None):
+        super().__init__(message, status_code=404, raw_response=raw_response)
+
+class RateLimitError(RemoraError):
+    """Raised when the API key exceeds its sliding window rate limit."""
+    def __init__(self, message: str = "Rate limit exceeded.", retry_after: Optional[int] = None, raw_response: Optional[dict] = None):
+        super().__init__(message, status_code=429, raw_response=raw_response)
+        self.retry_after = retry_after

remora_ai-0.1.0/remora/models.py

@@ -0,0 +1,142 @@
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict, Any, Literal
+
+MemoryType = Literal[
+    "FACT",
+    "PREFERENCE",
+    "GOAL",
+    "INSTRUCTION",
+    "DECISION",
+    "PROFILE",
+    "RELATIONSHIP",
+    "PROJECT_CONTEXT",
+    "BEHAVIOR",
+    "TEMPORARY",
+    "OTHER"
+]
+
+MemoryStatus = Literal[
+    "ACTIVE",
+    "SUPERSEDED",
+    "ARCHIVED",
+    "DELETED",
+    "EXPIRED"
+]
+
+@dataclass
+class ScoreBreakdown:
+    semantic_similarity: float
+    importance: float
+    confidence: float
+    recency: float
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ScoreBreakdown":
+        return cls(
+            semantic_similarity=data.get("semanticSimilarity", 0.0),
+            importance=data.get("importance", 0.0),
+            confidence=data.get("confidence", 0.0),
+            recency=data.get("recency", 0.0),
+        )
+
+@dataclass
+class Memory:
+    id: str
+    organization_id: str
+    project_id: str
+    external_user_id: str
+    namespace: str
+    content: str
+    type: str
+    status: str
+    importance: float
+    confidence: float
+    created_at: str
+    updated_at: str
+    last_accessed_at: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+    versions: Optional[List[Dict[str, Any]]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Memory":
+        return cls(
+            id=data.get("id", ""),
+            organization_id=data.get("organizationId", ""),
+            project_id=data.get("projectId", ""),
+            external_user_id=data.get("externalUserId", ""),
+            namespace=data.get("namespace", "default"),
+            content=data.get("content", ""),
+            type=data.get("type", "FACT"),
+            status=data.get("status", "ACTIVE"),
+            importance=float(data.get("importance", 0.5)),
+            confidence=float(data.get("confidence", 1.0)),
+            last_accessed_at=data.get("lastAccessedAt"),
+            created_at=data.get("createdAt", ""),
+            updated_at=data.get("updatedAt", ""),
+            metadata=data.get("metadata"),
+            versions=data.get("versions"),
+        )
+
+@dataclass
+class RankedMemory(Memory):
+    final_score: float = 0.0
+    score_breakdown: Optional[ScoreBreakdown] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "RankedMemory":
+        base = super().from_dict(data)
+        breakdown = None
+        if "scoreBreakdown" in data and isinstance(data["scoreBreakdown"], dict):
+            breakdown = ScoreBreakdown.from_dict(data["scoreBreakdown"])
+
+        return cls(
+            id=base.id,
+            organization_id=base.organization_id,
+            project_id=base.project_id,
+            external_user_id=base.external_user_id,
+            namespace=base.namespace,
+            content=base.content,
+            type=base.type,
+            status=base.status,
+            importance=base.importance,
+            confidence=base.confidence,
+            last_accessed_at=base.last_accessed_at,
+            created_at=base.created_at,
+            updated_at=base.updated_at,
+            metadata=base.metadata,
+            versions=base.versions,
+            final_score=float(data.get("finalScore", 0.0)),
+            score_breakdown=breakdown
+        )
+
+@dataclass
+class ContextResult:
+    context_text: str
+    memories: List[RankedMemory] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ContextResult":
+        memories_raw = data.get("memories", [])
+        memories = [RankedMemory.from_dict(m) for m in memories_raw]
+        return cls(
+            context_text=data.get("contextText", ""),
+            memories=memories
+        )
+
+@dataclass
+class IngestResult:
+    ingested: Optional[int] = None
+    job_id: Optional[str] = None
+    status: Optional[str] = None
+    memories: List[Memory] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "IngestResult":
+        memories_raw = data.get("memories", [])
+        memories = [Memory.from_dict(m) for m in memories_raw]
+        return cls(
+            ingested=data.get("ingested"),
+            job_id=data.get("jobId"),
+            status=data.get("status"),
+            memories=memories
+        )

remora_ai-0.1.0/tests/test_sdk.py

@@ -0,0 +1,78 @@
+import unittest
+from remora.models import Memory, RankedMemory, ContextResult, ScoreBreakdown
+from remora.client import RemoraClient
+from remora.exceptions import AuthenticationError
+
+class TestRemoraSDK(unittest.TestCase):
+    def test_client_init_requires_key(self):
+        with self.assertRaises(AuthenticationError):
+            RemoraClient(api_key="")
+
+    def test_memory_model_deserialization(self):
+        raw = {
+            "id": "mem_123",
+            "organizationId": "org_abc",
+            "projectId": "proj_xyz",
+            "externalUserId": "usr_alice",
+            "namespace": "personal",
+            "content": "User prefers dark mode.",
+            "type": "PREFERENCE",
+            "status": "ACTIVE",
+            "importance": 0.8,
+            "confidence": 0.95,
+            "createdAt": "2026-10-20T12:00:00Z",
+            "updatedAt": "2026-10-20T12:00:00Z"
+        }
+
+        memory = Memory.from_dict(raw)
+        self.assertEqual(memory.id, "mem_123")
+        self.assertEqual(memory.content, "User prefers dark mode.")
+        self.assertEqual(memory.importance, 0.8)
+        self.assertEqual(memory.confidence, 0.95)
+
+    def test_ranked_memory_deserialization(self):
+        raw = {
+            "id": "mem_123",
+            "organizationId": "org_abc",
+            "projectId": "proj_xyz",
+            "externalUserId": "usr_alice",
+            "namespace": "default",
+            "content": "User prefers Python.",
+            "type": "PREFERENCE",
+            "status": "ACTIVE",
+            "importance": 0.8,
+            "confidence": 0.9,
+            "finalScore": 0.895,
+            "scoreBreakdown": {
+                "semanticSimilarity": 0.92,
+                "importance": 0.8,
+                "confidence": 0.9,
+                "recency": 0.95
+            },
+            "createdAt": "2026-10-20T12:00:00Z",
+            "updatedAt": "2026-10-20T12:00:00Z"
+        }
+
+        ranked = RankedMemory.from_dict(raw)
+        self.assertEqual(ranked.final_score, 0.895)
+        self.assertIsNotNone(ranked.score_breakdown)
+        self.assertEqual(ranked.score_breakdown.semantic_similarity, 0.92)
+
+    def test_context_result_deserialization(self):
+        raw = {
+            "contextText": "Relevant user memories:\n- User likes Python.",
+            "memories": [
+                {
+                    "id": "mem_1",
+                    "content": "User likes Python.",
+                    "finalScore": 0.9
+                }
+            ]
+        }
+
+        ctx = ContextResult.from_dict(raw)
+        self.assertIn("Relevant user memories:", ctx.context_text)
+        self.assertEqual(len(ctx.memories), 1)
+
+if __name__ == "__main__":
+    unittest.main()