cuemap 0.7.2__tar.gz → 0.7.3__tar.gz

{cuemap-0.7.2/cuemap.egg-info → cuemap-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuemap
-Version: 0.7.2
+Version: 0.7.3
 Summary: CueMap Python SDK - High-performance temporal-associative memory
 Author-email: Kaan Demirel <hello@cuemap.dev>
 License: MIT
@@ -33,13 +33,26 @@ Requires-Dist: build>=1.0.0; extra == "dev"
 Requires-Dist: twine>=4.0.0; extra == "dev"
 Dynamic: license-file
 
-# CueMap Python SDK
+<p align="center">
+  <img src="https://cuemap.dev/cuemap-logo.PNG" alt="CueMap" width="120">
+</p>
+
+<h1 align="center">CueMap Python SDK</h1>
+
+<p align="center">A polished Python client for fast, accurate, and explainable agent memory.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/cuemap/"><img src="https://img.shields.io/pypi/v/cuemap?logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/cuemap/"><img src="https://img.shields.io/pypi/pyversions/cuemap?logo=python&logoColor=white" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5e5ce6" alt="License"></a>
+  <a href="https://github.com/cuemap-dev/cuemap"><img src="https://img.shields.io/badge/engine-v0.7.3-0f766e" alt="Engine compatibility"></a>
+</p>
 
 **High-performance temporal-associative memory store** designed for dynamic contextual retrieval.
 
 ## Overview
 
-CueMap implements a **Continuous Gradient Algorithm** optimized for associative data structures:
+CueMap uses **temporal-associative retrieval**: lexical and structural candidate generation, with optional semantic reranking. Its main components are:
 
 1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
 2.  **Local semantic reranking**: Uses bundled qint8 MiniLM-L3 by default, or q4 MiniLM-L3 with the edge profile, for bounded semantic ranking inside the engine.
@@ -47,9 +60,9 @@ CueMap implements a **Continuous Gradient Algorithm** optimized for associative
 4.  **Reinforcement (Access-based Learning)**: Frequently accessed memories gain signal strength, remaining highly accessible even as they age.
 5.  **Deterministic Facets & Intent Routing**: Extracts synchronous source, evidence, temporal, type, and entity facets, then uses sparse intent cues and reranking during recall.
 
-As of v0.7.2, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `all-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
+As of v0.7.3, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `paraphrase-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
 
-v0.7.2 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
+v0.7.3 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
 
 Use this SDK to talk to the Rust engine from Python applications.
 
@@ -64,7 +77,7 @@ pip install cuemap
 ### 1. Start the Engine
 
 ```bash
-docker run -p 8080:8080 cuemap/engine:latest
+docker run -p 8735:8735 cuemap/engine:latest
 ```
 
 ### 2. Basic Usage
@@ -134,9 +147,29 @@ print(response["proof"])
 # Cryptographic proof of context retrieval
 ```
 
-### v0.7.2 Recall Controls
+### Project memory lifecycle
 
-CueMap v0.7.2 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
+The engine can unload inactive project contexts while keeping their snapshots
+on disk. Normal project operations demand-load a project when needed, so the
+first request after an unload may take longer. Use the explicit helpers when
+you want to control residency:
+
+```python
+client.unload_project("older-repository")
+client.load_project("older-repository")
+client.save_project("older-repository")  # persist without unloading
+
+for project in client.list_projects():
+    print(project["project_id"], project["loaded"])
+```
+
+Portable projects use the same four operations as the CLI:
+`pack_project()`, `load_project_package()`, `push_project()`, and `pull_project()`.
+Use `sync_project(project_id, "s3://bucket/team")` for conflict-safe fast-forward sync.
+
+### v0.7.3 Recall Controls
+
+CueMap v0.7.3 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
 
 ```python
 results = client.recall(
@@ -250,3 +283,15 @@ async with AsyncCueMap() as client:
 ## License
 
 MIT
+
+### Recall previews
+
+The engine's `POST /recall` accepts `response_mode: "preview"` and optional
+`preview_chars` (100–2000 UTF-16 code units, default 200). Full content remains
+the default. Previews replace each hit's `content` with a leading `preview`,
+`content_truncated`, and `content_length`, preserving metadata and ranking.
+Use previews for broad discovery, then fetch a selected memory with
+`GET /memories/{id}?decoded=true` or read its source. Metadata and diagnostics
+are not capped. TypeScript request objects and Python sync/async `recall`
+accept these same options; Python returns `RecallPreviewResult` for ungrouped
+preview results. The updated engine is required.

{cuemap-0.7.2 → cuemap-0.7.3}/README.md

@@ -1,10 +1,23 @@
-# CueMap Python SDK
+<p align="center">
+  <img src="https://cuemap.dev/cuemap-logo.PNG" alt="CueMap" width="120">
+</p>
+
+<h1 align="center">CueMap Python SDK</h1>
+
+<p align="center">A polished Python client for fast, accurate, and explainable agent memory.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/cuemap/"><img src="https://img.shields.io/pypi/v/cuemap?logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/cuemap/"><img src="https://img.shields.io/pypi/pyversions/cuemap?logo=python&logoColor=white" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5e5ce6" alt="License"></a>
+  <a href="https://github.com/cuemap-dev/cuemap"><img src="https://img.shields.io/badge/engine-v0.7.3-0f766e" alt="Engine compatibility"></a>
+</p>
 
 **High-performance temporal-associative memory store** designed for dynamic contextual retrieval.
 
 ## Overview
 
-CueMap implements a **Continuous Gradient Algorithm** optimized for associative data structures:
+CueMap uses **temporal-associative retrieval**: lexical and structural candidate generation, with optional semantic reranking. Its main components are:
 
 1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
 2.  **Local semantic reranking**: Uses bundled qint8 MiniLM-L3 by default, or q4 MiniLM-L3 with the edge profile, for bounded semantic ranking inside the engine.
@@ -12,9 +25,9 @@ CueMap implements a **Continuous Gradient Algorithm** optimized for associative
 4.  **Reinforcement (Access-based Learning)**: Frequently accessed memories gain signal strength, remaining highly accessible even as they age.
 5.  **Deterministic Facets & Intent Routing**: Extracts synchronous source, evidence, temporal, type, and entity facets, then uses sparse intent cues and reranking during recall.
 
-As of v0.7.2, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `all-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
+As of v0.7.3, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `paraphrase-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
 
-v0.7.2 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
+v0.7.3 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
 
 Use this SDK to talk to the Rust engine from Python applications.
 
@@ -29,7 +42,7 @@ pip install cuemap
 ### 1. Start the Engine
 
 ```bash
-docker run -p 8080:8080 cuemap/engine:latest
+docker run -p 8735:8735 cuemap/engine:latest
 ```
 
 ### 2. Basic Usage
@@ -99,9 +112,29 @@ print(response["proof"])
 # Cryptographic proof of context retrieval
 ```
 
-### v0.7.2 Recall Controls
+### Project memory lifecycle
 
-CueMap v0.7.2 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
+The engine can unload inactive project contexts while keeping their snapshots
+on disk. Normal project operations demand-load a project when needed, so the
+first request after an unload may take longer. Use the explicit helpers when
+you want to control residency:
+
+```python
+client.unload_project("older-repository")
+client.load_project("older-repository")
+client.save_project("older-repository")  # persist without unloading
+
+for project in client.list_projects():
+    print(project["project_id"], project["loaded"])
+```
+
+Portable projects use the same four operations as the CLI:
+`pack_project()`, `load_project_package()`, `push_project()`, and `pull_project()`.
+Use `sync_project(project_id, "s3://bucket/team")` for conflict-safe fast-forward sync.
+
+### v0.7.3 Recall Controls
+
+CueMap v0.7.3 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
 
 ```python
 results = client.recall(
@@ -215,3 +248,15 @@ async with AsyncCueMap() as client:
 ## License
 
 MIT
+
+### Recall previews
+
+The engine's `POST /recall` accepts `response_mode: "preview"` and optional
+`preview_chars` (100–2000 UTF-16 code units, default 200). Full content remains
+the default. Previews replace each hit's `content` with a leading `preview`,
+`content_truncated`, and `content_length`, preserving metadata and ranking.
+Use previews for broad discovery, then fetch a selected memory with
+`GET /memories/{id}?decoded=true` or read its source. Metadata and diagnostics
+are not capped. TypeScript request objects and Python sync/async `recall`
+accept these same options; Python returns `RecallPreviewResult` for ungrouped
+preview results. The updated engine is required.

{cuemap-0.7.2 → cuemap-0.7.3}/cuemap/__init__.py

@@ -19,11 +19,11 @@ Example:
 
 from .client import CueMap, AsyncCueMap
 from .embedded import EmbeddedCueMap, resolve_cuemap_binary
-from .models import Memory, RecallResult
+from .models import Memory, RecallResult, RecallPreviewResult
 from .exceptions import CueMapError, ConnectionError, AuthenticationError
 from .grounding import CueMapGroundingRetriever, AsyncCueMapGroundingRetriever
 
-__version__ = "0.7.2"
+__version__ = "0.7.3"
 __all__ = [
     "CueMap",
     "AsyncCueMap",
@@ -31,6 +31,7 @@ __all__ = [
     "resolve_cuemap_binary",
     "Memory",
     "RecallResult",
+    "RecallPreviewResult",
     "CueMapError",
     "ConnectionError",
     "AuthenticationError",

{cuemap-0.7.2 → cuemap-0.7.3}/cuemap/client.py

@@ -3,7 +3,7 @@
 import httpx
 from typing import List, Optional, Dict, Any
 
-from .models import Memory, RecallResult
+from .models import Memory, RecallResult, RecallPreviewResult
 from .exceptions import CueMapError, ConnectionError, AuthenticationError
 
 
@@ -27,7 +27,7 @@ class CueMap:
     
     def __init__(
         self,
-        url: str = "http://localhost:8080",
+        url: str = "http://localhost:8735",
         api_key: Optional[str] = None,
         project_id: Optional[str] = None,
         timeout: float = 30.0
@@ -185,6 +185,8 @@ class CueMap:
         disable_systems_consolidation: Optional[bool] = None,
         semantic_mode: str = "hybrid",
         query_embedding: Optional[List[float]] = None,
+        response_mode: str = "full",
+        preview_chars: int = 200,
     ) -> List[RecallResult]:
         """
         Recall memories by cues or natural language.
@@ -231,6 +233,8 @@ class CueMap:
             "cuebridge_gap_limit": cuebridge_gap_limit,
             "semantic_mode": semantic_mode,
             "query_embedding": query_embedding,
+            "response_mode": response_mode,
+            "preview_chars": preview_chars,
         }
         if cues:
             payload["cues"] = cues
@@ -257,7 +261,7 @@ class CueMap:
         if projects and isinstance(results, list) and len(results) > 0 and "project_id" in results[0]:
             return data
             
-        return [RecallResult(**r) for r in results]
+        return [(RecallPreviewResult if response_mode == "preview" else RecallResult)(**r) for r in results]
     
     def recall_grounded(
         self,
@@ -302,8 +306,12 @@ class CueMap:
         
         return response.json()
 
-    def list_projects(self) -> List[str]:
-        """List all projects (multi-tenant only)."""
+    def list_projects(self) -> List[Dict[str, Any]]:
+        """List all projects and their runtime state (multi-tenant only).
+
+        Each item includes ``loaded`` so callers can distinguish a project
+        whose snapshot exists on disk from one currently resident in RAM.
+        """
         response = self.client.get(
             "/projects",
             headers=self._headers()
@@ -312,6 +320,93 @@ class CueMap:
             raise CueMapError(f"Failed to list projects: {response.text}")
         return response.json()
 
+    def load_project(self, project_id: str) -> Dict[str, Any]:
+        """Load a project's snapshot into engine memory."""
+        response = self.client.post(
+            f"/projects/{project_id}/load",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to load project: {response.text}")
+        return response.json()
+
+    def save_project(self, project_id: str) -> Dict[str, Any]:
+        """Persist a current project snapshot without unloading it."""
+        response = self.client.post(
+            f"/projects/{project_id}/save",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to save project: {response.text}")
+        return response.json()
+
+    def unload_project(self, project_id: str) -> Dict[str, Any]:
+        """Persist and unload a project from engine memory."""
+        response = self.client.post(
+            f"/projects/{project_id}/unload",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to unload project: {response.text}")
+        return response.json()
+
+    def pack_project(self, project_id: str) -> bytes:
+        """Return a ready-to-query project as portable ``.cuemap`` bytes."""
+        response = self.client.post(
+            f"/projects/{project_id}/pack",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to pack project: {response.text}")
+        return response.content
+
+    def load_project_package(self, package: bytes) -> Dict[str, Any]:
+        """Install and warm a portable ``.cuemap`` package."""
+        response = self.client.post(
+            "/projects/load",
+            content=package,
+            headers={
+                **self._headers(),
+                "Content-Type": "application/vnd.cuemap.project",
+            },
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to load project package: {response.text}")
+        return response.json()
+
+    def push_project(self, project_id: str, destination: str) -> Dict[str, Any]:
+        """Pack and upload a project using the server's configured AWS CLI."""
+        response = self.client.post(
+            f"/projects/{project_id}/push",
+            json={"destination": destination},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to push project: {response.text}")
+        return response.json()
+
+    def pull_project(self, source: str) -> Dict[str, Any]:
+        """Download, install, and warm a project using the server's AWS CLI."""
+        response = self.client.post(
+            "/projects/pull",
+            json={"source": source},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to pull project: {response.text}")
+        return response.json()
+
+    def sync_project(self, project_id: str, remote: str) -> Dict[str, Any]:
+        """Fast-forward a project through its immutable S3 sync history."""
+        response = self.client.post(
+            f"/projects/{project_id}/sync",
+            json={"remote": remote},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to sync project: {response.text}")
+        return response.json()
+
     def create_project(self, project_id: str) -> Dict[str, Any]:
         """Create a project."""
         response = self.client.post(
@@ -758,7 +853,7 @@ class AsyncCueMap:
     
     def __init__(
         self,
-        url: str = "http://localhost:8080",
+        url: str = "http://localhost:8735",
         api_key: Optional[str] = None,
         project_id: Optional[str] = None,
         timeout: float = 30.0
@@ -889,6 +984,8 @@ class AsyncCueMap:
         disable_systems_consolidation: Optional[bool] = None,
         semantic_mode: str = "hybrid",
         query_embedding: Optional[List[float]] = None,
+        response_mode: str = "full",
+        preview_chars: int = 200,
     ) -> List[RecallResult]:
         """Recall memories (async)."""
         payload = {
@@ -915,6 +1012,8 @@ class AsyncCueMap:
             "cuebridge_gap_limit": cuebridge_gap_limit,
             "semantic_mode": semantic_mode,
             "query_embedding": query_embedding,
+            "response_mode": response_mode,
+            "preview_chars": preview_chars,
         }
         if cues:
             payload["cues"] = cues
@@ -941,7 +1040,7 @@ class AsyncCueMap:
         if projects and isinstance(results, list) and len(results) > 0 and "project_id" in results[0]:
             return data
             
-        return [RecallResult(**r) for r in results]
+        return [(RecallPreviewResult if response_mode == "preview" else RecallResult)(**r) for r in results]
     
     async def recall_grounded(
         self,
@@ -979,8 +1078,8 @@ class AsyncCueMap:
         
         return response.json()
 
-    async def list_projects(self) -> List[str]:
-        """List all projects (async, multi-tenant only)."""
+    async def list_projects(self) -> List[Dict[str, Any]]:
+        """List all projects and their runtime state (async, multi-tenant only)."""
         response = await self.client.get(
             "/projects",
             headers=self._headers()
@@ -989,6 +1088,93 @@ class AsyncCueMap:
             raise CueMapError(f"Failed to list projects: {response.text}")
         return response.json()
 
+    async def load_project(self, project_id: str) -> Dict[str, Any]:
+        """Load a project's snapshot into engine memory (async)."""
+        response = await self.client.post(
+            f"/projects/{project_id}/load",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to load project: {response.text}")
+        return response.json()
+
+    async def save_project(self, project_id: str) -> Dict[str, Any]:
+        """Persist a current project snapshot without unloading it (async)."""
+        response = await self.client.post(
+            f"/projects/{project_id}/save",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to save project: {response.text}")
+        return response.json()
+
+    async def unload_project(self, project_id: str) -> Dict[str, Any]:
+        """Persist and unload a project from engine memory (async)."""
+        response = await self.client.post(
+            f"/projects/{project_id}/unload",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to unload project: {response.text}")
+        return response.json()
+
+    async def pack_project(self, project_id: str) -> bytes:
+        """Return a ready-to-query project as portable ``.cuemap`` bytes (async)."""
+        response = await self.client.post(
+            f"/projects/{project_id}/pack",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to pack project: {response.text}")
+        return response.content
+
+    async def load_project_package(self, package: bytes) -> Dict[str, Any]:
+        """Install and warm a portable ``.cuemap`` package (async)."""
+        response = await self.client.post(
+            "/projects/load",
+            content=package,
+            headers={
+                **self._headers(),
+                "Content-Type": "application/vnd.cuemap.project",
+            },
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to load project package: {response.text}")
+        return response.json()
+
+    async def push_project(self, project_id: str, destination: str) -> Dict[str, Any]:
+        """Pack and upload a project using the server's configured AWS CLI (async)."""
+        response = await self.client.post(
+            f"/projects/{project_id}/push",
+            json={"destination": destination},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to push project: {response.text}")
+        return response.json()
+
+    async def pull_project(self, source: str) -> Dict[str, Any]:
+        """Download, install, and warm a project using the server's AWS CLI (async)."""
+        response = await self.client.post(
+            "/projects/pull",
+            json={"source": source},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to pull project: {response.text}")
+        return response.json()
+
+    async def sync_project(self, project_id: str, remote: str) -> Dict[str, Any]:
+        """Fast-forward a project through its immutable S3 sync history (async)."""
+        response = await self.client.post(
+            f"/projects/{project_id}/sync",
+            json={"remote": remote},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise CueMapError(f"Failed to sync project: {response.text}")
+        return response.json()
+
     async def create_project(self, project_id: str) -> Dict[str, Any]:
         """Create a project (async)."""
         response = await self.client.post(

{cuemap-0.7.2 → cuemap-0.7.3}/cuemap/embedded.py

@@ -39,9 +39,11 @@ def _free_port() -> int:
 
 
 def _platform_package() -> str:
-    operating_system = platform.system().lower()
+    operating_system = {"Windows": "win32", "Darwin": "darwin", "Linux": "linux"}.get(platform.system())
     machine = platform.machine().lower()
-    architecture = "arm64" if machine in {"arm64", "aarch64"} else "x64"
+    architecture = {"arm64": "arm64", "aarch64": "arm64", "amd64": "x64", "x86_64": "x64"}.get(machine)
+    if operating_system is None or architecture is None or (operating_system == "win32" and architecture != "x64"):
+        raise RuntimeError(f"Unsupported CueMap platform: {platform.system()} {machine}")
     return f"@cuemap-dev/engine-{operating_system}-{architecture}"
 
 
@@ -49,9 +51,16 @@ def _npm_global_binary() -> Optional[str]:
     npm = shutil.which("npm")
     if not npm:
         return None
+    npm_command = [npm]
+    if platform.system() == "Windows":
+        node = shutil.which("node")
+        npm_cli = Path(npm).parent / "node_modules" / "npm" / "bin" / "npm-cli.js"
+        if not node or not npm_cli.is_file():
+            return None
+        npm_command = [node, str(npm_cli)]
     try:
         root = subprocess.run(
-            [npm, "root", "--global"],
+            [*npm_command, "root", "--global"],
             check=True,
             capture_output=True,
             text=True,
@@ -59,8 +68,8 @@ def _npm_global_binary() -> Optional[str]:
         ).stdout.strip()
     except (OSError, subprocess.SubprocessError):
         return None
-    binary_name = "cuemap.exe" if os.name == "nt" else "cuemap"
-    candidate = Path(root) / _platform_package() / "bin" / binary_name
+    package_bin = Path(root) / _platform_package() / "bin"
+    candidate = package_bin / ("cuemap-native.exe" if platform.system() == "Windows" else "cuemap")
     return str(candidate) if candidate.is_file() else None
 
 
@@ -75,7 +84,7 @@ def resolve_cuemap_binary(explicit_path: Optional[str] = None) -> str:
         return str(path)
 
     installed = shutil.which("cuemap")
-    if installed:
+    if installed and Path(installed).suffix.lower() not in {".cmd", ".bat", ".ps1"}:
         return installed
 
     global_binary = _npm_global_binary()
@@ -113,7 +122,7 @@ class EmbeddedCueMap:
         *,
         url: Optional[str] = None,
         bin_path: Optional[str] = None,
-        port: int = 8080,
+        port: int = 8735,
         config_path: Optional[str] = None,
         api_key: Optional[str] = None,
         startup_timeout: float = 15.0,
@@ -138,13 +147,27 @@ class EmbeddedCueMap:
         selected_port = _free_port() if status == "occupied" else port
         selected_url = f"http://127.0.0.1:{selected_port}"
         executable = resolve_cuemap_binary(bin_path)
-        arguments = [executable, "start", "--port", str(selected_port)]
+        command = [executable]
+        if platform.system() == "Windows" and Path(executable).suffix.lower() != ".exe":
+            if Path(executable).suffix.lower() in {".cmd", ".bat", ".ps1"}:
+                raise ValueError("Use the native .exe or the npm package bin/cuemap wrapper, not a shell shim")
+            node = shutil.which("node")
+            if not node:
+                raise FileNotFoundError("Node.js is required to launch the CueMap npm wrapper")
+            command = [node, executable]
+        arguments = [*command, "start", "--port", str(selected_port)]
         if config_path:
             arguments.extend(["--config", str(Path(config_path).expanduser())])
         process_env = dict(os.environ)
         if env:
             process_env.update(env)
         process_env["CUEMAP_PORT"] = str(selected_port)
+        process_env["CUEMAP_HOST"] = "127.0.0.1"
+        tokenizer = Path(executable).parent.parent / "assets" / "en_tokenizer.bin"
+        if Path(executable).name == "cuemap-native.exe" and tokenizer.is_file():
+            process_env.setdefault("TOKENIZER_PATH", str(tokenizer))
+        if api_key:
+            process_env["CUEMAP_API_KEY"] = api_key
 
         log(f"Starting CueMap at {selected_url}")
         process = subprocess.Popen(
@@ -164,7 +187,7 @@ class EmbeddedCueMap:
                 return cls(selected_url, True, process, shutdown_timeout)
             time.sleep(0.1)
 
-        process.terminate()
+        cls(selected_url, True, process, shutdown_timeout).stop()
         raise TimeoutError(f"CueMap did not become ready within {startup_timeout:g}s")
 
     def stop(self) -> None:

{cuemap-0.7.2 → cuemap-0.7.3}/cuemap/models.py

@@ -37,3 +37,11 @@ class RecallResult(BaseModel):
     structural_cues: List[str] = Field(default_factory=list)
     metadata: Dict[str, Any] = Field(default_factory=dict)
     explain: Optional[Dict[str, Any]] = None
+
+
+class RecallPreviewResult(RecallResult):
+    """Engine-provided leading excerpt; fetch the memory for full evidence."""
+    content: Optional[str] = None
+    preview: str
+    content_truncated: bool
+    content_length: int

{cuemap-0.7.2 → cuemap-0.7.3/cuemap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuemap
-Version: 0.7.2
+Version: 0.7.3
 Summary: CueMap Python SDK - High-performance temporal-associative memory
 Author-email: Kaan Demirel <hello@cuemap.dev>
 License: MIT
@@ -33,13 +33,26 @@ Requires-Dist: build>=1.0.0; extra == "dev"
 Requires-Dist: twine>=4.0.0; extra == "dev"
 Dynamic: license-file
 
-# CueMap Python SDK
+<p align="center">
+  <img src="https://cuemap.dev/cuemap-logo.PNG" alt="CueMap" width="120">
+</p>
+
+<h1 align="center">CueMap Python SDK</h1>
+
+<p align="center">A polished Python client for fast, accurate, and explainable agent memory.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/cuemap/"><img src="https://img.shields.io/pypi/v/cuemap?logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/cuemap/"><img src="https://img.shields.io/pypi/pyversions/cuemap?logo=python&logoColor=white" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5e5ce6" alt="License"></a>
+  <a href="https://github.com/cuemap-dev/cuemap"><img src="https://img.shields.io/badge/engine-v0.7.3-0f766e" alt="Engine compatibility"></a>
+</p>
 
 **High-performance temporal-associative memory store** designed for dynamic contextual retrieval.
 
 ## Overview
 
-CueMap implements a **Continuous Gradient Algorithm** optimized for associative data structures:
+CueMap uses **temporal-associative retrieval**: lexical and structural candidate generation, with optional semantic reranking. Its main components are:
 
 1.  **Intersection (Context Filter)**: Triangulates relevant memories by overlapping cues
 2.  **Local semantic reranking**: Uses bundled qint8 MiniLM-L3 by default, or q4 MiniLM-L3 with the edge profile, for bounded semantic ranking inside the engine.
@@ -47,9 +60,9 @@ CueMap implements a **Continuous Gradient Algorithm** optimized for associative
 4.  **Reinforcement (Access-based Learning)**: Frequently accessed memories gain signal strength, remaining highly accessible even as they age.
 5.  **Deterministic Facets & Intent Routing**: Extracts synchronous source, evidence, temporal, type, and entity facets, then uses sparse intent cues and reranking during recall.
 
-As of v0.7.2, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `all-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
+As of v0.7.3, CueMap keeps deterministic lexical candidate discovery and adds bundled qint8 `paraphrase-MiniLM-L3-v2` for bounded hybrid semantic and intent reranking. The `edge` engine profile uses a q4 build of the same model. No runtime model download is required, and callers can disable the encoder or provide their own vectors.
 
-v0.7.2 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
+v0.7.3 also preserves numeric per-project memory IDs everywhere. If callers need deterministic upsert/dedupe identity, pass `source_key`; memory IDs remain compact runtime addresses.
 
 Use this SDK to talk to the Rust engine from Python applications.
 
@@ -64,7 +77,7 @@ pip install cuemap
 ### 1. Start the Engine
 
 ```bash
-docker run -p 8080:8080 cuemap/engine:latest
+docker run -p 8735:8735 cuemap/engine:latest
 ```
 
 ### 2. Basic Usage
@@ -134,9 +147,29 @@ print(response["proof"])
 # Cryptographic proof of context retrieval
 ```
 
-### v0.7.2 Recall Controls
+### Project memory lifecycle
 
-CueMap v0.7.2 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
+The engine can unload inactive project contexts while keeping their snapshots
+on disk. Normal project operations demand-load a project when needed, so the
+first request after an unload may take longer. Use the explicit helpers when
+you want to control residency:
+
+```python
+client.unload_project("older-repository")
+client.load_project("older-repository")
+client.save_project("older-repository")  # persist without unloading
+
+for project in client.list_projects():
+    print(project["project_id"], project["loaded"])
+```
+
+Portable projects use the same four operations as the CLI:
+`pack_project()`, `load_project_package()`, `push_project()`, and `pull_project()`.
+Use `sync_project(project_id, "s3://bucket/team")` for conflict-safe fast-forward sync.
+
+### v0.7.3 Recall Controls
+
+CueMap v0.7.3 adds local semantic query signals alongside temporal query intent and optional reconstruction passes for longer conversational/codebase context.
 
 ```python
 results = client.recall(
@@ -250,3 +283,15 @@ async with AsyncCueMap() as client:
 ## License
 
 MIT
+
+### Recall previews
+
+The engine's `POST /recall` accepts `response_mode: "preview"` and optional
+`preview_chars` (100–2000 UTF-16 code units, default 200). Full content remains
+the default. Previews replace each hit's `content` with a leading `preview`,
+`content_truncated`, and `content_length`, preserving metadata and ranking.
+Use previews for broad discovery, then fetch a selected memory with
+`GET /memories/{id}?decoded=true` or read its source. Metadata and diagnostics
+are not capped. TypeScript request objects and Python sync/async `recall`
+accept these same options; Python returns `RecallPreviewResult` for ungrouped
+preview results. The updated engine is required.

{cuemap-0.7.2 → cuemap-0.7.3}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=61.0"]
+requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "cuemap"
-version = "0.7.2"
+version = "0.7.3"
 description = "CueMap Python SDK - High-performance temporal-associative memory"
 readme = "README.md"
 requires-python = ">=3.8"