@wiscale/velesdb-sdk 1.18.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.18.0** | Node.js >= 18 | Browser (WASM) | VelesDB Core License 1.0
+**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
@@ -810,18 +884,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 +931,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 +972,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 +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';
 ```

package/dist/index.d.mts

@@ -12,8 +12,15 @@ type StorageMode = 'full' | 'sq8' | 'binary' | 'pq' | 'rabitq';
 type SearchQuality = 'fast' | 'balanced' | 'accurate' | 'perfect' | 'autotune' | `custom:${number}` | `adaptive:${number}:${number}`;
 /** Backend type for VelesDB connection */
 type BackendType = 'wasm' | 'rest';
-/** Numeric point ID required by velesdb-server REST API (`u64`). */
-type RestPointId = number;
+/**
+ * Point ID accepted by the velesdb-server REST API (`u64`).
+ *
+ * Ids within the JS safe-integer range are numbers; decimal-string ids above
+ * `Number.MAX_SAFE_INTEGER` (2^53-1) stay verbatim strings so the full u64
+ * range survives the JavaScript boundary without precision loss (the server
+ * deserialises both forms since #1004).
+ */
+type RestPointId = number | string;
 /** Configuration options for VelesDB client */
 interface VelesDBConfig {
     /** Backend type: 'wasm' for browser/Node.js, 'rest' for server */
@@ -563,6 +570,42 @@ interface DegreeResponse {
     /** Number of outgoing edges */
     outDegree: number;
 }
+/** Request body for POST /collections/{name}/relations */
+interface RelateRequest {
+    /** Source point ID */
+    source: GraphNodeId;
+    /** Target point ID */
+    target: GraphNodeId;
+    /** Relationship type label (e.g. "KNOWS", "RELATED_TO") */
+    relType: string;
+    /** Optional edge properties */
+    properties?: Record<string, unknown>;
+}
+/** Response from POST /collections/{name}/relations */
+interface RelateResponse {
+    /** Allocated edge ID */
+    edgeId: GraphNodeId;
+}
+/** A single outgoing relation edge */
+interface RelationEdge {
+    /** Edge ID */
+    id: GraphNodeId;
+    /** Source point ID */
+    source: GraphNodeId;
+    /** Target point ID */
+    target: GraphNodeId;
+    /** Relationship type label */
+    relType: string;
+    /** Edge properties */
+    properties?: Record<string, unknown>;
+}
+/** Response from GET /collections/{name}/points/{id}/relations */
+interface RelationsResponse {
+    /** Outgoing relation edges */
+    edges: RelationEdge[];
+    /** Total count */
+    count: number;
+}
 /** Schema mode for graph collections */
 type GraphSchemaMode = 'schemaless' | 'strict';
 /** Graph collection configuration */
@@ -583,8 +626,15 @@ interface GraphCollectionConfig {
  */
 /** Semantic memory entry */
 interface SemanticEntry {
-    /** Unique fact ID */
-    id: number;
+    /**
+     * Unique fact ID.
+     *
+     * `string | number` is accepted as a convenience (a string must be a decimal
+     * integer). Ids must be non-negative integers within the JS safe-integer
+     * range (0..2^53-1): the REST wire transmits point ids as JSON numbers, so
+     * out-of-range ids are rejected (not silently truncated).
+     */
+    id: string | number;
     /** Fact text content */
     text: string;
     /** Embedding vector */
@@ -594,8 +644,24 @@ interface SemanticEntry {
 }
 /** Episodic memory event */
 interface EpisodicEvent {
+    /**
+     * Optional caller-provided event ID. When omitted, a monotonic id is
+     * generated. `string | number` is accepted as a convenience; ids must be
+     * non-negative integers within the JS safe-integer range (0..2^53-1) because
+     * the REST wire transmits them as JSON numbers, and out-of-range ids are
+     * rejected (not silently truncated).
+     */
+    id?: string | number;
     /** Event type identifier */
     eventType: string;
+    /**
+     * Event timestamp as a NUMERIC unix time in **seconds**.
+     *
+     * Mirrors the core episodic store, which persists a numeric `timestamp`
+     * that feeds `recent(since)` / `older_than(before)`. When omitted it
+     * defaults to the current unix-seconds value (`floor(Date.now() / 1000)`).
+     */
+    timestamp?: number;
     /** Event data */
     data: Record<string, unknown>;
     /** Embedding vector */
@@ -605,6 +671,14 @@ interface EpisodicEvent {
 }
 /** Procedural memory pattern */
 interface ProceduralPattern {
+    /**
+     * Optional caller-provided pattern ID. When omitted, a monotonic id is
+     * generated. `string | number` is accepted as a convenience; ids must be
+     * non-negative integers within the JS safe-integer range (0..2^53-1) because
+     * the REST wire transmits them as JSON numbers, and out-of-range ids are
+     * rejected (not silently truncated).
+     */
+    id?: string | number;
     /** Procedure name */
     name: string;
     /** Ordered steps */
@@ -620,6 +694,15 @@ interface ProceduralPattern {
     /** Optional metadata */
     metadata?: Record<string, unknown>;
 }
+/** A single episodic event recalled by timestamp. */
+interface EpisodicRecord {
+    /** Point id as a string (u64 precision preserved). */
+    id: string;
+    /** Numeric unix-seconds timestamp. */
+    timestamp: number;
+    /** Full point payload (includes `event_type`, caller data/metadata). */
+    payload: Record<string, unknown>;
+}
 /** Agent memory configuration */
 interface AgentMemoryConfig {
     /** Embedding dimension (default: 384) */
@@ -939,11 +1022,17 @@ declare const REST_CAPABILITIES: Readonly<CapabilityMap>;
  * Capability map for the WASM backend.
  *
  * The WASM build ships a focused subset: the dense / text / hybrid /
- * multi-query search paths plus VelesQL execution. Everything that
- * relies on persistent on-disk structures (secondary indexes, graph,
- * streaming, PQ training, agent memory, introspection, sparse
- * inverted index) is explicitly `false`. See `backends/wasm-stubs.ts`
- * for the exact set of `wasmNotSupported()` throw sites.
+ * multi-query search paths. Everything that relies on persistent
+ * on-disk structures (secondary indexes, graph, streaming, PQ
+ * training, agent memory, introspection, sparse inverted index) is
+ * explicitly `false`. See `backends/wasm-stubs.ts` for the exact set
+ * of `wasmNotSupported()` throw sites.
+ *
+ * `velesqlQuery` is `false`: `query()` only executes pure top-k NEAR
+ * statements (`SELECT * FROM <collection> WHERE vector NEAR $param
+ * [LIMIT n]`) and throws `NOT_SUPPORTED` for any other VelesQL clause
+ * (WHERE predicates, JOIN, GROUP BY, MATCH, set operations, FUSION),
+ * so full VelesQL is not advertised.
  */
 declare const WASM_CAPABILITIES: Readonly<CapabilityMap>;
 
@@ -1104,13 +1193,6 @@ interface StreamUpsertResponse {
     networkErrors: number;
 }
 
-/**
- * VelesDB TypeScript SDK - Backend Interface
- *
- * The `IVelesDBBackend` interface that all backends must implement.
- * @packageDocumentation
- */
-
 /** Backend interface that all backends must implement */
 interface IVelesDBBackend {
     /** Initialize the backend */
@@ -1239,12 +1321,28 @@ interface IVelesDBBackend {
     storeSemanticFact(collection: string, entry: SemanticEntry): Promise<void>;
     /** Search semantic memory */
     searchSemanticMemory(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Record an episodic event. Returns the generated point ID. */
-    recordEpisodicEvent(collection: string, event: EpisodicEvent): Promise<number>;
-    /** Recall episodic events */
+    /**
+     * Record an episodic event. Returns the point ID as a string (u64
+     * precision preserved).
+     */
+    recordEpisodicEvent(collection: string, event: EpisodicEvent): Promise<string>;
+    /** Recall episodic events by vector similarity. */
     recallEpisodicEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Store a procedural pattern. Returns the generated point ID. */
-    storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<number>;
+    /**
+     * Recall episodic events most-recent-first, optionally bounded below by
+     * `since` (inclusive unix-seconds). Mirrors core `episodic.recent(since)`.
+     */
+    recallRecentEvents(collection: string, since?: number): Promise<EpisodicRecord[]>;
+    /**
+     * Recall episodic events strictly older than `before` (unix-seconds),
+     * most-recent-first. Mirrors core `episodic.older_than(before)`.
+     */
+    recallOlderThanEvents(collection: string, before: number): Promise<EpisodicRecord[]>;
+    /**
+     * Store a procedural pattern. Returns the point ID as a string (u64
+     * precision preserved).
+     */
+    storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<string>;
     /** Match procedural patterns */
     matchProceduralPatterns(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
     /** Rebuild a collection's HNSW index (compacts tombstones). */
@@ -1271,6 +1369,14 @@ interface IVelesDBBackend {
     upsertNodePayload(collection: string, nodeId: number, payload: Record<string, unknown>): Promise<void>;
     /** Vector similarity search scoped to graph nodes only. */
     graphSearch(collection: string, request: GraphSearchRequest): Promise<GraphSearchResponse>;
+    /** Create a typed relation edge between two points. Returns the allocated edge ID. */
+    relate(collection: string, req: RelateRequest): Promise<RelateResponse>;
+    /** Remove a relation edge by ID. Returns `true` if removed. */
+    unrelate(collection: string, edgeId: GraphNodeId): Promise<boolean>;
+    /** List outgoing relation edges for a point. */
+    getRelations(collection: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    /** Durably set (or refresh) the TTL of a point. */
+    setTtlDurable(collection: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
 }
 
 /**
@@ -1328,16 +1434,31 @@ declare class AgentMemoryClient {
     storeFact(collection: string, entry: SemanticEntry): Promise<void>;
     /** Search semantic memory */
     searchFacts(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Record an episodic event. Returns the generated point ID. */
-    recordEvent(collection: string, event: EpisodicEvent): Promise<number>;
-    /** Recall episodic events */
+    /** Record an episodic event. Returns the point ID (string, u64-safe). */
+    recordEvent(collection: string, event: EpisodicEvent): Promise<string>;
+    /** Recall episodic events by vector similarity. */
     recallEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Store a procedural pattern. Returns the generated point ID. */
-    learnProcedure(collection: string, pattern: ProceduralPattern): Promise<number>;
+    /**
+     * Recall episodic events most-recent-first, optionally bounded below by
+     * `since` (inclusive unix-seconds). Mirrors core `episodic.recent(since)`.
+     */
+    recallRecent(collection: string, since?: number): Promise<EpisodicRecord[]>;
+    /**
+     * Recall episodic events strictly older than `before` (unix-seconds),
+     * most-recent-first. Mirrors core `episodic.older_than(before)`.
+     */
+    recallOlderThan(collection: string, before: number): Promise<EpisodicRecord[]>;
+    /** Store a procedural pattern. Returns the point ID (string, u64-safe). */
+    learnProcedure(collection: string, pattern: ProceduralPattern): Promise<string>;
     /** Match procedural patterns */
     recallProcedures(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Delete a memory entry (fact, event, or procedure) by its point ID. */
-    deleteMemory(collection: string, id: number): Promise<boolean>;
+    /**
+     * Delete a memory entry (fact, event, or procedure) by its point ID.
+     *
+     * Accepts the `string` ids returned by `recordEvent` / `learnProcedure`
+     * (u64-safe decimal strings) as well as numeric ids.
+     */
+    deleteMemory(collection: string, id: string | number): Promise<boolean>;
 }
 
 /**
@@ -1436,6 +1557,10 @@ declare class VelesDB {
     getNodePayload(collection: string, nodeId: number): Promise<NodePayloadResponse>;
     upsertNodePayload(collection: string, nodeId: number, payload: Record<string, unknown>): Promise<void>;
     graphSearch(collection: string, request: GraphSearchRequest): Promise<GraphSearchResponse>;
+    relate(collection: string, req: RelateRequest): Promise<RelateResponse>;
+    unrelate(collection: string, edgeId: GraphNodeId): Promise<boolean>;
+    getRelations(collection: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    setTtlDurable(collection: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
     capabilities(): Readonly<CapabilityMap>;
     get backendType(): string;
     agentMemory(config?: AgentMemoryConfig): AgentMemoryClient;
@@ -1514,9 +1639,11 @@ declare class WasmBackend implements IVelesDBBackend {
     }>>;
     storeSemanticFact(c: string, e: SemanticEntry): Promise<void>;
     searchSemanticMemory(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<number>;
+    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<string>;
     recallEpisodicEvents(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<number>;
+    recallRecentEvents(c: string, since?: number): Promise<EpisodicRecord[]>;
+    recallOlderThanEvents(c: string, before: number): Promise<EpisodicRecord[]>;
+    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<string>;
     matchProceduralPatterns(c: string, e: number[], k?: number): Promise<SearchResult[]>;
     rebuildIndex(c: string): Promise<RebuildIndexResponse>;
     getGuardrails(): Promise<GuardRailsConfigResponse>;
@@ -1531,6 +1658,10 @@ declare class WasmBackend implements IVelesDBBackend {
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
     sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
+    relate(c: string, req: RelateRequest): Promise<RelateResponse>;
+    unrelate(c: string, edgeId: GraphNodeId): Promise<boolean>;
+    getRelations(c: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    setTtlDurable(c: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
 }
 
 /**
@@ -1569,6 +1700,10 @@ declare class RestBackend implements IVelesDBBackend {
     getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
+    relate(c: string, req: RelateRequest): Promise<RelateResponse>;
+    unrelate(c: string, edgeId: GraphNodeId): Promise<boolean>;
+    getRelations(c: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    setTtlDurable(c: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
     search(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<SearchResult[]>;
     searchBatch(c: string, s: Array<{
         vector: number[] | Float32Array;
@@ -1615,9 +1750,11 @@ declare class RestBackend implements IVelesDBBackend {
     streamUpsertPoints(c: string, d: VectorDocument[]): Promise<StreamUpsertResponse>;
     storeSemanticFact(c: string, e: SemanticEntry): Promise<void>;
     searchSemanticMemory(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<number>;
+    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<string>;
     recallEpisodicEvents(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<number>;
+    recallRecentEvents(c: string, since?: number): Promise<EpisodicRecord[]>;
+    recallOlderThanEvents(c: string, before: number): Promise<EpisodicRecord[]>;
+    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<string>;
     matchProceduralPatterns(c: string, e: number[], k?: number): Promise<SearchResult[]>;
 }
 
@@ -2109,4 +2246,4 @@ declare class OpenAIEmbedder implements Embedder {
     embed(texts: string[]): Promise<number[][]>;
 }
 
-export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type Embedder, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, type GraphNodeId, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OpenAIEmbedder, type OpenAIEmbedderOptions, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };
+export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type Embedder, type EpisodicEvent, type EpisodicRecord, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, type GraphNodeId, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OpenAIEmbedder, type OpenAIEmbedderOptions, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, type RelateRequest, type RelateResponse, type RelationEdge, type RelationsResponse, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };