V0.7.3

.github/workflows/test.yml

@@ -0,0 +1,25 @@
+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]
+        node: [18, 24]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci
+      - run: npm test
+      - run: npm pack --dry-run

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to the CueMap TypeScript SDK will be documented in this file.
 
+## [0.7.3] - 2026-08-27
+
+### Changed
+- Synchronized the SDK patch release and documentation with CueMap Engine v0.7.3.
+- Documented compatibility with the engine's Tree-sitter-backed Swift, Dart, Objective-C, and Kotlin ingestion support.
+- Changed the default direct-client and embedded-engine port from `8080` to `8735`.
+
+### Added
+- Added project lifecycle methods plus portable project `pack`, `load`, `push`, and `pull`; project listings expose the engine's `loaded` state.
+- Added typed `syncProject()` support for fast-forward S3 project history.
+
 ## [0.7.2] - 2026-07-18
 
 ### Added

README.md

@@ -1,20 +1,33 @@
-# CueMap TypeScript SDK
+<p align="center">
+  <img src="https://cuemap.dev/cuemap-logo.PNG" alt="CueMap" width="120">
+</p>
+
+<h1 align="center">CueMap TypeScript SDK</h1>
+
+<p align="center">A polished TypeScript client for fast, accurate, and explainable agent memory.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/cuemap"><img src="https://img.shields.io/npm/v/cuemap?logo=npm" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/cuemap"><img src="https://img.shields.io/npm/dm/cuemap?logo=npm" alt="npm downloads"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-ready-3178c6?logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5e5ce6" alt="License"></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 and Intent Reranking**: Uses bundled qint8 MiniLM-L3 by default, or q4 MiniLM-L3 with the edge profile.
 3.  **Recency & Salience (Signal Dynamics)**: Balances fresh data with salient, high-signal events prioritized by an adaptive impact scoring module.
 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 uses 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 uses 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 TypeScript and JavaScript applications.
 
@@ -29,7 +42,7 @@ npm 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
@@ -82,9 +95,9 @@ console.log(response.results[0].explain);
 // Shows normalized cues, intent cues, and reranking details.
 ```
 
-### v0.7.2 Recall Controls
+### v0.7.3 Recall Controls
 
-CueMap v0.7.2 adds local semantic query signals alongside temporal query intent and the optional reconstruction passes for longer conversational/codebase context.
+CueMap v0.7.3 adds local semantic query signals alongside temporal query intent and the optional reconstruction passes for longer conversational/codebase context.
 
 ```typescript
 const response = await client.recall({
@@ -114,6 +127,27 @@ console.log(response.proof);
 // Cryptographic proof of context retrieval
 ```
 
+### Project memory lifecycle
+
+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:
+
+```typescript
+await client.unloadProject("older-repository");
+await client.loadProject("older-repository");
+await client.saveProject("older-repository"); // persist without unloading
+
+for (const project of await client.listProjects()) {
+  console.log(project.project_id, project.loaded);
+}
+```
+
+Portable projects use the same four operations as the CLI: `packProject()`,
+`loadProjectPackage()`, `pushProject()`, and `pullProject()`.
+Use `syncProject(projectId, "s3://bucket/team")` for conflict-safe fast-forward sync.
+
 For a controlled semantic comparison, use `semantic_mode: "lexical"`. Use `"semantic"` for vector candidate discovery or `"hybrid"` (the engine default) to rerank lexical candidates with the configured local encoder. `query_embedding` can supply a precomputed vector when the application owns the embedding provider.
 
 Classify query or memory intent with the same local model. Returned scores are ranking signals, not calibrated probabilities:
@@ -209,3 +243,15 @@ console.log(`Intent ready: ${status.intent_ready ?? false}`);
 ## 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.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cuemap",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "CueMap TypeScript SDK - High-performance temporal-associative memory",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,8 +17,8 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "npm run build && node --test test/*.test.js",
-    "test:e2e": "CUEMAP_E2E=1 node --test test/*.test.js",
+    "test": "npm run build && node scripts/run-tests.cjs",
+    "test:e2e": "npm run build && node scripts/run-e2e.cjs",
     "test:pack": "node scripts/verify-packed-install.mjs"
   },
   "keywords": [

scripts/run-e2e.cjs

@@ -0,0 +1,6 @@
+const { spawnSync } = require('node:child_process');
+const { readdirSync } = require('node:fs');
+const files = readdirSync('test').filter(name => /\.test\.(c?js)$/.test(name)).map(name => `test/${name}`);
+const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit', env: { ...process.env, CUEMAP_E2E: '1' } });
+if (result.error) throw result.error;
+process.exitCode = result.status ?? 1;

scripts/run-tests.cjs

@@ -0,0 +1,21 @@
+const { spawnSync } = require('node:child_process');
+const { readdirSync } = require('node:fs');
+
+const files = readdirSync('test')
+  .filter((name) => /\.test\.js$/.test(name))
+  .sort()
+  .map((name) => `test/${name}`);
+
+if (files.length === 0) {
+  throw new Error('No test files found in test/');
+}
+
+const result = spawnSync(process.execPath, ['--test', ...files], {
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exitCode = result.status ?? 1;

scripts/verify-packed-install.mjs

@@ -9,13 +9,13 @@ const sandbox = mkdtempSync(join(tmpdir(), "cuemap-ts-pack-") );
 
 try {
   execFileSync("npm", ["pack", "--pack-destination", sandbox], { cwd: packageRoot, stdio: "inherit" });
-  const tarball = join(sandbox, "cuemap-0.7.2.tgz");
+  const tarball = join(sandbox, "cuemap-0.7.3.tgz");
   execFileSync("npm", ["init", "-y"], { cwd: sandbox, stdio: "ignore" });
   execFileSync("npm", ["install", "--ignore-scripts", "--no-save", tarball], { cwd: sandbox, stdio: "inherit" });
   const probe = [
     "const fs = require('node:fs'); const path = require('node:path');",
     "const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(require.resolve('cuemap')), '..', 'package.json')));",
-    "if (pkg.version !== '0.7.2') throw new Error('unexpected package version');",
+    "if (pkg.version !== '0.7.3') throw new Error('unexpected package version');",
     "const sdk = require('cuemap');",
     "if (typeof sdk.default !== 'function') throw new Error('default SDK export missing');",
     "const embedded = require('cuemap/embedded');",