V0.7.3

.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Package validation
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - uses: actions/checkout@v4
+        with:
+          repository: cuemap-dev/typescript-sdk
+          ref: v0.7.3
+          path: .release-sdk
+      - run: npm ci
+        working-directory: .release-sdk
+      - run: npm run build
+        working-directory: .release-sdk
+      - run: npm install --ignore-scripts --omit=optional --no-save --package-lock=false ./.release-sdk
+      - run: npm test
+      - run: npm pack --dry-run

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.7.3] - 2026-08-27
+
+### Changed
+
+- Synchronized the MCP server release and documentation with CueMap Engine v0.7.3.
+- Documented mobile-language ingestion for Swift, Dart, Objective-C, and Kotlin repositories.
+- Documented the separately published CueMap Agent Plugin integration.
+- Changed the embedded engine's preferred default port from `8080` to `8735`; `CUEMAP_PORT` remains available for overrides.
+- Updated tool and skill guidance for focused, iterative coding investigations using existing recall controls and direct source inspection.
+
+### Added
+
+- Added project save/load/unload tools and confirmed `.cuemap` pack/load/push/pull tools; `cuemap_projects` reports whether each project is currently loaded.
+- Added confirmed `cuemap_project_sync` with immutable history and divergence protection.
+- Preview shaping now lives in the engine. MCP forwards the options and preserves its response; older engines report an explicit unsupported-preview error instead of silently returning full chunks.
+- Added opt-in recall `response_mode: "preview"` with bounded `preview_chars` for broad discovery. Returns leading excerpts and truncation flags in both MCP output forms, retaining evidence handles and metadata; full content remains the default.
+- Memory inspection requests `GET /memories/:id?decoded=true` and returns readable source evidence without storage bytes or vectors. Requires an engine supporting decoded reads; older engines produce an explicit upgrade error for this tool.
+- Recall now returns engine JSON in both text and MCP structured content, preserving source metadata, diagnostics, empty project groups, and project errors. Memory records expose project-scoped `memory_id` handles for follow-up inspection. This replaces the previous prose-only response format.
+
+
 ## [0.7.2] - 2026-08-04
 
 ### Added

README.md

@@ -1,12 +1,27 @@
-# CueMap MCP Server v0.7.2
+<p align="center">
+  <img src="https://cuemap.dev/cuemap-logo.PNG" alt="CueMap" width="120">
+</p>
+
+<h1 align="center">CueMap MCP Server v0.7.3</h1>
+
+<p align="center">A premium MCP bridge for explainable, repository-aware agent memory.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/cuemap-mcp"><img src="https://img.shields.io/npm/v/cuemap-mcp?logo=npm" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/cuemap-mcp"><img src="https://img.shields.io/npm/dm/cuemap-mcp?logo=npm" alt="npm downloads"></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-7c3aed" alt="MCP compatible"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5e5ce6" alt="License"></a>
+</p>
 
 The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for CueMap, allowing AI coding assistants (like Claude Desktop, Cursor, Windsurf, and Antigravity) to instantly recall codebase context using the CueMap engine.
 
+For agent-facing operating guidance—including repository consent, supported content types, recall modes, accuracy-oriented knob selection, and troubleshooting—see [SKILL.md](SKILL.md).
+
 ## Zero-Config Deployment
 
-The CueMap MCP Server is designed to work completely out-of-the-box. When started, it automatically manages a high-performance Rust instance of the CueMap Server in the background. The v0.7.2 engine bundles qint8 MiniLM-L3 by default and q4 MiniLM-L3 for the edge profile; no model download occurs at runtime.
+The CueMap MCP Server is designed to work completely out-of-the-box. When started, it automatically manages a high-performance Rust instance of the CueMap Server in the background. The v0.7.3 engine bundles qint8 MiniLM-L3 by default and q4 MiniLM-L3 for the edge profile; no model download occurs at runtime.
 
