@wiscale/velesdb-sdk 1.17.0 → 2.0.0

package/README.md

@@ -2,7 +2,17 @@
 
 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.17.0** | Node.js >= 18 | Browser (WASM) | MIT License
+**v2.0.0** | Node.js >= 18 | Browser (WASM) | VelesDB Core License 1.0
+
+## What's New (unreleased)
+
+- **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 +40,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 +170,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
@@ -537,6 +553,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 +741,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
@@ -772,7 +846,21 @@ const result = await db.trainPq('embeddings', {
 
 ### Agent Memory API
 
-The Agent Memory API provides three memory types for AI agents, built on top of VelesDB's vector and graph storage.
+The Agent Memory API provides three memory types for AI agents, built on top of
+VelesDB's vector storage. In the TypeScript/JavaScript SDK it is accessed **over
+REST** against a running `velesdb-server` (the Python and Rust bindings use the
+embedded engine instead).
+
+> **You must create the collection first.** The TS facade does **not**
+> auto-create a collection for you. Create it with the dimension that matches
+> your embedding model and the metric you want (`'cosine'` is the usual choice
+> for normalized text embeddings), then call `storeFact` / `recordEvent` /
+> `learnProcedure` against that same collection name.
+
+> **Embeddings are caller-supplied.** There is no auto-embedding: every
+> `embedding` you pass must come from your own embedding model (see
+> [Embedding helper](#embedding-helper)) and its length must equal the
+> collection dimension.
 
 ```typescript
 import { VelesDB } from '@wiscale/velesdb-sdk';
@@ -780,13 +868,46 @@ import { VelesDB } from '@wiscale/velesdb-sdk';
 const db = new VelesDB({ backend: 'rest', url: 'http://localhost:8080' });
 await db.init();
 
+// 1. Create the backing collection FIRST (nothing auto-creates it).
+//    The dimension must match your embedding model; cosine is typical.
+await db.createCollection('knowledge', { dimension: 384, metric: 'cosine' });
+
+// 2. Open the agent-memory facade.
 const memory = db.agentMemory({ dimension: 384 });
+
+// 3. Store and recall (embedding is your own model's output, length 384).
+await memory.storeFact('knowledge', {
+  id: 1,
+  text: 'VelesDB uses HNSW for vector indexing',
+  embedding: factEmbedding,
+});
+const facts = await memory.searchFacts('knowledge', queryEmbedding, 5);
+```
+
+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 (`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)
 
 ```typescript
-// Store a fact
+// Store a fact (id is caller-assigned; reusing an id upserts)
 await memory.storeFact('knowledge', {
   id: 1,
   text: 'VelesDB uses HNSW for vector indexing',
@@ -801,25 +922,37 @@ const facts = await memory.searchFacts('knowledge', queryEmbedding, 5);
 #### Episodic Memory (events and experiences)
 
 ```typescript
-// Record an event
-await memory.recordEvent('events', {
+// Record an event — returns the generated point id
+const eventId = await memory.recordEvent('events', {
   eventType: 'user_query',
   data: { query: 'How does HNSW work?', response: '...' },
   embedding: eventEmbedding,
-  metadata: { timestamp: Date.now() }
 });
 
 // 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)
 
 ```typescript
-// Store a procedure
-await memory.learnProcedure('procedures', {
+// Store a procedure — embedding is required so the pattern is recallable,
+// and the generated point id is returned
+const procId = await memory.learnProcedure('procedures', {
   name: 'deploy-to-prod',
   steps: ['Run tests', 'Build artifacts', 'Push to registry', 'Deploy'],
+  embedding: procedureEmbedding,
   metadata: { lastUsed: Date.now() }
 });
 
@@ -827,6 +960,27 @@ await memory.learnProcedure('procedures', {
 const procs = await memory.recallProcedures('procedures', queryEmbedding, 3);
 ```
 
+#### Deleting memories
+
+```typescript
+// Works for facts, events, and procedures — returns true if a point was removed
+await memory.deleteMemory('procedures', procId);
+```
+
+> **`dimension` is advisory.** `db.agentMemory({ dimension })` records a hint you
+> can read back via `memory.dimension`, but it does **not** create or size any
+> collection — the collection's own dimension (set at `createCollection`)
+> governs storage and search, and your embeddings must match it.
+
+> **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).
+
 ---
 
 ## Error Handling
@@ -904,10 +1058,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';
 ```
@@ -924,6 +1082,6 @@ import {
 
 ## License
 
-MIT License -- See [LICENSE](./LICENSE) for details.
+Licensed under the [VelesDB Core License 1.0](./LICENSE) (source-available). The SDK bundles the VelesDB WASM engine and is governed by the Core License.
 
 VelesDB Core and Server are licensed under VelesDB Core License 1.0 (source-available).