@wiscale/velesdb-sdk 1.18.0 → 3.0.0

package/README.md

@@ -2,7 +2,18 @@
 
 Official TypeScript SDK for [VelesDB](https://github.com/cyberlife-coder/VelesDB) -- the local-first vector database for AI and RAG. Sub-millisecond semantic search in Browser and Node.js.
 
-**v1.18.0** | Node.js >= 18 | Browser (WASM) | VelesDB Core License 1.0
+**v3.0.0** | Node.js >= 18 | Browser (WASM) | VelesDB Core License 1.0
+
+## What's New (unreleased)
+
+- **Streaming ingestion enablement (2026-06-14)** (REST backend): `enableStreaming(collection, config?)` turns on the bounded streaming-ingestion channel before `streamInsert()`. The optional `StreamingConfig` (`bufferSize`, `batchSize`, `flushIntervalMs`) is camelCase; omitted fields fall back to the server defaults. See [`db.enableStreaming`](#dbenablestreamingcollection-config) below. The WASM backend throws `NOT_SUPPORTED`.
+- **Relation + durable-TTL surface** (REST backend): `relate()`, `unrelate()`, `getRelations()`, `setTtlDurable()` — now fully tested and documented (see [Knowledge Graph API](#knowledge-graph-api) and [Agent Memory API](#agent-memory-api) below). The WASM backend throws `NOT_SUPPORTED` for these methods.
+- The shipped example (`examples/hybrid_queries.ts`) was rewritten against the real API and is now compile-checked in CI.
+
+## What's New in v2.0.0
+
+- v2.0.0: graph dimension on agent memory — `relate()` / `relations()` / `unrelate()`; durable-TTL setters; aligns with the engine 2.0 release. See the root [CHANGELOG](../../CHANGELOG.md) for the breaking VelesQL changes.
+- v1.18.0: agent-memory parity wave — temporal recall facades (`recallRecent` / `recallOlderThan`), id-coercion hardening for `deleteMemory(string | number)`.
 
 ## What's New in v1.16.0
 
@@ -30,7 +41,7 @@ Official TypeScript SDK for [VelesDB](https://github.com/cyberlife-coder/VelesDB
 ### Previous (v1.13.0)
 
 - **WASM VelesQL executor** -- full browser-side VelesQL execution: SELECT/INSERT/UPDATE/DELETE/DDL + aggregations (COUNT/SUM/AVG/MIN/MAX) + GROUP BY/HAVING/UNION/INTERSECT/EXCEPT/JOIN/FUSION/MATCH 1-2 hops + NOT De Morgan distribution
-- **TS SDK coverage raised to 94%** -- 423 tests, per-file thresholds codified in `vitest.config.ts`
+- **TS SDK coverage raised** -- per-file thresholds codified in `vitest.config.ts` (423 tests as of v1.13.0; the vitest suite has since grown past 770 cases). Note: the suite runs locally via `npm test` and is not currently executed in CI
 - **SIFT1M standardized ANN benchmark** -- fvecs/ivecs loader + Criterion ef sweep on the INRIA TEXMEX dataset, feature-gated behind `--features bench-sift1m`
 - **Security hardening** -- `validateCollectionName()` helper on TS SDK prevents VelesQL injection in `trainPq`
 - **API consistency** -- `streamInsert` now serializes `payload: null` explicitly (matches `streamUpsertPoints`)
@@ -160,7 +171,13 @@ const queryVector = new Float32Array(1536).fill(0.1);
 const results = await db.search('products', queryVector, { k: 10 });
 ```
 
-> **REST backend note:** Document IDs must be numeric integers in the range `0..Number.MAX_SAFE_INTEGER`. String IDs are only supported with the WASM backend.
+> **REST backend note:** Document IDs must be non-negative `u64` integers. Pass a JS
+> number in the range `0..Number.MAX_SAFE_INTEGER`, or a decimal string for the full
+> `u64` range — string ids above 2^53-1 (up to `18446744073709551615`) are kept
+> verbatim on the wire, so the ids returned by `recordEvent`/`learnProcedure`
+> round-trip through `get`/`delete` without precision loss. Exception: the NDJSON
+> bulk endpoint (`streamUpsertPoints`) only accepts safe-range numeric ids.
+> Arbitrary (non-numeric) string IDs are only supported with the WASM backend.
 
 > **Versioned routes:** The REST backend uses `/v1/` as the canonical route prefix
 > (e.g. `POST /v1/collections/{name}/search`). Legacy routes without the prefix
@@ -316,6 +333,21 @@ await db.upsertBatch('docs', [
 ]);
 ```
 
+#### `db.enableStreaming(collection, config?)`
+
+Enable the bounded streaming-ingestion channel on a collection. Call this once before `streamInsert()`. The optional `config` is camelCase; every field is optional and omitted fields fall back to the server defaults (REST only; the WASM backend throws `NOT_SUPPORTED`).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `bufferSize` | `number` | `10000` | Bounded ingestion channel capacity |
+| `batchSize` | `number` | `128` | Points flushed to the index per batch |
+| `flushIntervalMs` | `number` | `50` | Max milliseconds before a partial batch is flushed |
+
+```typescript
+await db.enableStreaming('docs', { bufferSize: 4096, batchSize: 64 });
+await db.streamInsert('docs', largeDocumentArray);
+```
+
 #### `db.streamInsert(collection, documents)`
 
 Insert documents with server backpressure support. Sends documents sequentially, respecting 429 rate limits. Throws `BackpressureError` if the server pushes back.
@@ -537,6 +569,14 @@ Get detailed collection configuration (dimension, metric, storage mode, point co
 
 Execute a VelesQL query. Supports SELECT, WHERE, vector NEAR, GROUP BY, HAVING, ORDER BY, JOIN, UNION/INTERSECT/EXCEPT, and USING FUSION.
 
+> **Backend support:** full VelesQL execution requires the **REST backend** (`velesdb-server`).
+> The WASM backend only executes pure top-k vector queries of the form
+> `SELECT * FROM <collection> WHERE vector NEAR $param [LIMIT n]` (`vector` is the
+> grammar keyword, not a column name) and throws a
+> `NOT_SUPPORTED` error for anything else (WHERE predicates, JOIN, GROUP BY, MATCH,
+> set operations, FUSION) instead of silently ignoring clauses. Accordingly,
+> `db.capabilities().velesqlQuery` is `false` on WASM.
+
 ```typescript
 // Vector similarity search
 const result = await db.query(
@@ -717,6 +757,56 @@ for (const node of result.results) {
 }
 ```
 
+#### `db.relate(collection, request)`
+
+Create a typed relation edge between two existing points. Returns the
+allocated edge ID (`RelateResponse = { edgeId: number | string }`). Point and
+edge IDs are `number | string` — IDs above `Number.MAX_SAFE_INTEGER` travel as
+decimal strings to avoid u64 precision loss. **REST backend only** (the WASM
+backend throws `NOT_SUPPORTED`).
+
+```typescript
+const { edgeId } = await db.relate('social', {
+  source: 100,
+  target: 200,
+  relType: 'FOLLOWS',
+  properties: { since: '2024-01-01' }  // optional, defaults to {}
+});
+```
+
+#### `db.unrelate(collection, edgeId)`
+
+Remove a relation edge by its ID. Returns `true` if the edge was removed,
+`false` if it did not exist. **REST backend only.**
+
+```typescript
+const removed = await db.unrelate('social', edgeId);
+```
+
+#### `db.getRelations(collection, pointId)`
+
+List the outgoing relation edges of a point. Returns
+`RelationsResponse = { edges: RelationEdge[]; count: number }` where each edge
+carries `{ id, source, target, relType, properties? }`. **REST backend only.**
+
+```typescript
+const { edges, count } = await db.getRelations('social', 100);
+for (const edge of edges) {
+  console.log(`${edge.source} -[${edge.relType}]-> ${edge.target}`);
+}
+```
+
+#### `db.setTtlDurable(collection, pointId, ttlSeconds)`
+
+Durably set (or refresh) the time-to-live of a point, in **seconds**. The
+expiry is persisted server-side (reserved `_veles_expires_at` payload field),
+so it survives a restart. `ttlSeconds` must be a non-negative number.
+**REST backend only.**
+
+```typescript
+await db.setTtlDurable('social', 100, 3600); // expire point 100 in 1 hour
+```
+
 ---
 
 ### Property Indexes
@@ -810,18 +900,25 @@ await memory.storeFact('knowledge', {
 const facts = await memory.searchFacts('knowledge', queryEmbedding, 5);
 ```
 
-Each recall method returns `SearchResult[]`:
+Each similarity-recall method (`searchFacts`, `recallEvents`,
+`recallProcedures`) returns `SearchResult[]`:
 
 ```typescript
 // SearchResult = { id: number; score: number; payload?: Record<string, unknown>; vector?: number[] }
 ```
 
+The temporal-recall methods (`recallRecent`, `recallOlderThan`) return
+`EpisodicRecord[]` instead — see [Episodic Memory](#episodic-memory-events-and-experiences).
+
 - `score` is the cosine similarity in `[0, 1]` (for a `cosine` collection);
   higher means more similar.
-- `payload` carries the stored fields (`text`, `event_type`, `name`, `steps`,
-  plus your metadata). The reserved keys `_memory_type` / `text` /
+- `payload` carries the stored fields (`content` for semantic text,
+  `event_type` / `timestamp` for episodic, `name` / `steps` for procedural,
+  plus your metadata). The reserved payload keys `_memory_type` / `content` /
   `event_type` / `timestamp` / `name` / `steps` always take precedence over
   caller `metadata`/`data` of the same name, so they cannot be clobbered.
+  Note: the `SemanticEntry.text` input field is stored as `content` in the
+  payload — `result.payload?.content` is the fact text on recall.
 
 #### Semantic Memory (facts and knowledge)
 
@@ -850,6 +947,17 @@ const eventId = await memory.recordEvent('events', {
 
 // Recall similar events
 const events = await memory.recallEvents('events', queryEmbedding, 5);
+
+// Temporal recall — no embedding needed, most-recent-first.
+// recallRecent(collection, since?): events with timestamp >= since
+// (inclusive, unix-seconds); recallOlderThan(collection, before): strictly older.
+const nowSecs = Math.floor(Date.now() / 1000);
+const allRecent = await memory.recallRecent('events');
+const lastHour = await memory.recallRecent('events', nowSecs - 3600);
+const stale = await memory.recallOlderThan('events', nowSecs - 86_400);
+
+// Both return EpisodicRecord[]:
+// { id: string; timestamp: number; payload: Record<string, unknown> }
 ```
 
 #### Procedural Memory (learned patterns)
@@ -880,9 +988,14 @@ await memory.deleteMemory('procedures', procId);
 > collection — the collection's own dimension (set at `createCollection`)
 > governs storage and search, and your embeddings must match it.
 
-> **TTL & snapshots.** Per-entry TTL (in **seconds**) and versioned snapshots are
-> exposed by the embedded Rust API only; the REST-backed TypeScript facade does
-> not surface them. See the [Agent Memory guide](../../docs/guides/AGENT_MEMORY.md).
+> **TTL & snapshots.** Durable per-point TTL (in **seconds**) **is** available
+> from this SDK: memory entries are regular points, so
+> [`db.setTtlDurable(collection, pointId, ttlSeconds)`](#dbsetttldurablecollection-pointid-ttlseconds)
+> expires a fact/event/procedure durably over REST. The subsystem-namespaced
+> TTL helpers (`set_semantic_ttl`, `store_with_ttl`, `auto_expire`) and
+> versioned snapshots remain embedded-only (Rust **and** Python bindings) and
+> are not exposed over REST. See the API-availability table in the
+> [Agent Memory guide](../../docs/guides/AGENT_MEMORY.md#api-availability-by-binding).
 
 ---
 
@@ -961,10 +1074,14 @@ import {
   type AddEdgeRequest,
   type TraverseRequest,
   type TraverseResponse,
+  type RelateRequest,
+  type RelateResponse,
+  type RelationsResponse,
   type QueryApiResponse,
   type AgentMemoryConfig,
   type SemanticEntry,
   type EpisodicEvent,
+  type EpisodicRecord,
   type ProceduralPattern,
 } from '@wiscale/velesdb-sdk';
 ```