-You do **not** need to install or run the CueMap CLI manually. The correct pre-compiled binary for your operating system is automatically downloaded via optional NPM dependencies.
+You do **not** need to install or run the CueMap CLI manually. The correct pre-compiled binary for your operating system is automatically downloaded via optional NPM dependencies. Embedded startup supports Linux x64/ARM64, macOS x64/ARM64, and Windows x64.
 
 ## Installation
 
@@ -17,13 +32,17 @@ npm install -g cuemap-mcp
 
 *(Note: Ensure your package manager is configured to download `optionalDependencies` so the local Rust binary is included).*
 
+## Agent Plugin
+
+CueMap also ships a separate [`cuemap-agent-plugin`](https://www.npmjs.com/package/cuemap-agent-plugin) package for Agent Plugins-compatible clients. It bundles the portable `plugin.json` manifest, stdio `mcp.json` configuration, and a repository-memory skill. The plugin launches this MCP server at the matching release version and must be installed or downloaded separately from `cuemap-mcp`.
+
 ## Configuration (Environment Variables)
 
-By default, the embedded engine runs on port `8080`. You can customize the server behavior by passing the following environment variables in your MCP configuration:
+By default, the embedded engine runs on port `8735`. You can customize the server behavior by passing the following environment variables in your MCP configuration:
 
-- `CUEMAP_PORT`: Override the port the embedded engine binds to (default: `8080`).
+- `CUEMAP_PORT`: Override the port the embedded engine binds to (default: `8735`).
 - `CUEMAP_CONFIG_PATH`: Absolute path to a custom `server_config.toml` to configure advanced Engine tuning, background jobs, and RAG search parameters.
-- `CUEMAP_URL`: If you prefer to bypass the embedded engine and connect to a remotely hosted or separately running CueMap server, specify its URL here (e.g. `http://localhost:8080`).
+- `CUEMAP_URL`: If you prefer to bypass the embedded engine and connect to a remotely hosted or separately running CueMap server, specify its URL here (e.g. `http://localhost:8735`).
 - `CUEMAP_PROJECT`: Override the default project. Without this setting, CueMap derives a stable repository-scoped project from the current Git remote or working directory.
 - `CUEMAP_LOG_PATH`: Override the embedded engine log path. It defaults to `~/.cuemap/server.log`, which is the file read by `cuemap logs`.
 
@@ -47,7 +66,7 @@ To use this MCP server with your AI assistant, add it to your assistant's MCP co
         "cuemap-mcp"
       ],
       "env": {
-        "CUEMAP_PORT": "8080"
+        "CUEMAP_PORT": "8735"
       }
     }
   }
@@ -81,9 +100,21 @@ To use this MCP server with your AI assistant, add it to your assistant's MCP co
 
 ### Project inspection and memory lifecycle
 
-- **`cuemap_projects`**: List projects and their summary metadata.
+- **`cuemap_projects`**: List projects and their summary metadata, including
+  whether each project is currently loaded in RAM.
+- **`cuemap_project_load`**: Explicitly warm a persisted project before a
+  latency-sensitive operation. Ordinary project requests demand-load it when
+  needed.
+- **`cuemap_project_save`**: Persist a current snapshot without unloading it.
+- **`cuemap_project_unload`**: Persist and unload a project to reduce memory
+  usage. Active work can produce a retryable busy response.
+- **`cuemap_project_pack` / `cuemap_project_package_load`**: Write or load a
+  ready-to-query local `.cuemap` package.
+- **`cuemap_project_push` / `cuemap_project_pull`**: Transfer a package through
+  S3 using the engine host's configured AWS CLI.
+- **`cuemap_project_sync`**: Fast-forward immutable S3 history and refuse divergence.
 - **`cuemap_stats`**: Read repository-project statistics, or global engine statistics with `global: true`.
-- **`cuemap_memory_get`**: Read one memory by numeric `memory_id`.
+- **`cuemap_memory_get`**: Read one memory as decoded text and provenance by numeric `memory_id` and owning `project`. Requires an engine supporting `GET /memories/:id?decoded=true`; older engines return an upgrade error through this tool.
 - **`cuemap_memory_reinforce`**: Reinforce one memory, optionally on explicit `cues`.
 - **`cuemap_memory_delete`**: Permanently delete one memory. Requires `confirmed: true` after explicit user confirmation.
 - **`cuemap_project_export`**: Export a cursor-paginated project page with configurable content, cue, and metadata inclusion.
@@ -117,11 +148,13 @@ These tools are for explicit ingestion requests. Repository initialization conti
 - **`cuemap_recall`**: Recalls context about a codebase from your CueMap integrated brain. Uses natural language and semantic search to find relevant information.
   - `query` (string): The natural language query to search for.
   - `limit` (number, optional): Maximum results to return (default: 10).
+  - `response_mode` (`full` | `preview`, optional): Default `full`. Use `preview` for broad discovery; each hit returns a leading excerpt instead of full content, retaining IDs and metadata.
+  - `preview_chars` (integer, optional): Preview length cap, 100–2000 UTF-16 code units (default: 200). Ignored in full mode. Metadata and diagnostics are not capped.
   - `projects` (string[], optional): List of project IDs to scope the search to. Multiple enables cross-project queries.
   - `cues` (string[], optional): Specific cue tags to filter the search.
   - `query_time` (string, optional): Timestamp or natural-language time anchor for v0.7 temporal query intent.
   - `depth` (number, optional): Depth of multi-hop recall expander (default: 1).
-  - `expansion_depth` (number, optional): Alias/cue expansion depth (default: 1).
+  - `expansion_depth` (number, optional): Neighbor context expansion (default: 1). Values above 1 include nearby parent chunks or source-ordered context, using a radius of `expansion_depth - 1` when linkage exists.
   - `auto_reinforce` (boolean, optional): Automatically reinforce retrieved memories (default: false).
   - `min_intersection` (number, optional): Minimum required cue intersection count (default: 0).
   - `explain` (boolean, optional): Include scoring explanation data in results (default: false).
@@ -136,6 +169,34 @@ These tools are for explicit ingestion requests. Repository initialization conti
   - `semantic_mode` (`lexical`, `semantic`, or `hybrid`, optional): Choose cue-only recall, vector candidate discovery, or local semantic reranking of lexical candidates. The engine default is `hybrid`.
 - `query_embedding` (number[], optional): Supply a precomputed query vector when the calling application owns the embedding provider.
 
+### Recall response and follow-up inspection
+
+Recall returns engine JSON in both MCP `structuredContent` and a matching JSON
+text block. This replaces the earlier prose-only format. Each identified
+memory carries `project_id` and `memory_id`; metadata, source locations, and
+requested diagnostics are preserved as supplied by the engine. Explicit
+project queries may return project blocks containing their own `results` or
+`error`, including empty groups. Ordinary unscoped queries return memory
+records directly in `results`.
+
+Use a hit's project and ID with `cuemap_memory_get` when the stored record is
+needed. That tool returns readable content without vectors or compressed
+storage bytes; it does not expand neighboring chunks or read live files.
+Prefer opening the cited source when recall already returned the relevant
+text. Follow-up recalls should address a new evidence gap. See [SKILL.md](SKILL.md)
+for the coding investigation workflow and bounded recall controls.
+
+For broad discovery, pass `response_mode: "preview"`. A hit's `content` is
+replaced by `preview`, `content_truncated`, and `content_length` (UTF-16 code
+units). This is a leading excerpt, not a generated summary or query-selected
+snippet. Full content is omitted from both MCP output forms; fetch promising
+memories by their project/ID or read the live source. Full mode remains the
+default. The engine shapes previews before sending its response. This does not change
+ranking or retrieval work, and does not limit metadata or diagnostics.
+
 ## License
 
-MIT - See the [LICENSE](LICENSE) file for more details.
+The MCP server package is MIT-licensed. Its optional native engine dependencies
+are separate packages: v0.7.3 and later engine packages are Apache-2.0, while
+pre-v0.7.3 engine packages remain under BSL-1.1. See [LICENSE](LICENSE) for the
+MCP server license.