@surrealdb/memory 1.0.0-alpha.10 → 1.0.0-alpha.11

package/dist/memory.cjs

@@ -355,7 +355,7 @@ var Documents = class {
 
 //#endregion
 //#region src/components/entities.ts
-/** Entity records, attributes, relations, and attribute history. */
+/** Entity records, attributes, relations, name search, and attribute history. */
 var Entities = class {
 	transport;
 	contextId;
@@ -366,6 +366,9 @@ var Entities = class {
 	get base() {
 		return `${getContextApiPrefix(this.contextId)}/entities`;
 	}
+	entityPath(entityType, name) {
+		return `${this.base}/${encodePathSegment(entityType)}/${encodePathSegment(name)}`;
+	}
 	/** Lists one page of entities, optionally filtered by type. */
 	async list(options) {
 		const query = {};
@@ -396,22 +399,253 @@ var Entities = class {
 		});
 		return page.page.totalSize ?? page.entities.length;
 	}
-	/** Fetches a single entity by type and name, with its attributes and relations. */
-	async get(entityType, name) {
-		const path = `${this.base}/${encodePathSegment(entityType)}/${encodePathSegment(name)}`;
-		const body = await this.transport.requestJson("GET", path);
+	/**
+	* Searches entities by name, best match first (`GET /entities/search`).
+	*
+	* Lexical and deterministic: no model and no vector index in the path, so
+	* an identical query returns identical rows in an identical order. An exact
+	* match on the normalised identity name scores `1.0` and everything else
+	* strictly below it, corpus-independently — a score means the same thing in
+	* a context of ten entities and one of ten million.
+	*
+	* Each match carries its own `factCount` and a `distinguisher` drawn from
+	* its highest-importance facts, so two same-named candidates can be told
+	* apart without a request per candidate.
+	*
+	* This is a ranked head, not a walk: it is bounded by `limit` and offers no
+	* cursor. Use {@link Entities.list} to enumerate the collection.
+	*/
+	async search(query, options) {
+		const params = { q: query };
+		if (options?.type !== void 0) params.type = options.type;
+		if (options?.limit !== void 0) params.limit = options.limit;
+		const body = await this.transport.requestJson("GET", `${this.base}/search`, { query: params });
+		return body.matches;
+	}
+	/**
+	* The entities worth starting from (`GET /entities/top`).
+	*
+	* `coverage` (the default) is most-known-about, the one ordering the entity
+	* listing cannot express. It is exact rather than approximated, and costs
+	* an aggregate pass per fact family: merging three separately-truncated
+	* top-lists would mis-rank an entity that leads on relations and trails on
+	* attributes. Prefer `importance` or `recency`, both index-served
+	* single-table reads, where the ranking need not be exact.
+	*
+	* A ranked head, like {@link Entities.search}: bounded, with no cursor.
+	*/
+	async top(options) {
+		const params = {};
+		if (options?.by !== void 0) params.by = options.by;
+		if (options?.type !== void 0) params.type = options.type;
+		if (options?.limit !== void 0) params.limit = options.limit;
+		const body = await this.transport.requestJson("GET", `${this.base}/top`, { query: params });
+		return body.entities;
+	}
+	/**
+	* Fetches a single entity with a bounded head of its attributes and
+	* relations, newest first.
+	*
+	* Both fact sections are bounded by `limit` and report whether they were
+	* cut in `truncated`. To read one in full, walk its own collection: the
+	* attributes through `/attributes?entity=`, and the relations through
+	* **both** `/relations?src=` and `/relations?dst=`, because the head
+	* carries edges in either direction and one filter alone reproduces half of
+	* it. All of them page by cursor in this same order, so the head is a
+	* genuine prefix of the walk.
+	*/
+	async get(entityType, name, options) {
+		const query = {};
+		if (options?.limit !== void 0) query.limit = options.limit;
+		addTemporalParams(query, options);
+		const body = await this.transport.requestJson("GET", this.entityPath(entityType, name), { query });
+		return body;
+	}
+	/**
+	* One hop out from an entity (`GET /entities/{type}/{name}/neighbourhood`).
+	*
+	* Each neighbour carries its own `factCount`, so a relation chip is
+	* navigable rather than decorative — without it a caller needs one request
+	* per chip. Paginated over the edge's own `(createdAt, id)`, never the fact
+	* count, which moves under ingest.
+	*
+	* `limit` is capped below the general list limit because each row costs
+	* three correlated counts.
+	*/
+	async neighbours(entityType, name, options) {
+		const query = {};
+		if (options?.minFacts !== void 0) query.minFacts = options.minFacts;
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.entityPath(entityType, name)}/neighbourhood`, { query });
+		return body;
+	}
+	/** Every neighbour of an entity, following cursors to exhaustion. */
+	async allNeighbours(entityType, name, options) {
+		return collectPages((cursor) => this.neighbours(entityType, name, {
+			minFacts: options?.minFacts,
+			limit: options?.limit,
+			cursor
+		}), "neighbours", options?.max);
+	}
+	/**
+	* One page of every key's supersession chain for an entity, newest first
+	* (`GET /entities/{type}/{name}/history`).
+	*
+	* Answers what changed about the subject. The per-key sibling,
+	* {@link Entities.history}, answers how one value changed, and this cannot
+	* be composed from it without a request per key. Superseded rows are
+	* included — the chain is the point.
+	*/
+	async changes(entityType, name, options) {
+		const query = {};
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.entityPath(entityType, name)}/history`, { query });
 		return body;
 	}
+	/**
+	* The subject's whole change history, following cursors to exhaustion.
+	*
+	* Unbounded by construction: an attribute revised on every sync has an
+	* unbounded chain. Pass `max` to stop the walk once that many rows are in
+	* hand.
+	*/
+	async allChanges(entityType, name, options) {
+		return collectPages((cursor) => this.changes(entityType, name, {
+			limit: options?.limit,
+			cursor
+		}), "history", options?.max);
+	}
 	/** Returns the supersession history for one attribute key. */
 	async history(entityType, name, key) {
-		const path = `${this.base}/${encodePathSegment(entityType)}/${encodePathSegment(name)}/history/${encodePathSegment(key)}`;
+		const path = `${this.entityPath(entityType, name)}/history/${encodePathSegment(key)}`;
 		const body = await this.transport.requestJson("GET", path);
 		return body.history;
 	}
 	/** Soft-deletes an entity (sets valid-until). */
 	async delete(entityType, name) {
-		const path = `${this.base}/${encodePathSegment(entityType)}/${encodePathSegment(name)}`;
-		await this.transport.requestJson("DELETE", path);
+		await this.transport.requestJson("DELETE", this.entityPath(entityType, name));
+	}
+};
+/** Copies the temporal filters a caller supplied into a query object. */
+function addTemporalParams(query, options) {
+	if (options?.asOf !== void 0) query.asOf = options.asOf;
+	if (options?.atInstant !== void 0) query.atInstant = options.atInstant;
+	if (options?.validFrom !== void 0) query.validFrom = options.validFrom;
+	if (options?.validUntil !== void 0) query.validUntil = options.validUntil;
+}
+
+//#endregion
+//#region src/components/facts.ts
+/**
+* The fact collections, in the order the bounded reads present them.
+*
+* Every surface that returns a bounded head of facts — `entities.get`, the
+* `/inspect` entity ref, and each section of `client.lookup` — reports
+* `truncated` and points here for the rest. These listings page by cursor in
+* the same newest-first order, so a truncated head is a genuine prefix of the
+* walk rather than a separate ranking.
+*/
+var Facts = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return getContextApiPrefix(this.contextId);
+	}
+	/**
+	* Lists one page of live attributes, newest first (`GET /attributes`).
+	*
+	* Live means not superseded and inside its validity window. Superseded
+	* values are reachable through the entity history endpoints.
+	*/
+	async attributes(options) {
+		const query = {};
+		if (options?.entity !== void 0) query.entity = options.entity;
+		if (options?.key !== void 0) query.key = options.key;
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.base}/attributes`, { query });
+		return body;
+	}
+	/** Every matching attribute, following cursors to exhaustion. */
+	async allAttributes(options) {
+		return collectPages((cursor) => this.attributes({
+			...options,
+			cursor
+		}), "attributes", options?.max);
+	}
+	/**
+	* Lists one page of live relation edges, newest first (`GET /relations`).
+	*
+	* `src` and `dst` filter one direction each. An entity's whole edge set is
+	* the union of both walks — see {@link Facts.allEdgesOf}, which does that
+	* for you.
+	*/
+	async relations(options) {
+		const query = {};
+		if (options?.src !== void 0) query.src = options.src;
+		if (options?.dst !== void 0) query.dst = options.dst;
+		if (options?.label !== void 0) query.label = options.label;
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.base}/relations`, { query });
+		return body;
+	}
+	/** Every matching relation, following cursors to exhaustion. */
+	async allRelations(options) {
+		return collectPages((cursor) => this.relations({
+			...options,
+			cursor
+		}), "relations", options?.max);
+	}
+	/**
+	* Every edge touching an entity, in both directions.
+	*
+	* This is what a truncated relation section points at. `src` and `dst` are
+	* separate filters, so either walk alone reproduces half the set that
+	* `entities.get` and `lookup` return; this runs both and concatenates them,
+	* outbound first.
+	*
+	* @param entity The subject, as `<type>/<name>`.
+	*/
+	async allEdgesOf(entity, options) {
+		const [outbound, inbound] = await Promise.all([this.allRelations({
+			src: entity,
+			label: options?.label,
+			limit: options?.limit
+		}), this.allRelations({
+			dst: entity,
+			label: options?.label,
+			limit: options?.limit
+		})]);
+		return [...outbound, ...inbound];
+	}
+	/**
+	* Lists one page of live actions — dated events — newest first by write
+	* time (`GET /actions`).
+	*
+	* Ordered on write time rather than event time because event time is
+	* revisable, and a revision under an event-time ordering would move a row
+	* across page boundaries mid-walk. `since` and `until` still bound the
+	* event time.
+	*/
+	async actions(options) {
+		const query = {};
+		if (options?.actor !== void 0) query.actor = options.actor;
+		if (options?.verb !== void 0) query.verb = options.verb;
+		if (options?.since !== void 0) query.since = options.since;
+		if (options?.until !== void 0) query.until = options.until;
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.base}/actions`, { query });
+		return body;
+	}
+	/** Every matching action, following cursors to exhaustion. */
+	async allActions(options) {
+		return collectPages((cursor) => this.actions({
+			...options,
+			cursor
+		}), "actions", options?.max);
 	}
 };
 
@@ -735,6 +969,84 @@ var Traces = class {
 	}
 };
 
+//#endregion
+//#region src/components/uncertainty.ts
+/**
+* The things this context is unsure about, and the one write that settles one.
+*
+* `/state` collapses these to `{about, reason}`, which is enough to say
+* something is unresolved and not enough to act on it. These rows carry the
+* subject, so a flag can be linked to the entity it is about and settled.
+*/
+var Uncertainty = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/uncertainty`;
+	}
+	/** Lists one page of uncertainty flags, newest first (`GET /uncertainty`). */
+	async list(options) {
+		const query = {};
+		if (options?.entity !== void 0) query.entity = options.entity;
+		if (options?.resolved !== void 0) query.resolved = options.resolved;
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/** Every matching flag, following cursors to exhaustion. */
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			...options,
+			cursor
+		}), "unknowns");
+	}
+	/**
+	* How many flags match, without fetching them.
+	*
+	* Asks for a single row with `count: true`, so the total is the only thing
+	* paid for beyond one page bound.
+	*/
+	async count(options) {
+		const page = await this.list({
+			...options,
+			limit: 1,
+			count: true
+		});
+		return page.page.totalSize ?? page.unknowns.length;
+	}
+	/**
+	* Settles a flag by accepting one value
+	* (`POST /uncertainty/{id}/resolve`). Requires the `memory:write` grant.
+	*
+	* One call, three effects: the flag is claimed, `acceptedValue` is written
+	* through the reconciler at the upsert trust prior, and the values it beats
+	* are retired. The accepted value lands at the flag's own scope rather than
+	* the caller's write anchors, because it has to replace the contenders
+	* where they live.
+	*
+	* Settlement converges on retry rather than being transactional: a failure
+	* after the value is written hands the flag back and reports it, and
+	* repeating the call dedups the value and finishes the retirement.
+	*
+	* Only the two reconciler-raised kinds — a cross-provenance contradiction
+	* and a confidence-floor hold — record the entity and key a written value
+	* would need. A flag without one is refused with a `422`, so check
+	* `resolvable` on the row before offering the action; it also accounts for
+	* an already-settled flag and for one whose scope reaches beyond the
+	* calling key's write region.
+	*/
+	async resolve(uncertaintyId, acceptedValue, options) {
+		const payload = { acceptedValue };
+		if (options?.note !== void 0) payload.note = options.note;
+		const body = await this.transport.requestJson("POST", `${this.base}/${encodePathSegment(uncertaintyId)}/resolve`, { body: payload });
+		return body.uncertainty;
+	}
+};
+
 //#endregion
 //#region src/errors.ts
 /** Base class for all Agent Memory client errors. */
