@surrealdb/memory 1.0.0-alpha.9

package/dist/memory.cjs

@@ -0,0 +1,1672 @@
+
+//#region src/file-body.ts
+/**
+* Normalises a file-like input to a `Blob` for multipart uploads.
+* `ReadableStream` inputs are buffered in full (suitable for typical document sizes).
+*/
+async function agentMemoryFileInputToBlob(input, mimeType) {
+	if (typeof File !== "undefined" && input instanceof File) return input;
+	if (input instanceof Blob) return input;
+	if (input instanceof ArrayBuffer) return new Blob([input], { type: mimeType });
+	if (ArrayBuffer.isView(input)) return new Blob([input], { type: mimeType });
+	const stream = input;
+	const reader = stream.getReader();
+	const chunks = [];
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (value) chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const total = chunks.reduce((a, c) => a + c.byteLength, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const c of chunks) {
+		out.set(c, offset);
+		offset += c.byteLength;
+	}
+	return new Blob([out], { type: mimeType });
+}
+
+//#endregion
+//#region src/pagination.ts
+/**
+* Copies the pagination parameters a caller supplied into a query object,
+* leaving absent ones absent so the server applies its own defaults.
+*/
+function addPageParams(query, options) {
+	if (options?.limit !== void 0) query.limit = options.limit;
+	if (options?.cursor !== void 0) query.cursor = options.cursor;
+	if (options?.count !== void 0) query.count = options.count;
+}
+/**
+* Yields every page of a listing, following `page.nextCursor` to exhaustion.
+*
+* `fetchPage` receives the cursor to resume from — `undefined` on the first
+* call — and must pass it through to the underlying request unchanged.
+*/
+async function* walkPages(fetchPage, collection) {
+	let cursor;
+	const seen = /* @__PURE__ */ new Set();
+	for (;;) {
+		const response = await fetchPage(cursor);
+		if (response === null || response === void 0) return;
+		yield response;
+		const next = response.page?.nextCursor;
+		if (next === void 0 || next === null || next === "") return;
+		if (seen.has(next)) throw new Error(`Agent Memory returned a repeated pagination cursor while walking \`${collection}\`; the page walk cannot advance.`);
+		seen.add(next);
+		cursor = next;
+	}
+}
+/**
+* Follows a listing's cursors to exhaustion and returns every row.
+*
+* This is what the Agent Memory CLI does for verbs that print a whole set, and
+* what a caller wants when the collection is a tree or a filter source rather
+* than a screenful. Without `max` it is an unbounded read by construction:
+* prefer the page-at-a-time `list` for anything user-facing and large.
+*
+* `max` stops the walk once that many rows are in hand, so a caller that only
+* ever renders the first N does not pay for the pages beyond them. The result
+* can still overshoot `max` by up to one page, because pages arrive whole.
+*/
+async function collectPages(fetchPage, collection, max) {
+	const rows = [];
+	for await (const page of walkPages(fetchPage, collection)) {
+		const items = page[collection];
+		if (items) rows.push(...items);
+		if (max !== void 0 && rows.length >= max) break;
+	}
+	return rows;
+}
+
+//#endregion
+//#region src/paths.ts
+/**
+* URL-encodes a single path segment (e.g. context id, entity name).
+* @param value Raw segment value.
+*/
+function encodePathSegment(value) {
+	return encodeURIComponent(value);
+}
+/**
+* Returns the API path prefix for an Agent Memory context: `/api/v1/{contextId}`.
+* @param contextId Context identifier.
+*/
+function getContextApiPrefix(contextId) {
+	return `/api/v1/${encodePathSegment(contextId)}`;
+}
+
+//#endregion
+//#region src/scope.ts
+/**
+* Normalises a {@link Scope} input to the wire `ScopeSets` (a DNF selector,
+* `string[][]`: an OR of clauses, each clause an AND of `key/value` slash-paths).
+*
+* A bare string becomes one single-path clause. Each element of the outer array
+* becomes a clause: a string element is a one-path clause, an array element is an
+* AND clause of its paths. Within each clause empty strings are dropped and paths
+* are de-duplicated preserving first-seen order; a clause that ends up empty is
+* dropped (empty clauses are rejected on the wire).
+*
+* @param scope Scope input in any accepted shape.
+* @returns The normalised DNF selector, or `undefined` when no non-empty clause
+*   remains (so callers can omit the field entirely and use the key's default
+*   write region).
+*/
+function normaliseScope(scope) {
+	if (scope === void 0 || scope === null) return void 0;
+	const clauses = typeof scope === "string" ? [scope] : scope;
+	const out = [];
+	for (const clause of clauses) {
+		const paths = typeof clause === "string" ? [clause] : clause;
+		const deduped = [...new Set(paths.filter((p) => p.length > 0))];
+		if (deduped.length > 0) out.push(deduped);
+	}
+	return out.length > 0 ? out : void 0;
+}
+
+//#endregion
+//#region src/components/documents.ts
+/**
+* Copies the deprecated offset parameters into a query object. Kept separate
+* from {@link addPageParams} so the two never merge into one option bag: the
+* server rejects `cursor` sent together with `page`.
+*/
+function addOffsetParams(query, options) {
+	if (options?.page !== void 0) query.page = options.page;
+	if (options?.pageSize !== void 0) query.pageSize = options.pageSize;
+}
+async function buildUploadForm(options) {
+	const blob = await agentMemoryFileInputToBlob(options.file, options.contentType);
+	const form = new FormData();
+	const metadata = {};
+	if (options.title !== void 0) metadata.title = options.title;
+	if (options.source !== void 0) metadata.source = options.source;
+	const scopes = normaliseScope(options.scopes);
+	if (scopes) metadata.scopes = scopes;
+	if (options.labels !== void 0) metadata.labels = options.labels;
+	if (Object.keys(metadata).length > 0) form.append("metadata", JSON.stringify(metadata));
+	const name = options.filename ?? (typeof File !== "undefined" && options.file instanceof File ? options.file.name : "upload");
+	form.append("file", blob, name);
+	return form;
+}
+/** The per-request transport options an upload forwards from its own options. */
+function sendOptions(options) {
+	return {
+		signal: options.signal,
+		onUploadProgress: options.onUploadProgress,
+		timeoutMs: options.timeoutMs
+	};
+}
+/** Keyword graph helpers for the document corpus. */
+var DocumentKeywords = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/documents/keywords`;
+	}
+	/** Lists one page of keywords with optional filters. */
+	async list(options) {
+		const query = {};
+		if (options?.q !== void 0) query.q = options.q;
+		if (options?.minDocumentCount !== void 0) query.minDocumentCount = options.minDocumentCount;
+		if (options?.sort !== void 0) query.sort = options.sort;
+		addPageParams(query, options);
+		addOffsetParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/** Every matching keyword, following cursors to exhaustion. */
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			...options,
+			cursor
+		}), "keywords");
+	}
+	/** Vector search over keyword embeddings. */
+	async search(options) {
+		const payload = { query: options.query };
+		if (options.k !== void 0) payload.k = options.k;
+		if (options.threshold !== void 0) payload.threshold = options.threshold;
+		const body = await this.transport.requestJson("POST", `${this.base}/search`, { body: payload });
+		return body;
+	}
+	/** Gets one keyword by its normalised form. */
+	async get(normalised) {
+		const body = await this.transport.requestJson("GET", `${this.base}/${encodePathSegment(normalised)}`);
+		return body;
+	}
+	/** Keywords linked to a document. */
+	async forDocument(documentId) {
+		const path = `${getContextApiPrefix(this.contextId)}/documents/${encodePathSegment(documentId)}/keywords`;
+		const body = await this.transport.requestJson("GET", path);
+		return body.keywords;
+	}
+};
+/** Document ingestion, retrieval, and corpus search. */
+var Documents = class {
+	transport;
+	contextId;
+	/** Keyword graph for the document corpus. */
+	keywords;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+		this.keywords = new DocumentKeywords(transport, contextId);
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/documents`;
+	}
+	/** Uploads a document (multipart). Returns the ingestion handle. */
+	async upload(options) {
+		const form = await buildUploadForm(options);
+		const body = await this.transport.requestJson("POST", this.base, {
+			body: form,
+			...sendOptions(options)
+		});
+		return body;
+	}
+	/** Reprocesses an existing document with replacement bytes (multipart). */
+	async reprocess(documentId, options) {
+		const form = await buildUploadForm(options);
+		const path = `${this.base}/${encodePathSegment(documentId)}`;
+		const body = await this.transport.requestJson("PUT", path, {
+			body: form,
+			...sendOptions(options)
+		});
+		if (body === null) return {
+			id: documentId,
+			status: "queued",
+			contentHash: "",
+			deduplicated: false
+		};
+		return body;
+	}
+	/** Metadata for one document. */
+	async get(documentId) {
+		const body = await this.transport.requestJson("GET", `${this.base}/${encodePathSegment(documentId)}`);
+		return body;
+	}
+	/** Raw document bytes. */
+	async raw(documentId, options) {
+		return this.transport.requestBytes("GET", `${this.base}/${encodePathSegment(documentId)}/raw`, options?.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : void 0);
+	}
+	/** Lists one page of a document's text chunks, in document order. */
+	async chunks(documentId, options) {
+		const query = {};
+		addPageParams(query, options);
+		addOffsetParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.base}/${encodePathSegment(documentId)}/chunks`, { query });
+		return body;
+	}
+	/**
+	* Every chunk of a document, following cursors to exhaustion.
+	*
+	* Reconstructing a document's text needs all of it, and `limit` is clamped
+	* at 500 server-side, so a single wide page silently truncates anything
+	* longer. Pass `max` when only the first N chunks are ever rendered, so a
+	* very long document does not cost a page fetch per hundred chunks.
+	*/
+	async allChunks(documentId, options) {
+		return collectPages((cursor) => this.chunks(documentId, {
+			limit: options?.limit,
+			cursor
+		}), "chunks", options?.max);
+	}
+	/** Lists one page of documents with optional filters. */
+	async list(options) {
+		const query = {};
+		if (options?.status !== void 0) query.status = options.status;
+		if (options?.mimeType !== void 0) query.mimeType = options.mimeType;
+		addPageParams(query, options);
+		addOffsetParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/** Every matching document, following cursors to exhaustion. */
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			...options,
+			cursor
+		}), "documents");
+	}
+	/**
+	* How many documents 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.documents.length;
+	}
+	/** Deletes a document. */
+	async delete(documentId) {
+		await this.transport.requestJson("DELETE", `${this.base}/${encodePathSegment(documentId)}`);
+	}
+	/** Hybrid / vector / BM25 / graph search over the document corpus. */
+	async query(options) {
+		const body = await this.transport.requestJson("POST", `${this.base}/query`, { body: options });
+		return body;
+	}
+	/** Recomputes derived document↔keyword and document↔document links. */
+	async recomputeLinks() {
+		const body = await this.transport.requestJson("POST", `${this.base}/recompute-links`, { body: {} });
+		return body;
+	}
+};
+
+//#endregion
+//#region src/components/entities.ts
+/** Entity records, attributes, relations, and attribute history. */
+var Entities = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/entities`;
+	}
+	/** Lists one page of entities, optionally filtered by type. */
+	async list(options) {
+		const query = {};
+		if (options?.type !== void 0) query.type = options.type;
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/** Every matching entity, following cursors to exhaustion. */
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			type: options?.type,
+			limit: options?.limit,
+			cursor
+		}), "entities");
+	}
+	/**
+	* How many entities 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({
+			type: options?.type,
+			limit: 1,
+			count: true
+		});
+		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);
+		return body;
+	}
+	/** 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 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);
+	}
+};
+
+//#endregion
+//#region src/components/keys.ts
+/** Self-service API keys for this context (requires the `manage` grant). */
+var Keys = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/keys`;
+	}
+	/**
+	* Mints a new key. The full secret is returned once in
+	* {@link MintedKeyJson.key} and cannot be retrieved again.
+	*/
+	async create(options) {
+		const payload = {};
+		if (options?.name !== void 0) payload.name = options.name;
+		if (options?.grants !== void 0) payload.grants = options.grants;
+		const body = await this.transport.requestJson("POST", this.base, {
+			body: Object.keys(payload).length > 0 ? payload : void 0,
+			query: { ttlSeconds: options?.ttlSeconds }
+		});
+		return body;
+	}
+	/**
+	* Lists one page of key metadata for the context (secrets are never
+	* included).
+	*
+	* `keys` can hold fewer than `limit` entries while `page.hasMore` is still
+	* true: a non-administrator sees only the key they authenticated with, so
+	* the page is bounded in the database and then filtered. Terminate a walk on
+	* `page.nextCursor`, never on a short page.
+	*/
+	async list(options) {
+		const query = {};
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/** Every key the caller can see, following cursors to exhaustion. */
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			limit: options?.limit,
+			cursor
+		}), "keys");
+	}
+	/** Revokes a key by name. */
+	async delete(keyName) {
+		await this.transport.requestJson("DELETE", `${this.base}/${encodePathSegment(keyName)}`);
+	}
+	/** Rotates a key, returning a fresh secret in {@link MintedKeyJson.key}. */
+	async rotate(keyName, options) {
+		const body = await this.transport.requestJson("POST", `${this.base}/${encodePathSegment(keyName)}/rotate`, { query: { ttlSeconds: options?.ttlSeconds } });
+		return body;
+	}
+};
+
+//#endregion
+//#region src/components/lifecycle.ts
+/** Operator lifecycle sweeps (expiry and decay). */
+var Lifecycle = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/lifecycle`;
+	}
+	/** Runs the context-category expiry sweep. Returns the number of affected rows. */
+	async expire() {
+		const body = await this.transport.requestJson("POST", `${this.base}/expire`, { body: {} });
+		return body;
+	}
+	/** Runs the importance decay sweep. Returns the number of affected rows. */
+	async decay() {
+		const body = await this.transport.requestJson("POST", `${this.base}/decay`, { body: {} });
+		return body;
+	}
+};
+
+//#endregion
+//#region src/components/principals.ts
+/** Principals and their scope grants (requires the `manage` grant). */
+var Principals = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/principals`;
+	}
+	/** Lists one page of the context's principals. */
+	async list(options) {
+		const query = {};
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/** Every principal in the context, following cursors to exhaustion. */
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			limit: options?.limit,
+			cursor
+		}), "principals");
+	}
+	/** Fetches a single principal and its declared grants. */
+	async get(principalId) {
+		const body = await this.transport.requestJson("GET", `${this.base}/${encodePathSegment(principalId)}`);
+		return body;
+	}
+	/** Resolves the verbs a principal effectively holds at a scope path. */
+	async effective(principalId, options) {
+		const query = { path: options.path };
+		if (options.asOf !== void 0) query.asOf = options.asOf;
+		const body = await this.transport.requestJson("GET", `${this.base}/${encodePathSegment(principalId)}/effective`, { query });
+		return body;
+	}
+	/** Grants a principal a set of verbs over a scope pattern. */
+	async grant(principalId, options) {
+		const body = await this.transport.requestJson("POST", `${this.base}/${encodePathSegment(principalId)}/grants`, { body: {
+			path: options.path,
+			verbs: options.verbs
+		} });
+		return body;
+	}
+	/** Revokes a set of verbs from a principal over a scope pattern. */
+	async revoke(principalId, options) {
+		const body = await this.transport.requestJson("DELETE", `${this.base}/${encodePathSegment(principalId)}/grants`, { body: {
+			path: options.path,
+			verbs: options.verbs
+		} });
+		return body;
+	}
+};
+
+//#endregion
+//#region src/components/scopes.ts
+/** The scope tree: register, list, delete, and forget scope subtrees. */
+var Scopes = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/scopes`;
+	}
+	/**
+	* Lists one page of registered scope nodes.
+	*
+	* `scopes` can hold fewer than `limit` entries while `page.hasMore` is still
+	* true: the server bounds the page in the database and then drops nodes the
+	* caller has no grant over, so invisible nodes consume page budget without
+	* appearing. Terminate a walk on `page.nextCursor`, never on a short page —
+	* or call {@link listAll}, which does it correctly.
+	*
+	* `page.totalSize` is always absent here: the endpoint takes no `count`, and
+	* a total counted before the visibility filter would not match what a walk
+	* returns anyway.
+	*/
+	async list(options) {
+		const query = {};
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/**
+	* Every registered scope node, following cursors to exhaustion.
+	*
+	* The scope tree is consumed whole — as a tree to render, or as the source
+	* for scope autocomplete and validation — so a single page of it is not
+	* useful.
+	*/
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			limit: options?.limit,
+			cursor
+		}), "scopes");
+	}
+	/** Registers a scope path with optional display metadata. */
+	async register(options) {
+		const payload = { path: options.path };
+		if (options.displayName !== void 0) payload.displayName = options.displayName;
+		if (options.description !== void 0) payload.description = options.description;
+		const body = await this.transport.requestJson("POST", this.base, { body: payload });
+		return body;
+	}
+	/** Deletes (tombstones) a scope node by path. */
+	async delete(path) {
+		await this.transport.requestJson("DELETE", this.base, { query: { path } });
+	}
+	/** Forgets (erases) a scope subtree. Returns the number of rows forgotten. */
+	async forget(options) {
+		const payload = {};
+		if (options?.path !== void 0) payload.path = options.path;
+		const body = await this.transport.requestJson("POST", `${this.base}/forget`, { body: payload });
+		return body;
+	}
+};
+
+//#endregion
+//#region src/components/sessions.ts
+/** An open conversation session within an Agent Memory context. */
+var Session = class {
+	transport;
+	contextId;
+	/** Session id (API path segment). */
+	id;
+	/** Creation timestamp. */
+	createdAt;
+	/** DNF scope selector the session writes to (outer OR, inner AND). */
+	scopes;
+	constructor(transport, contextId, info) {
+		this.transport = transport;
+		this.contextId = contextId;
+		this.id = info.id;
+		this.createdAt = info.createdAt;
+		this.scopes = info.scopes;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/sessions/${encodePathSegment(this.id)}`;
+	}
+	/** Deletes this session on the server. */
+	async close() {
+		await this.transport.requestJson("DELETE", this.base);
+	}
+	/** Lists one page of turns recorded against this session, oldest first. */
+	async turns(options) {
+		const query = {};
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.base}/turns`, { query });
+		return body;
+	}
+	/**
+	* Every turn in this session, following cursors to exhaustion.
+	*
+	* A transcript is read whole, so this is usually what a caller wants.
+	*/
+	async allTurns(options) {
+		return collectPages((cursor) => this.turns({
+			limit: options?.limit,
+			cursor
+		}), "turns");
+	}
+	/** Retrieves session-scoped LLM context text for a query. */
+	async context(options) {
+		const body = await this.transport.requestJson("POST", `${this.base}/context`, { body: { query: options.query } });
+		return body;
+	}
+};
+/** Creates and manages conversation sessions for a context. */
+var Sessions = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	/** Opens a new session with an optional DNF scope selector and metadata. */
+	async create(options) {
+		const base = `${getContextApiPrefix(this.contextId)}/sessions`;
+		const payload = {};
+		const scopes = normaliseScope(options?.scopes);
+		if (scopes) payload.scopes = scopes;
+		if (options?.metadata !== void 0) payload.metadata = options.metadata;
+		const body = await this.transport.requestJson("POST", base, { body: payload });
+		return new Session(this.transport, this.contextId, body);
+	}
+};
+
+//#endregion
+//#region src/components/traces.ts
+/** Retrieval decision traces for a context. */
+var Traces = class {
+	transport;
+	contextId;
+	constructor(transport, contextId) {
+		this.transport = transport;
+		this.contextId = contextId;
+	}
+	get base() {
+		return `${getContextApiPrefix(this.contextId)}/traces`;
+	}
+	/** Lists one page of trace records, newest first. */
+	async list(options) {
+		const query = {};
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", this.base, { query });
+		return body;
+	}
+	/** Every trace record, following cursors to exhaustion. */
+	async listAll(options) {
+		return collectPages((cursor) => this.list({
+			limit: options?.limit,
+			cursor
+		}), "traces");
+	}
+	/** Fetches one trace by id. */
+	async get(traceId) {
+		const body = await this.transport.requestJson("GET", `${this.base}/${encodePathSegment(traceId)}`);
+		return body;
+	}
+	/** Aggregate trace statistics over the recent window. */
+	async stats() {
+		const body = await this.transport.requestJson("GET", `${this.base}/stats`);
+		return body;
+	}
+};
+
+//#endregion
+//#region src/streaming.ts
+function frameToChunk(payload, done) {
+	const delta = typeof payload.delta === "string" ? payload.delta : typeof payload.token === "string" ? payload.token : "";
+	const traceId = typeof payload.traceId === "string" ? payload.traceId : typeof payload.trace_id === "string" ? payload.trace_id : void 0;
+	const sessionId = typeof payload.sessionId === "string" ? payload.sessionId : typeof payload.session_id === "string" ? payload.session_id : void 0;
+	return {
+		delta,
+		traceId,
+		sessionId,
+		done,
+		raw: payload
+	};
+}
+/**
+* Parses an SSE response body into {@link ChatChunk}s.
+*
+* Handles multi-line `data:` payloads, comment lines, and the terminal
+* `[DONE]` sentinel.
+*
+* @param response A streaming `fetch` response with a readable body.
+*/
+async function* parseChatStream(response) {
+	const body = response.body;
+	if (!body) return;
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (value) buffer += decoder.decode(value, { stream: true });
+			if (done) buffer += decoder.decode();
+			let sep;
+			while ((sep = buffer.search(/\r?\n\r?\n/)) !== -1) {
+				const rawFrame = buffer.slice(0, sep);
+				buffer = buffer.slice(sep + (buffer[sep] === "\r" ? 4 : 2));
+				const dataLines = [];
+				for (const line of rawFrame.split(/\r?\n/)) {
+					if (line.startsWith(":")) continue;
+					if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+				}
+				if (dataLines.length === 0) continue;
+				const data = dataLines.join("\n");
+				if (data === "[DONE]") {
+					yield {
+						delta: "",
+						done: true,
+						raw: {}
+					};
+					return;
+				}
+				let payload;
+				try {
+					payload = JSON.parse(data);
+				} catch {
+					payload = { delta: data };
+				}
+				const isDone = payload.done === true;
+				yield frameToChunk(payload, isDone);
+				if (isDone) return;
+			}
+			if (done) break;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+//#endregion
+//#region src/errors.ts
+/** Base class for all Agent Memory client errors. */
+var AgentMemoryError = class extends Error {
+	name = "AgentMemoryError";
+	/** HTTP status code, or `0` for connection failures. */
+	status;
+	/** Short error title from the API or a generic label. */
+	title;
+	/** Human-readable detail when provided. */
+	detail;
+	/** RFC 7807 `type` URI when provided. */
+	type;
+	/** RFC 7807 `instance` when provided. */
+	instance;
+	/** Additional problem-details fields. */
+	extensions;
+	constructor(options) {
+		const detail = options.detail ?? void 0;
+		let message = `[${options.status}] ${options.title}`;
+		if (detail) message += `: ${detail}`;
+		super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.status = options.status;
+		this.title = options.title;
+		this.detail = detail;
+		this.type = options.type ?? void 0;
+		this.instance = options.instance ?? void 0;
+		this.extensions = options.extensions ?? {};
+	}
+};
+/** Missing or invalid bearer token (401). */
+var AuthError = class extends AgentMemoryError {
+	name = "AuthError";
+};
+/** Principal or scope floor rejected the call (403). */
+var ScopeError = class extends AgentMemoryError {
+	name = "ScopeError";
+};
+/** Resource not found (404). */
+var NotFoundError = class extends AgentMemoryError {
+	name = "NotFoundError";
+};
+/** Invalid request body or parameters (400 / 422). */
+var ValidationError = class extends AgentMemoryError {
+	name = "ValidationError";
+};
+/** Rate or token budget exceeded (429). */
+var RateLimitError = class extends AgentMemoryError {
+	name = "RateLimitError";
+	/** Seconds from `Retry-After` when numeric. */
+	retryAfter;
+	constructor(options) {
+		super(options);
+		this.retryAfter = options.retryAfter ?? void 0;
+	}
+};
+/** Server error after retries exhausted (5xx). */
+var ServerError = class extends AgentMemoryError {
+	name = "ServerError";
+};
+/** Network failure, timeout, or other non-HTTP error (status 0). */
+var ConnectionError = class extends AgentMemoryError {
+	name = "ConnectionError";
+};
+/**
+* The caller aborted the request through the `signal` they supplied (status 0).
+*
+* Distinct from {@link ConnectionError} so a deliberate cancellation can be told
+* apart from a timeout or a network failure: only the latter two describe
+* something that went wrong, and only they are worth reporting to a user.
+*/
+var CancelledError = class extends AgentMemoryError {
+	name = "CancelledError";
+};
+const STATUS_MAP = {
+	400: ValidationError,
+	401: AuthError,
+	403: ScopeError,
+	404: NotFoundError,
+	422: ValidationError
+};
+function parseRetryAfter(headers) {
+	const raw = headers.get("Retry-After") ?? headers.get("retry-after");
+	if (raw === null) return void 0;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : void 0;
+}
+/**
+* Builds a typed error from an API error response body and headers.
+* @param status HTTP status code.
+* @param body Parsed JSON body or plain text, or null.
+* @param headers Response headers (for `Retry-After` on 429).
+*/
+function errorFromResponse(status, body, headers) {
+	const extensions = {};
+	let title = "Agent Memory request failed";
+	let detail;
+	let type;
+	let instance;
+	if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+		const o = body;
+		const t = o.title ?? o.message;
+		if (typeof t === "string") title = t;
+		if (typeof o.detail === "string") detail = o.detail;
+		if (typeof o.type === "string") type = o.type;
+		if (typeof o.instance === "string") instance = o.instance;
+		for (const [key, value] of Object.entries(o)) if (![
+			"status",
+			"title",
+			"detail",
+			"type",
+			"instance",
+			"message"
+		].includes(key)) extensions[key] = value;
+	} else if (typeof body === "string" && body.length > 0) detail = body;
+	const base = {
+		status,
+		title,
+		detail,
+		type,
+		instance,
+		extensions
+	};
+	if (status >= 500) return new ServerError(base);
+	if (status === 429) return new RateLimitError({
+		...base,
+		retryAfter: parseRetryAfter(headers)
+	});
+	const Ctor = STATUS_MAP[status];
+	if (Ctor) return new Ctor(base);
+	return new AgentMemoryError(base);
+}
+
+//#endregion
+//#region src/idempotency.ts
+/**
+* Idempotency-key derivation for safe write retries.
+*
+* Mirrors the reference clients: the key is a SHA-256 digest of the request
+* method, path, body, and a 30-second time bucket. Identical writes replayed
+* within the same bucket collapse to a single server-side effect, which makes
+* the `/facts` and `/facts/batch` writes safe to retry.
+*/
+const BUCKET_SECONDS = 30;
+function toHex(buffer) {
+	const bytes = new Uint8Array(buffer);
+	let out = "";
+	for (const b of bytes) out += b.toString(16).padStart(2, "0");
+	return out;
+}
+/**
+* Computes an idempotency key for a write request.
+*
+* @param method HTTP method (e.g. `POST`).
+* @param path Request path including the context prefix.
+* @param body Serialised request body (empty string when none).
+* @param now Current epoch milliseconds (injectable for tests).
+* @returns A hex-encoded SHA-256 digest.
+*/
+async function idempotencyKey(method, path, body, now = Date.now()) {
+	const bucket = Math.floor(now / 1e3 / BUCKET_SECONDS);
+	const material = `${method}\0${path}\0${body}\0${bucket}`;
+	const data = new TextEncoder().encode(material);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return toHex(digest);
+}
+
+//#endregion
+//#region src/retry.ts
+const _BACKOFF_MS = [
+	250,
+	500,
+	1e3
+];
+/** Back-off delays (ms) used between retry attempts for idempotent reads. */
+function backoffSchedule(maxRetries) {
+	const capped = Math.max(0, Math.min(maxRetries, _BACKOFF_MS.length));
+	return _BACKOFF_MS.slice(0, capped);
+}
+/**
+* Whether a failed request should be retried.
+*
+* Retries apply to idempotent reads (`GET`/`HEAD`) and writes explicitly marked
+* idempotent, on `5xx` responses or connection errors (`status === null`).
+*/
+function shouldRetry(method, status, attempt, maxRetries, idempotent = false) {
+	if (attempt >= maxRetries) return false;
+	const m = method.toUpperCase();
+	if (m !== "GET" && m !== "HEAD" && !idempotent) return false;
+	if (status === null) return true;
+	return status >= 500;
+}
+
+//#endregion
+//#region src/transport.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const DEFAULT_MAX_RETRIES = 3;
+function buildUrl(endpoint, path, query) {
+	const urlStr = path.startsWith("http://") || path.startsWith("https://") ? path : `${endpoint.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+	if (!query || Object.keys(query).length === 0) return urlStr;
+	const url = new URL(urlStr);
+	for (const [k, v] of Object.entries(query)) {
+		if (v === void 0 || v === null) continue;
+		url.searchParams.set(k, String(v));
+	}
+	return url.toString();
+}
+function decodeBody(text) {
+	if (!text) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+/**
+* Combines a caller's abort signal with an internal one.
+*
+* The internal signal carries the request timeout, so it cannot simply be
+* replaced by the caller's — both have to be able to abort the request.
+*
+* @returns A cleanup function that detaches the forwarding listener.
+*/
+function forwardAbort(from, to) {
+	if (!from) return () => {};
+	if (from.aborted) {
+		to.abort();
+		return () => {};
+	}
+	const onAbort = () => to.abort();
+	from.addEventListener("abort", onAbort, { once: true });
+	return () => from.removeEventListener("abort", onAbort);
+}
+/**
+* Sends a multipart body with `XMLHttpRequest` so its progress can be observed.
+*
+* `fetch` cannot report how much of a request body has been sent in any browser,
+* which leaves a large upload indistinguishable from a stalled one. This path is
+* used only when a caller asks for progress; everything else stays on `fetch`.
+*/
+function sendWithProgress(options) {
+	const { url, method, headers, body, signal, onProgress } = options;
+	return new Promise((resolve, reject) => {
+		const request = new XMLHttpRequest();
+		request.open(method, url, true);
+		for (const [name, value] of Object.entries(headers)) request.setRequestHeader(name, value);
+		request.upload.addEventListener("progress", (event) => {
+			onProgress({
+				loaded: event.loaded,
+				total: event.lengthComputable ? event.total : void 0
+			});
+		});
+		request.addEventListener("load", () => {
+			resolve({
+				status: request.status,
+				text: request.responseText,
+				headers: parseRawHeaders(request.getAllResponseHeaders())
+			});
+		});
+		request.addEventListener("error", () => reject(/* @__PURE__ */ new TypeError("Network request failed")));
+		request.addEventListener("abort", () => {
+			const error = /* @__PURE__ */ new Error("Request aborted");
+			error.name = "AbortError";
+			reject(error);
+		});
+		const onAbort = () => request.abort();
+		if (signal.aborted) request.abort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		request.addEventListener("loadend", () => signal.removeEventListener("abort", onAbort));
+		request.send(body);
+	});
+}
+function parseRawHeaders(raw) {
+	const headers = new Headers();
+	for (const line of raw.trim().split(/[\r\n]+/)) {
+		const separator = line.indexOf(":");
+		if (separator === -1) continue;
+		headers.append(line.slice(0, separator).trim(), line.slice(separator + 1).trim());
+	}
+	return headers;
+}
+/**
+* Performs authenticated HTTP requests with retries, idempotency keys, JSON
+* handling, and server-sent-event streaming.
+*/
+var Transport = class Transport {
+	endpoint;
+	apiKey;
+	timeoutMs;
+	maxRetries;
+	fetchImpl;
+	onBehalfOf;
+	constructor(options) {
+		if (!options.endpoint) throw new TypeError("Agent Memory endpoint is required.");
+		if (!options.apiKey) throw new TypeError("Agent Memory API key is required.");
+		this.endpoint = options.endpoint.replace(/\/$/, "");
+		this.apiKey = options.apiKey;
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+		this.onBehalfOf = options.onBehalfOf;
+	}
+	/**
+	* Returns a copy of this transport that issues every request on behalf of
+	* `principalId` (adds the `X-Spectron-On-Behalf-Of` header).
+	*/
+	withOnBehalfOf(principalId) {
+		return new Transport({
+			endpoint: this.endpoint,
+			apiKey: this.apiKey,
+			timeoutMs: this.timeoutMs,
+			maxRetries: this.maxRetries,
+			fetchImpl: this.fetchImpl,
+			onBehalfOf: principalId
+		});
+	}
+	/** Builds the common request headers, including delegation when configured. */
+	baseHeaders(accept) {
+		const headers = {
+			Accept: accept,
+			Authorization: `Bearer ${this.apiKey}`,
+			"User-Agent": `surrealdb-memory-js/1.0.0-alpha.9`
+		};
+		if (this.onBehalfOf) headers["X-Spectron-On-Behalf-Of"] = this.onBehalfOf;
+		return headers;
+	}
+	/**
+	* Sends a JSON or multipart request.
+	* @returns Parsed JSON, or `null` for empty 204 responses.
+	*/
+	async requestJson(method, path, init) {
+		const methodUpper = method.toUpperCase();
+		const url = buildUrl(this.endpoint, path, init?.query);
+		const schedule = backoffSchedule(this.maxRetries);
+		const headerObj = this.baseHeaders("application/json");
+		let body;
+		let serialisedBody = "";
+		const bodyInput = init?.body;
+		const isMultipart = bodyInput instanceof FormData;
+		if (bodyInput !== void 0) if (isMultipart) body = bodyInput;
+		else {
+			serialisedBody = JSON.stringify(bodyInput);
+			body = serialisedBody;
+			headerObj["Content-Type"] = "application/json";
+		}
+		const timeoutMs = isMultipart ? init?.timeoutMs ?? 0 : init?.timeoutMs ?? this.timeoutMs;
+		if (init?.idempotent) headerObj["Idempotency-Key"] = await idempotencyKey(methodUpper, path, serialisedBody);
+		if (init?.signal?.aborted) throw new CancelledError({
+			status: 0,
+			title: "Request cancelled",
+			detail: "The signal was already aborted"
+		});
+		const withProgress = isMultipart && init?.onUploadProgress !== void 0 && typeof XMLHttpRequest !== "undefined";
+		let attempt = 0;
+		for (;;) {
+			const controller = new AbortController();
+			const detachAbort = forwardAbort(init?.signal, controller);
+			const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+			const headersForFetch = { ...headerObj };
+			if (body instanceof FormData) delete headersForFetch["Content-Type"];
+			try {
+				const response = withProgress ? await sendWithProgress({
+					url,
+					method: methodUpper,
+					headers: headersForFetch,
+					body,
+					signal: controller.signal,
+					onProgress: init.onUploadProgress
+				}).then(({ status, text: text$1, headers }) => ({
+					status,
+					ok: status >= 200 && status < 300,
+					headers,
+					text: () => Promise.resolve(text$1)
+				})) : await this.fetchImpl(url, {
+					method: methodUpper,
+					headers: headersForFetch,
+					body: methodUpper === "GET" || methodUpper === "HEAD" ? void 0 : body,
+					signal: controller.signal
+				});
+				clearTimeout(timer);
+				detachAbort();
+				if (response.status >= 400 && shouldRetry(methodUpper, response.status, attempt, this.maxRetries, init?.idempotent)) {
+					await sleep(schedule[attempt] ?? 1e3);
+					attempt += 1;
+					continue;
+				}
+				const text = await response.text();
+				if (!response.ok) throw errorFromResponse(response.status, decodeBody(text), response.headers);
+				if (response.status === 204 || text.length === 0) return null;
+				return decodeBody(text);
+			} catch (e) {
+				clearTimeout(timer);
+				detachAbort();
+				if (e instanceof Error && e.name === "AbortError") {
+					if (init?.signal?.aborted) throw new CancelledError({
+						status: 0,
+						title: "Request cancelled",
+						detail: "The request was aborted by the caller",
+						cause: e
+					});
+					throw new ConnectionError({
+						status: 0,
+						title: "Request timed out",
+						detail: `Exceeded ${timeoutMs}ms`,
+						cause: e
+					});
+				}
+				if (shouldRetry(methodUpper, null, attempt, this.maxRetries, init?.idempotent) && !(e instanceof Error && "status" in e)) {
+					await sleep(schedule[attempt] ?? 1e3);
+					attempt += 1;
+					continue;
+				}
+				if (e && typeof e === "object" && "status" in e) throw e;
+				throw new ConnectionError({
+					status: 0,
+					title: "Connection failed",
+					detail: e instanceof Error ? e.message : String(e),
+					cause: e
+				});
+			}
+		}
+	}
+	/**
+	* GET that returns raw bytes (e.g. document `raw`).
+	*/
+	async requestBytes(method, path, init) {
+		const methodUpper = method.toUpperCase();
+		const url = buildUrl(this.endpoint, path, init?.query);
+		const timeoutMs = init?.timeoutMs ?? this.timeoutMs;
+		const schedule = backoffSchedule(this.maxRetries);
+		const headers = this.baseHeaders("*/*");
+		let attempt = 0;
+		for (;;) {
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
+			try {
+				const response = await this.fetchImpl(url, {
+					method: methodUpper,
+					headers,
+					signal: controller.signal
+				});
+				clearTimeout(timer);
+				if (response.status >= 400 && shouldRetry(methodUpper, response.status, attempt, this.maxRetries)) {
+					await sleep(schedule[attempt] ?? 1e3);
+					attempt += 1;
+					continue;
+				}
+				if (!response.ok) {
+					const text = await response.text();
+					throw errorFromResponse(response.status, decodeBody(text), response.headers);
+				}
+				return await response.arrayBuffer();
+			} catch (e) {
+				clearTimeout(timer);
+				if (e instanceof Error && e.name === "AbortError") throw new ConnectionError({
+					status: 0,
+					title: "Request timed out",
+					detail: `Exceeded ${timeoutMs}ms`,
+					cause: e
+				});
+				if (shouldRetry(methodUpper, null, attempt, this.maxRetries)) {
+					await sleep(schedule[attempt] ?? 1e3);
+					attempt += 1;
+					continue;
+				}
+				if (e && typeof e === "object" && "status" in e) throw e;
+				throw new ConnectionError({
+					status: 0,
+					title: "Connection failed",
+					detail: e instanceof Error ? e.message : String(e),
+					cause: e
+				});
+			}
+		}
+	}
+	/**
+	* Opens a server-sent-event stream (e.g. streaming `chat`).
+	*
+	* Streams are not retried; the returned {@link Response} carries the raw SSE
+	* body for the caller to parse.
+	*/
+	async stream(method, path, init) {
+		const methodUpper = method.toUpperCase();
+		const url = buildUrl(this.endpoint, path, init?.query);
+		const headers = this.baseHeaders("text/event-stream");
+		let body;
+		if (init?.body !== void 0) {
+			body = JSON.stringify(init.body);
+			headers["Content-Type"] = "application/json";
+		}
+		let response;
+		try {
+			response = await this.fetchImpl(url, {
+				method: methodUpper,
+				headers,
+				body
+			});
+		} catch (e) {
+			throw new ConnectionError({
+				status: 0,
+				title: "Connection failed",
+				detail: e instanceof Error ? e.message : String(e),
+				cause: e
+			});
+		}
+		if (!response.ok) {
+			const text = await response.text();
+			throw errorFromResponse(response.status, decodeBody(text), response.headers);
+		}
+		return response;
+	}
+};
+
+//#endregion
+//#region src/client.ts
+function addDefined(target, key, value) {
+	if (value !== void 0) target[key] = value;
+}
+/**
+* Typed client for the public Agent Memory API: memory writes and recall, document
+* ingestion, sessions, entities, lifecycle, traces, and scope administration.
+*
+* The client is pinned to a single `context`; every call targets
+* `/api/v1/{context}/…`.
+*/
+var AgentMemory = class AgentMemory {
+	transport;
+	/** Agent Memory context id this client calls. */
+	contextId;
+	/** Document ingestion, retrieval, corpus search, and the keyword graph. */
+	documents;
+	/** Entity records, attributes, relations, and attribute history. */
+	entities;
+	/** Conversation sessions for this context. */
+	sessions;
+	/** Expiry and decay sweeps. */
+	lifecycle;
+	/** Retrieval trace tooling. */
+	traces;
+	/** Principals and their scope grants. */
+	principals;
+	/** The scope tree. */
+	scopes;
+	/** Self-service API keys for this context. */
+	keys;
+	constructor(options) {
+		if (!options.context) throw new TypeError("Agent Memory context is required.");
+		this.contextId = options.context;
+		this.transport = new Transport({
+			apiKey: options.apiKey,
+			endpoint: options.endpoint,
+			timeoutMs: options.timeout,
+			maxRetries: options.maxRetries,
+			fetchImpl: options.fetchImpl
+		});
+		const components = AgentMemory.buildComponents(this.transport, this.contextId);
+		this.documents = components.documents;
+		this.entities = components.entities;
+		this.sessions = components.sessions;
+		this.lifecycle = components.lifecycle;
+		this.traces = components.traces;
+		this.principals = components.principals;
+		this.scopes = components.scopes;
+		this.keys = components.keys;
+	}
+	static buildComponents(transport, contextId) {
+		return {
+			documents: new Documents(transport, contextId),
+			entities: new Entities(transport, contextId),
+			sessions: new Sessions(transport, contextId),
+			lifecycle: new Lifecycle(transport, contextId),
+			traces: new Traces(transport, contextId),
+			principals: new Principals(transport, contextId),
+			scopes: new Scopes(transport, contextId),
+			keys: new Keys(transport, contextId)
+		};
+	}
+	get base() {
+		return getContextApiPrefix(this.contextId);
+	}
+	/**
+	* Returns a client that issues every request on behalf of `principalId`,
+	* sending the `X-Spectron-On-Behalf-Of` delegation header. Requires the
+	* `manage` grant. The original client is left unchanged.
+	*/
+	onBehalfOf(principalId) {
+		if (!principalId) throw new TypeError("onBehalfOf requires a principal id.");
+		const transport = this.transport.withOnBehalfOf(principalId);
+		const delegate = Object.create(AgentMemory.prototype);
+		return Object.assign(delegate, {
+			contextId: this.contextId,
+			transport,
+			...AgentMemory.buildComponents(transport, this.contextId)
+		});
+	}
+	/**
+	* Liveness probe for the API (`GET /api/v1/health`).
+	* @throws {AgentMemoryError} When the service is unhealthy or unreachable.
+	*/
+	async health() {
+		await this.transport.requestJson("GET", "/api/v1/health");
+	}
+	/**
+	* Persists facts from free-form text and/or caller-supplied triples
+	* (`POST /facts`). Idempotent within a 30-second window.
+	*/
+	async remember(text, options) {
+		const payload = {};
+		addDefined(payload, "text", text);
+		addDefined(payload, "infer", options?.infer);
+		addDefined(payload, "session_id", options?.sessionId);
+		addDefined(payload, "scopes", normaliseScope(options?.scopes));
+		addDefined(payload, "role", options?.role);
+		addDefined(payload, "memory_category", options?.memoryCategory);
+		addDefined(payload, "labels", options?.labels);
+		addDefined(payload, "triples", options?.triples);
+		const body = await this.transport.requestJson("POST", `${this.base}/facts`, {
+			body: payload,
+			idempotent: true
+		});
+		return body;
+	}
+	/**
+	* Persists facts from a batch of conversation messages (`POST /facts/batch`).
+	* Idempotent within a 30-second window.
+	*/
+	async rememberMany(messages, options) {
+		const payload = { messages };
+		addDefined(payload, "session_id", options?.sessionId);
+		addDefined(payload, "scopes", normaliseScope(options?.scopes));
+		addDefined(payload, "extract", options?.extract);
+		addDefined(payload, "infer", options?.infer);
+		addDefined(payload, "labels", options?.labels);
+		const body = await this.transport.requestJson("POST", `${this.base}/facts/batch`, {
+			body: payload,
+			idempotent: true
+		});
+		return body;
+	}
+	/** Semantic recall over memory for this context (`POST /query`). */
+	async recall(query, options) {
+		const payload = { query };
+		addDefined(payload, "k", options?.k);
+		addDefined(payload, "mode", options?.mode);
+		addDefined(payload, "sessionId", options?.sessionId);
+		addDefined(payload, "include", options?.include);
+		addDefined(payload, "asOf", options?.asOf);
+		addDefined(payload, "atInstant", options?.atInstant);
+		addDefined(payload, "labels", options?.labels);
+		addDefined(payload, "lens", normaliseScope(options?.lens));
+		addDefined(payload, "scopeView", options?.scopeView);
+		addDefined(payload, "validFrom", options?.validFrom);
+		addDefined(payload, "validUntil", options?.validUntil);
+		addDefined(payload, "source", options?.source);
+		addDefined(payload, "location", options?.location);
+		const body = await this.transport.requestJson("POST", `${this.base}/query`, { body: payload });
+		return body;
+	}
+	/** Forgets memory matching a natural-language query (`POST /forget`). */
+	async forget(query, options) {
+		const payload = { query };
+		if (options?.purge) payload.purge = true;
+		const body = await this.transport.requestJson("POST", `${this.base}/forget`, { body: payload });
+		return body;
+	}
+	async chat(message, options) {
+		const payload = { message };
+		addDefined(payload, "sessionId", options?.sessionId);
+		addDefined(payload, "scopes", normaliseScope(options?.scopes));
+		addDefined(payload, "model", options?.model);
+		if (options?.bypassCache) payload.bypassCache = true;
+		addDefined(payload, "labels", options?.labels);
+		if (options?.stream) {
+			payload.stream = true;
+			const response = await this.transport.stream("POST", `${this.base}/chat`, { body: payload });
+			return parseChatStream(response);
+		}
+		const body = await this.transport.requestJson("POST", `${this.base}/chat`, { body: payload });
+		return body;
+	}
+	/** Retrieves LLM-facing context text for a query without a session (`POST /context`). */
+	async context(query, options) {
+		const payload = { query };
+		addDefined(payload, "k", options?.k);
+		addDefined(payload, "labels", options?.labels);
+		addDefined(payload, "lens", normaliseScope(options?.lens));
+		addDefined(payload, "scopeView", options?.scopeView);
+		const body = await this.transport.requestJson("POST", `${this.base}/context`, { body: payload });
+		return body;
+	}
+	/** Runs a reflection pass; may persist attributes when `persist` is true (`POST /reflect`). */
+	async reflect(query, options) {
+		const body = await this.transport.requestJson("POST", `${this.base}/reflect`, { body: {
+			query,
+			persist: options?.persist ?? false
+		} });
+		return body;
+	}
+	/** Consolidates accumulated observations into durable facts (`POST /consolidate`). */
+	async consolidate(options) {
+		const payload = {};
+		if (options?.dryRun) payload.dryRun = true;
+		addDefined(payload, "factLimit", options?.factLimit);
+		addDefined(payload, "observationLimit", options?.observationLimit);
+		const body = await this.transport.requestJson("POST", `${this.base}/consolidate`, { body: payload });
+		return body;
+	}
+	/** Infers and emits new relation edges between entities (`POST /elaborate`). */
+	async elaborate(options) {
+		const payload = {};
+		addDefined(payload, "entityRef", options?.entityRef);
+		addDefined(payload, "budget", options?.budget);
+		if (options?.sweep) payload.sweep = true;
+		if (options?.dryRun) payload.dryRun = true;
+		const body = await this.transport.requestJson("POST", `${this.base}/elaborate`, { body: payload });
+		return body;
+	}
+	/** Runs an integrity check over the memory store (`POST /fsck`). */
+	async fsck(options) {
+		const payload = {};
+		addDefined(payload, "check", options?.check);
+		addDefined(payload, "duplicateThreshold", options?.duplicateThreshold);
+		addDefined(payload, "maxResults", options?.maxResults);
+		const body = await this.transport.requestJson("POST", `${this.base}/fsck`, { body: payload });
+		return body;
+	}
+	/** Inspects an entity, attribute, or trace by reference (`GET /inspect`). */
+	async inspect(ref, options) {
+		const query = { ref };
+		addDefined(query, "asOf", options?.asOf);
+		addDefined(query, "atInstant", options?.atInstant);
+		addDefined(query, "validFrom", options?.validFrom);
+		addDefined(query, "validUntil", options?.validUntil);
+		const body = await this.transport.requestJson("GET", `${this.base}/inspect`, { query });
+		return body;
+	}
+	/** Lists one page of audit rows for write/recall activity (`GET /audit`). */
+	async audit(options) {
+		const query = {};
+		addDefined(query, "principal", options?.principal);
+		addDefined(query, "key", options?.key);
+		addDefined(query, "kind", options?.kind);
+		addDefined(query, "since", options?.since);
+		addDefined(query, "until", options?.until);
+		addPageParams(query, options);
+		const body = await this.transport.requestJson("GET", `${this.base}/audit`, { query });
+		return body;
+	}
+	/** Every matching audit row, following cursors to exhaustion. */
+	async auditAll(options) {
+		return collectPages((cursor) => this.audit({
+			...options,
+			cursor
+		}), "rows");
+	}
+	/**
+	* Structured memory state snapshot (`GET /state`).
+	*
+	* A snapshot, not an export: this is a composite read over six tables, each
+	* 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
+	* 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`.
+	*/
+	async state(options) {
+		const query = {};
+		addDefined(query, "limit", options?.limit);
+		const body = await this.transport.requestJson("GET", `${this.base}/state`, { query });
+		return body;
+	}
+	/** Static and dynamic profile slices (`GET /profile`). */
+	async profile() {
+		const body = await this.transport.requestJson("GET", `${this.base}/profile`);
+		return body;
+	}
+	/** The calling principal's identity and resolved grants (`GET /me`). */
+	async whoami() {
+		const body = await this.transport.requestJson("GET", `${this.base}/me`);
+		return body;
+	}
+};
+
+//#endregion
+//#region src/types/domain.ts
+/** Inference mode for the `/facts` write API. */
+const InferMode = {
+	full: "full",
+	triples: "triples",
+	preview: "preview",
+	none: "none"
+};
+/** Bulk extraction strategy for `/facts/batch`. */
+const BatchExtractionMode = {
+	per_message: "per_message",
+	whole_conversation: "whole_conversation"
+};
+/** Memory category classification applied during extraction. */
+const MemoryCategory = {
+	identity: "identity",
+	knowledge: "knowledge",
+	context: "context"
+};
+/** Role of a conversation turn participant. */
+const TurnRole = {
+	user: "user",
+	assistant: "assistant",
+	system: "system",
+	tool: "tool"
+};
+/** Chunk query mode for `/documents/query`. */
+const QueryMode = {
+	hybrid: "hybrid",
+	vector: "vector",
+	bm25: "bm25",
+	hybrid_graph: "hybrid_graph"
+};
+/** Grant verb in the scope permission model. */
+const Verb = {
+	read: "read",
+	write: "write",
+	create_scope: "create_scope",
+	delete_scope: "delete_scope",
+	grant: "grant",
+	manage: "manage",
+	forget: "forget"
+};
+/** Scope read breadth for memory queries. */
+const ScopeView = {
+	strict: "strict",
+	merged: "merged",
+	crossTeam: "crossTeam"
+};
+/** Document pipeline status values returned by the API. */
+const DocumentStatus = {
+	queued: "queued",
+	extracting: "extracting",
+	chunking: "chunking",
+	embedding: "embedding",
+	keywording: "keywording",
+	extracting_nodes: "extracting_nodes",
+	ready: "ready",
+	failed: "failed"
+};
+
+//#endregion
+exports.AgentMemory = AgentMemory;
+exports.AgentMemoryError = AgentMemoryError;
+exports.AuthError = AuthError;
+exports.BatchExtractionMode = BatchExtractionMode;
+exports.CancelledError = CancelledError;
+exports.ConnectionError = ConnectionError;
+exports.DocumentKeywords = DocumentKeywords;
+exports.DocumentStatus = DocumentStatus;
+exports.Documents = Documents;
+exports.Entities = Entities;
+exports.InferMode = InferMode;
+exports.Keys = Keys;
+exports.Lifecycle = Lifecycle;
+exports.MemoryCategory = MemoryCategory;
+exports.NotFoundError = NotFoundError;
+exports.Principals = Principals;
+exports.QueryMode = QueryMode;
+exports.RateLimitError = RateLimitError;
+exports.ScopeError = ScopeError;
+exports.ScopeView = ScopeView;
+exports.Scopes = Scopes;
+exports.ServerError = ServerError;
+exports.Session = Session;
+exports.Sessions = Sessions;
+exports.Traces = Traces;
+exports.Transport = Transport;
+exports.TurnRole = TurnRole;
+exports.ValidationError = ValidationError;
+exports.Verb = Verb;
+exports.addPageParams = addPageParams;
+exports.agentMemoryFileInputToBlob = agentMemoryFileInputToBlob;
+exports.backoffSchedule = backoffSchedule;
+exports.collectPages = collectPages;
+exports.encodePathSegment = encodePathSegment;
+exports.errorFromResponse = errorFromResponse;
+exports.getContextApiPrefix = getContextApiPrefix;
+exports.idempotencyKey = idempotencyKey;
+exports.normaliseScope = normaliseScope;
+exports.parseChatStream = parseChatStream;
+exports.shouldRetry = shouldRetry;
+exports.walkPages = walkPages;