sovant 1.3.0__py3-none-any.whl → 1.3.2__py3-none-any.whl

sovant/__init__.py

@@ -1,4 +1,4 @@
 from .client import Sovant, SovantError
 from .models import MemoryCreate, MemoryResult, SearchQuery
 
-__version__ = "1.3.0"
+__version__ = "1.3.2"

sovant/client.py

@@ -193,6 +193,61 @@ class Sovant:
     def memory_delete(self, id: str):
         return self._request("DELETE", f"{self.base_url}/api/v1/memories/{id}")
 
+    def memory_list(
+        self,
+        limit: int | None = None,
+        offset: int | None = None,
+        thread_id: str | None = None,
+        type: str | None = None,
+        tags: list[str] | None = None,
+        is_pinned: bool | None = None,
+        is_archived: bool | None = None,
+        sort_by: str | None = None,
+        sort_order: str | None = None,
+    ):
+        """
+        List memories with filtering and pagination
+
+        Returns memories ordered by sort criteria (default: created_at desc).
+        Use list() to fetch recent memories or filter by criteria.
+        Use memory_search() for semantic/vector-based queries.
+        Use memory_recall() for conversational AI queries.
+
+        Args:
+            limit: Maximum memories to return (default: 20, max: 100)
+            offset: Number of memories to skip for pagination (default: 0)
+            thread_id: Filter by thread ID
+            type: Filter by memory type ('journal', 'insight', 'observation', 'task', 'preference')
+            tags: Filter by tags (memories must have all specified tags)
+            is_pinned: Filter by pinned status
+            is_archived: Filter by archived status
+            sort_by: Sort field ('created_at', 'updated_at', 'importance', 'type')
+            sort_order: Sort direction ('asc' or 'desc')
+
+        Returns:
+            Dict with 'memories', 'total', 'limit', 'offset', 'has_more'
+        """
+        params = {}
+        if limit is not None:
+            params['limit'] = str(limit)
+        if offset is not None:
+            params['offset'] = str(offset)
+        if thread_id:
+            params['thread_id'] = thread_id
+        if type:
+            params['type'] = type
+        if tags:
+            params['tags'] = ','.join(tags)
+        if is_pinned is not None:
+            params['is_pinned'] = str(is_pinned).lower()
+        if is_archived is not None:
+            params['is_archived'] = str(is_archived).lower()
+        if sort_by:
+            params['sort_by'] = sort_by
+        if sort_order:
+            params['sort_order'] = sort_order
+        return self._request("GET", f"{self.base_url}/api/v1/memory", params=params)
+
     def memory_create_batch(self, memories: list[Dict[str, Any]]):
         """
         Batch create multiple memories in a single request

sovant-1.3.2.dist-info/METADATA

@@ -0,0 +1,417 @@
+Metadata-Version: 2.4
+Name: sovant
+Version: 1.3.2
+Summary: Sovant Python SDK — governed AI memory layer for AI agents and applications
+Author: Sovant
+License-Expression: MIT
+Project-URL: Documentation, https://sovant.ai/docs
+Project-URL: Source, https://github.com/hechin91/sovant-ai
+Project-URL: Tracker, https://github.com/hechin91/sovant-ai/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.8.2
+Dynamic: license-file
+
+# Sovant Python SDK
+
+**Sovant is a governed AI memory layer for AI agents and applications.**
+Use it to store, search, and recall memories with profile awareness and enterprise-grade control over how memory is captured and used.
+
+[![PyPI version](https://img.shields.io/pypi/v/sovant.svg)](https://pypi.org/project/sovant/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install sovant
+```
+
+## Quick Start
+
+```python
+import os
+from sovant import Sovant, MemoryCreate, SearchQuery
+
+client = Sovant(api_key=os.environ["SOVANT_API_KEY"])
+
+# Create a memory
+mem = client.memory_create(MemoryCreate(
+    data="User prefers dark mode",
+    type="preference",
+    tags=["ui", "settings"],
+))
+
+# Search memories
+results = client.memory_search(SearchQuery(
+    query="user preferences",
+    limit=10,
+))
+
+# Update a memory
+updated = client.memory_update(mem["id"], {
+    "tags": ["ui", "settings", "theme"],
+})
+
+# Delete a memory
+client.memory_delete(mem["id"])
+```
+
+## Recall vs Search
+
+Sovant provides two ways to query memories:
+
+- **`memory_recall()`** -- Hybrid recall, profile-aware.
+  Use for conversational queries: "What do you know about me?", "What happened on Project X?".
+  Uses Sovant's hybrid pipeline (profile fast-path + thread-scoped lexical + vector semantic search) and prioritizes profile facts (name/age/location) when available.
+
+- **`memory_search()`** -- Semantic search.
+  Use for topic lookup and discovery. Pure vector similarity search without profile logic.
+
+```python
+# Recall for conversational queries (returns { "results": [...], "total": N })
+recall = client.memory_recall(
+    query="what do you know about me?",
+    limit=10,
+)
+for mem in recall.get("results", []):
+    print(mem["content"])
+
+# Search for topic discovery
+topics = client.memory_search(SearchQuery(
+    query="project updates",
+    limit=5,
+))
+```
+
+## Working with Threads
+
+Threads let you organize related memories into conversations or sessions. Each thread has a `title` and can contain multiple memories.
+
+```python
+import os
+from sovant import Sovant, MemoryCreate
+
+client = Sovant(api_key=os.environ["SOVANT_API_KEY"])
+
+# Create a new thread
+thread = client.threads_create(
+    title="Project Alpha Discussion",
+    description="Q1 planning meeting notes",
+    metadata={"project": "alpha", "quarter": "Q1"},
+)
+
+# Store memories in the thread
+mem1 = client.memory_create(MemoryCreate(
+    data="Decided to launch in March",
+    type="journal",
+    thread_id=thread["id"],
+))
+
+mem2 = client.memory_create(MemoryCreate(
+    data="Budget approved: $50k",
+    type="insight",
+    thread_id=thread["id"],
+))
+
+# Recall memories from this specific thread
+thread_recall = client.memory_recall(
+    query="launch date",
+    thread_id=thread["id"],
+    limit=10,
+)
+# thread_recall["results"] contains the matching memories
+
+# Get thread with all its memories
+thread_with_memories = client.threads_get(
+    thread["id"],
+    include_memories=True,
+    limit=50,
+)
+
+# List all threads
+threads = client.threads_list(limit=20, offset=0)
+
+# Update thread
+updated = client.threads_update(
+    thread["id"],
+    title="Project Alpha - Q1 Launch",
+    status="completed",
+)
+
+# Delete thread (keeps memories by default)
+client.threads_delete(thread["id"])
+
+# Delete thread AND all its memories
+client.threads_delete(thread["id"], delete_memories=True)
+```
+
+## Configuration
+
+```python
+from sovant import Sovant
+
+client = Sovant(
+    api_key="sk_live_...",           # Required (or set SOVANT_API_KEY env var)
+    base_url="https://sovant.ai",    # Optional, defaults to https://sovant.ai
+    timeout=30.0,                    # Optional, request timeout in seconds (default: 30.0)
+    max_retries=3,                   # Optional, max retry attempts (default: 3)
+)
+```
+
+The SDK handles authentication via the `Authorization: Bearer` header.
+
+## API Reference
+
+### Memory Operations
+
+#### Create Memory
+
+```python
+from sovant import MemoryCreate
+
+memory = client.memory_create(MemoryCreate(
+    data="Customer contacted support about billing",
+    type="observation",          # 'journal' | 'insight' | 'observation' | 'task' | 'preference'
+    tags=["support", "billing"],
+    metadata={"ticket_id": "12345"},
+    thread_id="thread_abc123",   # Optional thread association
+))
+```
+
+#### Get Memory by ID
+
+```python
+memory = client.memory_get("mem_123abc")
+```
+
+#### Update Memory
+
+```python
+updated = client.memory_update("mem_123abc", {
+    "tags": ["support", "billing", "resolved"],
+})
+```
+
+#### Delete Memory
+
+```python
+client.memory_delete("mem_123abc")
+```
+
+#### Search Memories
+
+```python
+from sovant import SearchQuery
+
+# Semantic search
+results = client.memory_search(SearchQuery(
+    query="customer preferences about notifications",
+    limit=10,
+    type="preference",
+))
+
+# Filter-based search
+results = client.memory_search(SearchQuery(
+    tags=["settings", "notifications"],
+    from_date="2024-01-01",
+    to_date="2024-12-31",
+    limit=20,
+))
+```
+
+#### Recall Memories
+
+Recall returns `{ "results": [...], "total": N, "query_type": "hybrid" }`.
+
+```python
+# Hybrid recall with profile awareness
+recall = client.memory_recall(
+    query="what do you know about me?",
+    limit=10,
+)
+for mem in recall.get("results", []):
+    print(mem["content"], mem.get("relevance"))
+
+# Thread-scoped recall
+recall = client.memory_recall(
+    query="launch timeline",
+    thread_id="thread_abc123",
+    limit=5,
+)
+```
+
+#### Batch Create
+
+```python
+results = client.memory_create_batch([
+    {"data": "First memory", "type": "journal"},
+    {"data": "Second memory", "type": "insight", "tags": ["important"]},
+])
+```
+
+#### List Memories
+
+Fetch memories with filtering and pagination. Use `memory_list()` to retrieve recent memories or filter by criteria — it's more efficient than `memory_search()` when you don't need vector similarity.
+
+```python
+# List recent memories
+result = client.memory_list(limit=20, offset=0)
+for mem in result["memories"]:
+    print(mem["content"])
+
+# Filter by thread
+thread_mems = client.memory_list(thread_id="thread-uuid", limit=50)
+
+# Filter by type and tags
+prefs = client.memory_list(
+    type="preference",
+    tags=["settings"],
+    sort_by="updated_at",
+    sort_order="desc",
+)
+
+# Pinned memories only
+pinned = client.memory_list(is_pinned=True)
+```
+
+**Available parameters:**
+- `limit` — max results (default: 20, max: 100)
+- `offset` — pagination offset
+- `thread_id` — filter by thread
+- `type` — filter by memory type
+- `tags` — filter by tags (must have all)
+- `is_pinned` — filter by pinned status
+- `is_archived` — filter by archived status
+- `sort_by` — `created_at`, `updated_at`, `importance`, or `type`
+- `sort_order` — `asc` or `desc`
+
+### Thread Management
+
+```python
+# Create a thread
+thread = client.threads_create(
+    title="Customer Support Session",
+    metadata={"user_id": "user_123"},
+)
+
+# List threads
+threads = client.threads_list(limit=10, offset=0)
+
+# Get thread by ID (with memories)
+thread = client.threads_get("thread_abc123", include_memories=True)
+
+# Update thread
+updated = client.threads_update(
+    "thread_abc123",
+    title="Resolved: Billing Issue",
+    status="completed",
+)
+
+# Delete thread
+client.threads_delete("thread_abc123")
+```
+
+## Memory Types
+
+- **journal** -- Chronological entries and logs
+- **insight** -- Derived patterns and conclusions
+- **observation** -- Factual, observed information
+- **task** -- Action items and todos
+- **preference** -- User preferences and settings
+
+## Error Handling
+
+The SDK raises `SovantError` for all API errors:
+
+```python
+from sovant import Sovant, SovantError
+
+try:
+    memory = client.memory_get("invalid_id")
+except SovantError as e:
+    print(f"Error: {e}")
+    print(f"Code: {e.code}")      # e.g. "NOT_FOUND", "HTTP_401"
+    print(f"Status: {e.status}")  # e.g. 404, 401
+
+    if e.status == 404:
+        print("Memory not found")
+    elif e.status == 401:
+        print("Invalid API key")
+    elif e.status == 429:
+        print("Rate limited -- SDK retries automatically")
+```
+
+The SDK automatically retries on rate limit (429) and server errors (5xx) with exponential backoff.
+
+## Examples
+
+### Customer Support Integration
+
+```python
+from sovant import MemoryCreate
+
+# Track customer interaction
+interaction = client.memory_create(MemoryCreate(
+    data="Customer reported slow dashboard loading",
+    type="observation",
+    thread_id=f"ticket_{ticket_id}",
+    tags=["support", "performance", "dashboard"],
+    metadata={
+        "ticket_id": ticket_id,
+        "priority": "high",
+    },
+))
+
+# Record resolution
+resolution = client.memory_create(MemoryCreate(
+    data="Resolved by clearing cache and upgrading plan",
+    type="insight",
+    thread_id=f"ticket_{ticket_id}",
+    tags=["support", "resolved"],
+))
+```
+
+### User Preference Tracking
+
+```python
+from sovant import MemoryCreate, SearchQuery
+
+# Store preference
+client.memory_create(MemoryCreate(
+    data="User prefers email notifications over SMS",
+    type="preference",
+    tags=["notifications", "email"],
+))
+
+# Query preferences
+preferences = client.memory_search(SearchQuery(
+    query="notification preferences",
+    type="preference",
+))
+```
+
+## Rate Limiting
+
+The API enforces 60 requests per minute. The SDK automatically retries rate-limited requests with exponential backoff. Rate limit headers are included in responses:
+
+- `X-RateLimit-Limit` -- Request limit per window
+- `X-RateLimit-Remaining` -- Remaining requests
+- `X-RateLimit-Reset` -- Reset timestamp
+
+## Support
+
+- Documentation: [https://sovant.ai/docs](https://sovant.ai/docs)
+- Issues: [GitHub Issues](https://github.com/hechin91/sovant-ai/issues)
+
+## License & Use
+
+- This SDK is MIT-licensed for integration convenience.
+- The Sovant API and platform are proprietary to Sovant Technologies Sdn. Bhd.
+- You may use this SDK to integrate with Sovant's hosted API.
+- Hosting/redistributing the Sovant backend or any proprietary components is not permitted.
+
+## License
+
+MIT -- See [LICENSE](LICENSE) file for details.

{sovant-1.3.0.dist-info → sovant-1.3.2.dist-info}/RECORD

@@ -1,14 +1,14 @@
-sovant/__init__.py,sha256=u5rAQYbVb4cDn8QvmJB-VusRtSXzQsFH6bAJrBMvvNI,122
+sovant/__init__.py,sha256=5cDlN_M0B40LXBtmhQydiExiBAVPvhKUrgPFz11OVgo,122
 sovant/base_client.py,sha256=Vmn6OGywGwLbH5cEeflSjVOFwn5iX_YdfTdUq9pWWxA,8778
-sovant/client.py,sha256=8VnTPSli1QgRky9PqUb9OAKdbMPTfXlGoUkmAYsFfCw,11804
+sovant/client.py,sha256=ObRKZp1Fz97cYYYx50ZHkEji9Uh9qYc3f0Ob1BLT1xk,13975
 sovant/exceptions.py,sha256=MQMSgk7ckXnAbe7hPPpbKOnRBHSPxuCY7WSjqfJAvd0,1557
 sovant/models.py,sha256=avDAITMptDDdDfNH_ed854Q7kF6z_1OzjwJ9Xeft_-8,979
 sovant/types.py,sha256=gnvdXksJt8LObti7nc6eHSBCB7Pz7SNpS5o_HRTq_kA,6098
 sovant/resources/__init__.py,sha256=cPFIM7h8duviDdeHudnVEAmv3F89RHQxdH5BCRWFteQ,193
 sovant/resources/memories.py,sha256=bKKE0uWqFkPa1OEvbK1LrdSD7v6N04RhJ_2VDoPPQBA,11379
 sovant/resources/threads.py,sha256=mN29xP0JODmZBKyfhpeqJyViUWNVMAx3TlYAW-1ruTs,12558
-sovant-1.3.0.dist-info/licenses/LICENSE,sha256=rnNP6-elrMIlQ9jf2aqnHZMyyQ_wvF3y1hTpVUusCWU,1062
-sovant-1.3.0.dist-info/METADATA,sha256=6-_NLCFzejStKM-YRnzYNXBLh9WWoNyO4K6cYvr02W4,14201
-sovant-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sovant-1.3.0.dist-info/top_level.txt,sha256=za6eVEsYd_ZQQs8vrmEWNcAR58r1wCDge_jA60e4CvQ,7
-sovant-1.3.0.dist-info/RECORD,,
+sovant-1.3.2.dist-info/licenses/LICENSE,sha256=rnNP6-elrMIlQ9jf2aqnHZMyyQ_wvF3y1hTpVUusCWU,1062
+sovant-1.3.2.dist-info/METADATA,sha256=JJ4db5M7GK2oDU7F95-uYwN-DcBxxHGPGmJiKsfv7wA,10604
+sovant-1.3.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+sovant-1.3.2.dist-info/top_level.txt,sha256=za6eVEsYd_ZQQs8vrmEWNcAR58r1wCDge_jA60e4CvQ,7
+sovant-1.3.2.dist-info/RECORD,,

{sovant-1.3.0.dist-info → sovant-1.3.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

sovant-1.3.0.dist-info/METADATA

@@ -1,574 +0,0 @@
-Metadata-Version: 2.4
-Name: sovant
-Version: 1.3.0
-Summary: Sovant Memory-as-a-Service Python SDK
-Author: Sovant
-License: MIT
-Project-URL: Documentation, https://sovant.ai/docs
-Project-URL: Source, https://github.com/hechin91/sovant-ai
-Project-URL: Tracker, https://github.com/hechin91/sovant-ai/issues
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: pydantic>=2.8.2
-Dynamic: license-file
-
-# Sovant Python SDK
-
-**Sovant is a governed AI memory layer for AI agents and applications.**
-Use it to store, search, and recall memories with profile awareness and enterprise-grade control over how memory is captured and used.
-
-[![PyPI version](https://img.shields.io/pypi/v/sovant.svg)](https://pypi.org/project/sovant/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Installation
-
-```bash
-pip install sovant
-```
-
-## Quick Start
-
-```python
-from sovant import Sovant
-
-# Initialize the client
-client = Sovant(api_key="sk_live_your_api_key_here", base_url="https://sovant.ai")
-
-# Create a memory
-mem = client.memory.create({
-    "content": "User prefers dark mode",
-    "type": "preference",
-    "tags": ["ui", "settings"]
-})
-
-# Search memories
-results = client.memory.search({
-    "query": "user preferences",
-    "limit": 10
-})
-
-# Update a memory
-updated = client.memory.update(mem["id"], {
-    "tags": ["ui", "settings", "theme"]
-})
-
-# Delete a memory
-client.memory.delete(mem["id"])
-```
-
-## Recall vs Search
-
-Sovant provides two ways to query memories:
-
-- **`memory_recall()`** – Hybrid recall, profile-aware
-  Use for conversational queries: "What do you know about me?", "What happened on Project X?".
-  Uses Sovant's hybrid pipeline (profile fast-path + thread-scoped lexical + vector semantic search) and prioritizes profile facts (name/age/location) when available.
-
-- **`memory_search()`** – Semantic search
-  Use for topic lookup and discovery. Pure vector similarity search without profile logic.
-  Behavior unchanged from previous versions.
-
-```python
-# Recall for conversational queries
-context = client.memory_recall(
-    query="what do you know about me?",
-    limit=10
-)
-
-# Search for topic discovery
-topics = client.memory_search({
-    "query": "project updates",
-    "limit": 5
-})
-```
-
-## Working with Threads
-
-Threads let you organize related memories into conversations or sessions. Each thread has a `title` and can contain multiple memories.
-
-```python
-from sovant import Sovant
-
-client = Sovant(api_key="sk_live_your_api_key_here")
-
-# Create a new thread
-thread = client.threads_create(
-    title="Project Alpha Discussion",
-    description="Q1 planning meeting notes",
-    metadata={"project": "alpha", "quarter": "Q1"}
-)
-
-# Store memories in the thread
-from sovant.models import MemoryCreate
-
-mem1 = client.memory_create(MemoryCreate(
-    data="Decided to launch in March",
-    type="journal",
-    thread_id=thread["id"]
-))
-
-mem2 = client.memory_create(MemoryCreate(
-    data="Budget approved: $50k",
-    type="insight",
-    thread_id=thread["id"]
-))
-
-# Recall memories from this specific thread
-thread_memories = client.memory_recall(
-    query="launch date",
-    thread_id=thread["id"],
-    limit=10
-)
-
-# Get thread with all its memories
-thread_with_memories = client.threads_get(
-    thread["id"],
-    include_memories=True,
-    limit=50
-)
-
-# List all threads
-threads = client.threads_list(limit=20, offset=0)
-
-# Update thread
-updated = client.threads_update(
-    thread["id"],
-    title="Project Alpha - Q1 Launch",
-    status="completed"
-)
-
-# Delete thread (keeps memories by default)
-client.threads_delete(thread["id"])
-
-# Delete thread AND all its memories
-client.threads_delete(thread["id"], delete_memories=True)
-```
-
-## Chat in 60 Seconds
-
-Stream real-time chat responses with memory context:
-
-```python
-from sovant import Sovant
-import sys
-
-client = Sovant(api_key="sk_live_your_api_key_here", base_url="https://sovant.ai")
-
-# Create a chat session
-session = client.chat.create_session({"title": "Demo"})
-
-# Stream a response
-stream = client.chat.send_message(
-    session["id"],
-    "hello",
-    {
-        "provider": "openai",
-        "model": "gpt-4o-mini",
-        "use_memory": True
-    },
-    stream=True
-)
-
-for ev in stream:
-    if ev["type"] == "delta":
-        sys.stdout.write(ev.get("data", ""))
-    elif ev["type"] == "done":
-        print("\n[done]")
-
-# Get chat history
-messages = client.chat.get_messages(session["id"])
-```
-
-## Profile Recall Helpers
-
-Save and recall user profile facts with canonical patterns:
-
-```python
-# Extract profile entity from text
-fact = client.recall.extract_profile("i'm from kuching")
-# -> {"entity": "location", "value": "kuching"} | None
-
-if fact:
-    client.recall.save_profile_fact(fact)  # canonicalizes and persists
-
-# Get all profile facts
-profile = client.recall.get_profile_facts()
-# -> {"name": "...", "age": "...", "location": "...", "preferences": [...]}
-```
-
-## Configuration
-
-```python
-from sovant import Sovant
-
-client = Sovant(
-    api_key="sk_live_your_api_key_here",  # Required
-    base_url="https://sovant.ai",         # Optional, API endpoint
-    timeout=30.0,                          # Optional, request timeout in seconds (default: 30.0)
-    max_retries=3,                         # Optional, max retry attempts (default: 3)
-    debug=False,                           # Optional, enable debug logging (default: False)
-)
-```
-
-The SDK handles dual authentication automatically, preferring the `x-sovant-api-key` header over `Authorization: Bearer`.
-
-## API Reference
-
-### Memory Operations
-
-#### Create Memory
-
-```python
-memory = client.memory.create({
-    "content": "Customer contacted support about billing",
-    "type": "observation",          # 'journal' | 'insight' | 'observation' | 'task' | 'preference'
-    "tags": ["support", "billing"],
-    "metadata": {"ticket_id": "12345"},
-    "thread_id": "thread_abc123",   # Optional thread association
-})
-```
-
-#### List Memories
-
-```python
-memories = client.memory.list({
-    "limit": 20,                    # Max items per page (default: 20)
-    "offset": 0,                    # Pagination offset
-    "tags": ["billing"],            # Filter by tags
-    "type": "observation",          # Filter by type
-    "is_archived": False,           # Filter archived status
-})
-
-print(memories["memories"])         # Array of memories
-print(memories["total"])            # Total count
-print(memories["has_more"])         # More pages available
-```
-
-#### Get Memory by ID
-
-```python
-memory = client.memory.get("mem_123abc")
-```
-
-#### Update Memory (Partial)
-
-```python
-updated = client.memory.update("mem_123abc", {
-    "tags": ["support", "billing", "resolved"],
-    "metadata": {
-        **memory.get("metadata", {}),
-        "resolved": True,
-    },
-    "is_archived": True,
-})
-```
-
-#### Replace Memory (Full)
-
-```python
-replaced = client.memory.put("mem_123abc", {
-    "content": "Updated content here",  # Required for PUT
-    "type": "observation",
-    "tags": ["updated"],
-})
-```
-
-#### Delete Memory
-
-```python
-client.memory.delete("mem_123abc")
-```
-
-#### Search Memories
-
-```python
-# Semantic search
-semantic_results = client.memory.search({
-    "query": "customer preferences about notifications",
-    "limit": 10,
-    "type": "preference",
-})
-
-# Filter-based search
-filter_results = client.memory.search({
-    "tags": ["settings", "notifications"],
-    "from_date": "2024-01-01",
-    "to_date": "2024-12-31",
-    "limit": 20,
-})
-```
-
-#### Batch Operations
-
-```python
-batch = client.memory.batch({
-    "operations": [
-        {
-            "op": "create",
-            "data": {
-                "content": "First memory",
-                "type": "journal",
-            },
-        },
-        {
-            "op": "update",
-            "id": "mem_123abc",
-            "data": {
-                "tags": ["updated"],
-            },
-        },
-        {
-            "op": "delete",
-            "id": "mem_456def",
-        },
-    ],
-})
-
-print(batch["results"])         # Individual operation results
-print(batch["summary"])         # Summary statistics
-```
-
-### Thread Management
-
-Associate memories with conversation threads:
-
-```python
-# Create a thread
-thread = client.threads.create({
-    "title": "Customer Support Session",
-    "metadata": {"user_id": "user_123"}
-})
-
-# List threads
-threads = client.threads.list({
-    "limit": 10,
-    "offset": 0
-})
-
-# Get thread by ID
-thread = client.threads.get("thread_abc123")
-
-# Update thread
-updated_thread = client.threads.update("thread_abc123", {
-    "title": "Resolved: Billing Issue",
-    "metadata": {"status": "resolved"}
-})
-
-# Delete thread
-client.threads.delete("thread_abc123")
-
-# Link memory to thread
-client.threads.link_memory("thread_abc123", "mem_123abc")
-
-# Create memories within a thread
-memory1 = client.memory.create({
-    "content": "User asked about pricing",
-    "type": "observation",
-    "thread_id": "thread_abc123",
-})
-
-memory2 = client.memory.create({
-    "content": "User selected enterprise plan",
-    "type": "observation",
-    "thread_id": "thread_abc123",
-})
-
-# List memories in a thread
-thread_memories = client.memory.list({
-    "thread_id": "thread_abc123",
-})
-```
-
-### API Key Management
-
-Manage API keys programmatically:
-
-```python
-# List all API keys
-keys = client.keys.list()
-print(keys)  # Array of key objects
-
-# Create a new API key
-new_key = client.keys.create({"name": "CI key"})
-print(new_key["key"])  # The actual secret key (only shown once!)
-
-# Update key metadata
-client.keys.update(new_key["id"], {"name": "Production key"})
-
-# Revoke a key
-client.keys.revoke(new_key["id"])
-```
-
-## Memory Types
-
-- **journal** - Chronological entries and logs
-- **insight** - Derived patterns and conclusions
-- **observation** - Factual, observed information
-- **task** - Action items and todos
-- **preference** - User preferences and settings
-
-## Error Handling
-
-The SDK provides typed errors for better error handling:
-
-```python
-from sovant import Sovant, SovantError, AuthError, RateLimitError, NetworkError, TimeoutError
-
-try:
-    memory = client.memory.get("invalid_id")
-except AuthError as e:
-    print(f"Authentication failed: {e}")
-    # Handle authentication error
-except RateLimitError as e:
-    print(f"Rate limit exceeded: {e}")
-    print(f"Retry after: {e.retry_after}")
-    # Handle rate limiting
-except NetworkError as e:
-    print(f"Network error: {e}")
-    # Handle network issues
-except TimeoutError as e:
-    print(f"Request timed out: {e}")
-    # Handle timeout
-except SovantError as e:
-    print(f"API Error: {e}")
-    print(f"Status: {e.status}")
-    print(f"Request ID: {e.request_id}")
-
-    if e.status == 404:
-        # Handle not found
-        pass
-    elif e.status == 400:
-        # Handle bad request
-        pass
-```
-
-## Advanced Features
-
-### Retry Configuration
-
-The SDK automatically retries failed requests with exponential backoff:
-
-```python
-client = Sovant(
-    api_key="sk_live_...",
-    max_retries=5,           # Increase retry attempts
-    timeout=60.0,            # Increase timeout for slow connections
-)
-```
-
-### Debug Mode
-
-Enable debug logging to see detailed request/response information:
-
-```python
-client = Sovant(
-    api_key="sk_live_...",
-    debug=True,              # Enable debug output
-)
-```
-
-### Custom Base URL
-
-Connect to different environments:
-
-```python
-client = Sovant(
-    api_key="sk_live_...",
-    base_url="https://staging.sovant.ai",
-)
-```
-
-## Best Practices
-
-1. **Use appropriate memory types** - Choose the correct type for your use case
-2. **Add meaningful tags** - Tags improve searchability and organization
-3. **Use threads** - Group related memories together
-4. **Handle errors gracefully** - Implement proper error handling
-5. **Batch operations** - Use batch API for multiple operations
-6. **Archive don't delete** - Consider archiving instead of deleting
-
-## Examples
-
-### Customer Support Integration
-
-```python
-# Track customer interaction
-interaction = client.memory.create({
-    "content": "Customer reported slow dashboard loading",
-    "type": "observation",
-    "thread_id": f"ticket_{ticket_id}",
-    "tags": ["support", "performance", "dashboard"],
-    "metadata": {
-        "ticket_id": ticket_id,
-        "customer_id": customer_id,
-        "priority": "high",
-    },
-})
-
-# Record resolution
-resolution = client.memory.create({
-    "content": "Resolved by clearing cache and upgrading plan",
-    "type": "insight",
-    "thread_id": f"ticket_{ticket_id}",
-    "tags": ["support", "resolved"],
-    "metadata": {
-        "ticket_id": ticket_id,
-        "resolution_time": "2h",
-    },
-})
-```
-
-### User Preference Tracking
-
-```python
-# Store preference
-preference = client.memory.create({
-    "content": "User prefers email notifications over SMS",
-    "type": "preference",
-    "tags": ["notifications", "email", "settings"],
-    "metadata": {
-        "user_id": user_id,
-        "setting": "notification_channel",
-        "value": "email",
-    },
-})
-
-# Query preferences
-preferences = client.memory.search({
-    "query": "notification preferences",
-    "type": "preference",
-    "tags": ["notifications"],
-})
-```
-
-## Rate Limiting
-
-The API implements rate limiting. The SDK automatically handles rate limit responses with retries. Rate limit headers are included in responses:
-
-- `X-RateLimit-Limit` - Request limit per window
-- `X-RateLimit-Remaining` - Remaining requests
-- `X-RateLimit-Reset` - Reset timestamp
-
-## Support
-
-- Documentation: [https://sovant.ai/docs](https://sovant.ai/docs)
-- API/Auth docs: [https://sovant.ai/docs/security/auth](https://sovant.ai/docs/security/auth)
-- Issues: [GitHub Issues](https://github.com/sovant-ai/python-sdk/issues)
-- Support: support@sovant.ai
-
-## Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes.
-
-## License & Use
-
-- This SDK is MIT-licensed for integration convenience.
-- The Sovant API and platform are proprietary to Sovant Technologies Sdn. Bhd.
-- You may use this SDK to integrate with Sovant's hosted API.
-- Hosting/redistributing the Sovant backend or any proprietary components is not permitted.
-
-## License
-
-MIT - See [LICENSE](LICENSE) file for details.