@@ -1159,7 +1471,7 @@ var Transport = class Transport {
 		const headers = {
 			Accept: accept,
 			Authorization: `Bearer ${this.apiKey}`,
-			"User-Agent": `surrealdb-memory-js/1.0.0-alpha.10`
+			"User-Agent": `surrealdb-memory-js/1.0.0-alpha.11`
 		};
 		if (this.onBehalfOf) headers["X-Spectron-On-Behalf-Of"] = this.onBehalfOf;
 		return headers;
@@ -1369,8 +1681,12 @@ var AgentMemory = class AgentMemory {
 	contextId;
 	/** Document ingestion, retrieval, corpus search, and the keyword graph. */
 	documents;
-	/** Entity records, attributes, relations, and attribute history. */
+	/** Entity records, attributes, relations, name search, and attribute history. */
 	entities;
+	/** The attribute, relation, and action collections a bounded head points at. */
+	facts;
+	/** Things the context is unsure about, and the write that settles one. */
+	uncertainty;
 	/** Conversation sessions for this context. */
 	sessions;
 	/** Expiry and decay sweeps. */
@@ -1396,6 +1712,8 @@ var AgentMemory = class AgentMemory {
 		const components = AgentMemory.buildComponents(this.transport, this.contextId);
 		this.documents = components.documents;
 		this.entities = components.entities;
+		this.facts = components.facts;
+		this.uncertainty = components.uncertainty;
 		this.sessions = components.sessions;
 		this.lifecycle = components.lifecycle;
 		this.traces = components.traces;
@@ -1407,6 +1725,8 @@ var AgentMemory = class AgentMemory {
 		return {
 			documents: new Documents(transport, contextId),
 			entities: new Entities(transport, contextId),
+			facts: new Facts(transport, contextId),
+			uncertainty: new Uncertainty(transport, contextId),
 			sessions: new Sessions(transport, contextId),
 			lifecycle: new Lifecycle(transport, contextId),
 			traces: new Traces(transport, contextId),
@@ -1522,6 +1842,46 @@ var AgentMemory = class AgentMemory {
 		const body = await this.transport.requestJson("POST", `${this.base}/chat`, { body: payload });
 		return body;
 	}
+	/**
+	* What this context knows about a subject, in one round trip
+	* (`POST /lookup`).
+	*
+	* Everything returned is a stored row: nothing is generated, nothing is
+	* summarised by a model, and an identical query returns an identical
+	* answer. Branch on `resolution.kind` — `entity`, `topic`, `ambiguous`,
+	* `empty` — rather than inferring which case you got from an array length.
+	*
+	* This is a composite aggregate like {@link AgentMemory.state}, not a
+	* collection: every section is bounded and reports `truncated`, and none of
+	* them page. To read a section in full, walk its own collection endpoint —
+	* facts through `/attributes?entity=`, relations through **both**
+	* `/relations?src=` and `/relations?dst=`, events through
+	* `/actions?actor=`, passages through {@link AgentMemory.recall}, and
+	* unknowns through {@link AgentMemory.uncertainty}. Note that `facts` is
+	* ranked by importance while its collection pages in write order: the
+	* ranked head is a different question from the walk, not its first page.
+	*
+	* Facts carry their source, trust and confidence but not the quoted
+	* evidence text — a fact is one line until asked, and expanding one is a
+	* passage read.
+	*/
+	async lookup(query, options) {
+		const payload = { query };
+		addDefined(payload, "subject", options?.subject);
+		addDefined(payload, "entityType", options?.entityType);
+		addDefined(payload, "ambiguityMargin", options?.ambiguityMargin);
+		addDefined(payload, "include", options?.include);
+		addDefined(payload, "factLimit", options?.factLimit);
+		addDefined(payload, "relationLimit", options?.relationLimit);
+		addDefined(payload, "eventLimit", options?.eventLimit);
+		addDefined(payload, "passageLimit", options?.passageLimit);
+		addDefined(payload, "uncertaintyLimit", options?.uncertaintyLimit);
+		const body = await this.transport.requestJson("POST", `${this.base}/lookup`, {
+			body: payload,
+			idempotent: true
+		});
+		return body;
+	}
 	/** Retrieves LLM-facing context text for a query without a session (`POST /context`). */
 	async context(query, options) {
 		const payload = { query };
@@ -1529,6 +1889,7 @@ var AgentMemory = class AgentMemory {
 		addDefined(payload, "labels", options?.labels);
 		addDefined(payload, "lens", normaliseScope(options?.lens));
 		addDefined(payload, "scopeView", options?.scopeView);
+		addDefined(payload, "subject", options?.subject);
 		const body = await this.transport.requestJson("POST", `${this.base}/context`, {
 			body: payload,
 			idempotent: true
@@ -1607,11 +1968,13 @@ var AgentMemory = class AgentMemory {
 	* bounded by `limit` (default 100, max 500), and `truncated` reports which
 	* of them had more rows.
 	*
-	* Four of those tables have their own collection endpoint to enumerate them
+	* Five of those tables have their own collection endpoint to enumerate them
 	* completely — entities (see {@link AgentMemory.entities}), attributes,
-	* relations, and actions. The remaining two, `instructions` and `unknowns`,
-	* have no such route: when `truncated` flags either, the omitted rows cannot
-	* be recovered other than by raising `limit`.
+	* relations, actions, and `unknowns` (see
+	* {@link AgentMemory.uncertainty}, which also returns the subject each flag
+	* is about, where this snapshot collapses it to `{about, reason}`). Only
+	* `instructions` has no such route: when `truncated` flags it, the omitted
+	* rows cannot be recovered other than by raising `limit`.
 	*/
 	async state(options) {
 		const query = {};
@@ -1681,6 +2044,36 @@ const ScopeView = {
 	merged: "merged",
 	crossTeam: "crossTeam"
 };
+/**
+* Ordering for the ranked entity head at `/entities/top`.
+*
+* `coverage` is most-known-about and the one ordering the entity listing cannot
+* express, but it costs an exact aggregate pass per fact family. `importance`
+* and `recency` are index-served single-table reads: prefer them where the
+* ranking need not be exact.
+*/
+const EntityRanking = {
+	coverage: "coverage",
+	importance: "importance",
+	recency: "recency"
+};
+/**
+* The sections `/lookup` can be asked to fill.
+*
+* Everything but `passages` is on by default, because `passages` costs a
+* retrieval pass. An omitted section comes back empty with `truncated` false:
+* it was declined, not cut short. Unknown names are ignored by the server.
+*
+* `entities` is absent deliberately — it is not selectable. The server fills it
+* for a topic answer and leaves it empty for an entity one.
+*/
+const LookupSection = {
+	facts: "facts",
+	relations: "relations",
+	events: "events",
+	passages: "passages",
+	uncertainty: "uncertainty"
+};
 /** Document pipeline status values returned by the API. */
 const DocumentStatus = {
 	queued: "queued",
@@ -1704,9 +2097,12 @@ exports.DocumentKeywords = DocumentKeywords;
 exports.DocumentStatus = DocumentStatus;
 exports.Documents = Documents;
 exports.Entities = Entities;
+exports.EntityRanking = EntityRanking;
+exports.Facts = Facts;
 exports.InferMode = InferMode;
 exports.Keys = Keys;
 exports.Lifecycle = Lifecycle;
+exports.LookupSection = LookupSection;
 exports.MemoryCategory = MemoryCategory;
 exports.NotFoundError = NotFoundError;
 exports.Principals = Principals;
@@ -1722,6 +2118,7 @@ exports.StreamError = StreamError;
 exports.Traces = Traces;
 exports.Transport = Transport;
 exports.TurnRole = TurnRole;
+exports.Uncertainty = Uncertainty;
 exports.ValidationError = ValidationError;
 exports.Verb = Verb;
 exports.addPageParams = addPageParams;