xmemory 2.2.1 → 3.0.0

package/README.md

@@ -122,6 +122,7 @@ Extract and store structured objects from text.
 ```typescript
 const result = await inst.write("Bob is a designer based in Berlin.");
 console.log(result.write_id, result.trace_id);
+console.log(result.changes); // what the write created / updated / deleted
 ```
 
 Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic` defaults to `"fast"`.
@@ -152,7 +153,34 @@ const result = await inst.read("Who is on the team?");
 console.log(result.reader_result);
 ```
 
-Options: `{ readMode?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
+Options: `{ readMode?, scope?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
+
+#### Scoped reads
+
+By default a read may draw on the whole instance. Pass a `scope` to restrict it
+to a set of concrete objects — useful for grounding an answer in exactly the
+records you care about, or for keeping a per-user / per-entity read from leaking
+into unrelated data.
+
+Each object in the scope is identified by its `type` (the PascalCase class name
+or snake_case table name) plus its user-defined primary `key` (a mapping of
+primary-key field name to value):
+
+```typescript
+const result = await inst.read("What do we know about these people?", {
+  scope: {
+    objects: [
+      { type: "Person", key: { full_name: "Alice Smith" } },
+      { type: "Person", key: { full_name: "Bob Jones" } },
+    ],
+    relationsScope: "all_relations", // default: "no_relations"
+  },
+});
+```
+
+`relationsScope` controls relation traversal: `"no_relations"` (the default)
+restricts the read to the listed objects only, while `"all_relations"` also
+exposes the relations among the in-scope objects.
 
 ### `inst.extract(text, options?)` → `ExtractResult`
 

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
 export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
 export { SchemaType } from "./types.js";
 export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
+export type { ScopeObject, ReadScope, RelationsScope } from "./types.js";
 export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
 export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
 export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";

package/dist/instance.d.ts

@@ -5,6 +5,7 @@ import type { ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsRe
 export declare class DescribeResult {
     readonly instanceId: string;
     readonly instanceName: string;
+    readonly about: string;
     readonly schemaSummary: string;
     readonly tools: readonly ToolDescription[];
     constructor(raw: RawDescribeResult);

package/dist/instance.js

@@ -5,11 +5,13 @@ const DEFAULT_DESCRIBE_TTL_MS = 300_000; // 5 minutes
 export class DescribeResult {
     instanceId;
     instanceName;
+    about;
     schemaSummary;
     tools;
     constructor(raw) {
         this.instanceId = raw.instance_id;
         this.instanceName = raw.instance_name;
+        this.about = raw.about ?? "";
         this.schemaSummary = raw.schema_summary;
         this.tools = raw.tools;
     }
@@ -24,6 +26,9 @@ export class DescribeResult {
         const includeHttp = options?.includeHttp ?? false;
         const lines = [];
         lines.push(`Instance: ${this.instanceName} (${this.instanceId})`);
+        if (this.about) {
+            lines.push(`\n${this.about}`);
+        }
         if (this.schemaSummary) {
             lines.push(`\n${this.schemaSummary}`);
         }
@@ -109,6 +114,17 @@ export class InstanceHandle {
             query,
             mode: options?.readMode ?? "single-answer",
         };
+        if (options?.scope != null) {
+            // Serialize to the API's identity wire shape: each object is
+            // `{type, key: {key: {...}}}` (by user-defined primary key), plus `relations_scope`.
+            body.scope = {
+                objects: options.scope.objects.map((o) => ({
+                    type: o.type,
+                    key: { key: o.key },
+                })),
+                relations_scope: options.scope.relationsScope ?? "no_relations",
+            };
+        }
         if (options?.traceId != null)
             body.trace_id = options.traceId;
         return this._requestOne("POST", `/instances/${this.id}/read`, {

package/dist/types.d.ts

@@ -6,8 +6,28 @@ export declare const SchemaType: {
     readonly JSON: 1;
 };
 export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
-export type ExtractionLogic = "fast" | "regular" | "deep";
+export type ExtractionLogic = "fast" | "deep";
 export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
+/**
+ * One concrete object a scoped read may touch. Identify it by `type` (PascalCase
+ * class name or snake_case table name) plus its user-defined primary `key`
+ * (a mapping of primary-key field name to value).
+ */
+export interface ScopeObject {
+    type: string;
+    key: Record<string, string | number | boolean>;
+}
+/** Which relations a scoped read may traverse. */
+export type RelationsScope = "no_relations" | "all_relations";
+/**
+ * A read's scope: the concrete `objects` it may touch, plus relation policy.
+ * `relationsScope` is `no_relations` (objects only) by default; `all_relations`
+ * also exposes the relations among the in-scope `objects`.
+ */
+export interface ReadScope {
+    objects: ScopeObject[];
+    relationsScope?: RelationsScope;
+}
 export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extracted" | "applying" | "completed" | "failed" | "not_found";
 export declare class XmemoryAPIError extends Error {
     readonly status?: number | undefined;
@@ -61,7 +81,8 @@ export interface ReadResult {
 export interface WriteResult {
     readonly write_id: string;
     readonly trace_id: string | null;
-    readonly cleaned_objects: unknown;
+    /** What the write did, grouped into `created` / `updated` / `deleted`. */
+    readonly changes: unknown;
 }
 export interface AsyncWriteResult {
     readonly write_id: string;
@@ -306,6 +327,7 @@ export interface ToolDescription {
 export interface RawDescribeResult {
     readonly instance_id: string;
     readonly instance_name: string;
+    readonly about?: string;
     readonly schema_summary: string;
     readonly tools: ToolDescription[];
 }
@@ -321,6 +343,8 @@ export interface RequestOptions {
 }
 export interface ReadOptions {
     readMode?: ReadMode;
+    /** Restrict the read to a set of concrete objects (plus optional relation traversal). */
+    scope?: ReadScope;
     traceId?: string;
     timeoutMs?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmemory",
-  "version": "2.2.1",
+  "version": "3.0.0",
   "description": "xmemory",
   "keywords": [
     "xmemory"