xmemory 3.6.0 → 3.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,154 @@
1
+ /**
2
+ * InstanceHandle — scoped data operations on a single xmemory instance.
3
+ */
4
+ import type { SetupFormatValue, AgentSetupResult, ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsResult, DecisionInput, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ReviewSuggestionsResult, SuggestionRequestOptions, ToolDescription, WriteMutation, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
5
+ export declare class DescribeResult {
6
+ readonly instanceId: string;
7
+ readonly instanceName: string;
8
+ readonly about: string;
9
+ readonly schemaSummary: string;
10
+ readonly tools: readonly ToolDescription[];
11
+ /**
12
+ * What this memory is for. This is the instance's description, under the name
13
+ * the agent-facing surfaces give it.
14
+ */
15
+ readonly purpose: string | null;
16
+ /**
17
+ * The standing preference set for this memory, rendered verbatim.
18
+ *
19
+ * "owner" is the wire field's name, not a verified claim about authorship:
20
+ * anyone holding edit permission on the instance can set this, including an
21
+ * agent that was asked to. {@link asText} therefore labels it by provenance.
22
+ */
23
+ readonly ownerInstructions: string | null;
24
+ /**
25
+ * Generated from the schema; `null` until it has been generated, and cleared
26
+ * again by a schema change. Not folded into {@link asText} — it overlaps
27
+ * `schemaSummary`, which is already there, and a prompt gains nothing from
28
+ * being told twice.
29
+ */
30
+ readonly usageBrief: string | null;
31
+ constructor(raw: RawDescribeResult);
32
+ /**
33
+ * Plain-text representation suitable for injecting into an LLM system prompt.
34
+ *
35
+ * Includes `purpose` and `ownerInstructions` when the instance has them;
36
+ * `usageBrief` is deliberately left out (read the property if you want it).
37
+ *
38
+ * Both of those are free text set by anyone holding edit permission on the
39
+ * instance, so each is labelled with where it came from and how much weight it
40
+ * deserves rather than presented as if this library authored it. The labels
41
+ * state provenance; they are not a security boundary, and a caller embedding
42
+ * this in a system prompt is still handling text it does not control.
43
+ *
44
+ * By default, tools are presented as method calls (matching the SDK).
45
+ * Set `includeHttp` to `true` to also show HTTP method and path for
46
+ * raw REST callers.
47
+ */
48
+ asText(options?: {
49
+ includeHttp?: boolean;
50
+ }): string;
51
+ /** Tool definitions in the Anthropic tool-use format. */
52
+ asAnthropicTools(): Record<string, unknown>[];
53
+ /** Tool definitions in the OpenAI function-calling format. */
54
+ asOpenaiTools(): Record<string, unknown>[];
55
+ }
56
+ export declare class InstanceHandle {
57
+ readonly id: string;
58
+ private readonly _requestOne;
59
+ private _describeCache;
60
+ private _describeCacheAt;
61
+ private _describeTtlMs;
62
+ constructor(id: string, requestOne: RequestOneFn);
63
+ read(query: string, options?: ReadOptions): Promise<ReadResult>;
64
+ /**
65
+ * Write to this instance: extract from free text, or apply structured
66
+ * mutations. Pass a string to extract structured data from free-form text,
67
+ * or a `WriteMutation[]` to apply deterministic, LLM-free create / update /
68
+ * delete edits (applied in array order; later mutations may reference
69
+ * objects created earlier in the batch, and a `null` value in a mutation's
70
+ * `values` clears that field). `extractionLogic` / `diffEngine` only apply
71
+ * to the text form.
72
+ *
73
+ * Pass `scope` — a `WriteScope` of concrete existing objects, each named by
74
+ * its user-defined primary key — to anchor a text write to them. Their current
75
+ * values are shown to the extractor so the write updates them instead of
76
+ * creating duplicates, and the write is then confined to the scope: it may
77
+ * only modify or delete the scoped objects and create new objects and
78
+ * relations anchored to them. A write that would touch any other existing
79
+ * object fails. The server accepts a scope with fast extraction only, and a
80
+ * scoped write additionally requires read permission on the instance, because
81
+ * the scoped objects' values are shown to the extractor.
82
+ */
83
+ write(text: string, options?: WriteOptions): Promise<WriteResult>;
84
+ write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
85
+ /**
86
+ * Submit a write job and return immediately with a `write_id` for polling.
87
+ * Accepts the same text / `WriteMutation[]` dual input as {@link write}, and
88
+ * the same `scope`. A scope violation is reported by {@link writeStatus} as a
89
+ * failed write.
90
+ */
91
+ writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
92
+ writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
93
+ writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
94
+ extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
95
+ getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
96
+ /**
97
+ * Return the current consolidated schema-improvement proposal (step 1).
98
+ *
99
+ * The result's `proposal.proposal_version` is the optimistic-concurrency
100
+ * token you pass to `decideSuggestions` / `applyPendingDecisions`. When
101
+ * `status === "evolution_in_progress"`, back off for `retry_after_seconds`
102
+ * and retry instead of blocking on the in-flight migration.
103
+ */
104
+ reviewSuggestions(options?: SuggestionRequestOptions): Promise<ReviewSuggestionsResult>;
105
+ /**
106
+ * Record accept/reject/defer decisions for proposal items, in bulk (step 2).
107
+ *
108
+ * `proposalVersion` must be the token from the latest `reviewSuggestions`; a
109
+ * stale token throws `XmemoryAPIError` with `code === "stale_proposal_version"`.
110
+ * The result's `next_proposal_version` can be passed straight to
111
+ * `applyPendingDecisions`.
112
+ */
113
+ decideSuggestions(proposalVersion: string, decisions: DecisionInput[], options?: SuggestionRequestOptions): Promise<DecideSuggestionsResult>;
114
+ /**
115
+ * Commit accepted decisions as a single migration (step 3).
116
+ *
117
+ * `status === "nothing_to_apply"` means no accepted items were left. A stale
118
+ * `proposalVersion` or an unmet dependency throws `XmemoryAPIError`
119
+ * (`code === "stale_proposal_version"` / `"dependency_closure_failed"`).
120
+ */
121
+ applyPendingDecisions(proposalVersion: string, options?: SuggestionRequestOptions): Promise<ApplyPendingDecisionsResult>;
122
+ /**
123
+ * Return the agent-facing tool descriptions for this instance.
124
+ *
125
+ * The instance's schema comes back in `DescribeResult.schemaSummary`.
126
+ *
127
+ * Results are cached locally with a TTL (default 5 min).
128
+ * Call `clearDescribeCache()` to force a refresh.
129
+ */
130
+ describe(options?: RequestOptions): Promise<DescribeResult>;
131
+ /**
132
+ * How to connect *this* instance somewhere else, most likely surface first.
133
+ *
134
+ * Answers "how do I also reach this memory on my desktop, or in another editor" —
135
+ * not how to reach it from here, which this handle already does. The same payload
136
+ * `get_setup_instructions` serves over MCP and `xmemcli instance setup` prints.
137
+ *
138
+ * **Carries no credential.** The steps tell a reader to sign in themselves, out of
139
+ * band, so nothing returned here is a secret.
140
+ *
141
+ * Not cached, unlike `describe()`: it is computed from the instance's current
142
+ * metadata, so an owner who edits a surface hint expects the next call to show it.
143
+ *
144
+ * `format: SetupFormat.PROJECT` additionally returns the files a customer commits so a
145
+ * whole team gets this instance. Read `result.format` rather than assuming: a server
146
+ * older than that parameter ignores it, answers 200, and names no format at all, so
147
+ * `undefined` is the signal that this deployment predates the project rendering.
148
+ */
149
+ setupInstructions(options?: RequestOptions & {
150
+ format?: SetupFormatValue;
151
+ }): Promise<AgentSetupResult>;
152
+ /** Clear the cached describe result so the next `describe()` call fetches fresh data. */
153
+ clearDescribeCache(): void;
154
+ }
@@ -2,12 +2,26 @@
2
2
  * InstanceHandle — scoped data operations on a single xmemory instance.
3
3
  */
4
4
  import { SetupFormat } from "./types.js";
5
+ /**
6
+ * Serialize scope objects to the API's identity wire shape, `{type, key: {key: {...}}}`,
7
+ * by user-defined primary key. Shared by scoped reads and scoped writes so the two
8
+ * cannot drift.
9
+ */
10
+ function serializeScopeObjects(objects) {
11
+ return objects.map((o) => ({ type: o.type, key: { key: o.key } }));
12
+ }
5
13
  /** Build the shared `/write` + `/write_async` request body for either input mode. */
6
14
  function buildWriteBody(input, options) {
7
15
  if (typeof input !== "string") {
8
16
  if (input.length === 0) {
9
17
  throw new Error("structured write requires at least one mutation");
10
18
  }
19
+ // Structured mutations bypass extraction, so there is nothing for a scope to
20
+ // anchor. The overload types already rule this out; the throw catches a caller
21
+ // who reached the implementation signature anyway.
22
+ if (options?.scope != null) {
23
+ throw new Error("'scope' and structured mutations are mutually exclusive");
24
+ }
11
25
  // Structured path: no text, no extraction options — mutations go straight
12
26
  // to the wire.
13
27
  return { structured_mutations: input };
@@ -18,6 +32,9 @@ function buildWriteBody(input, options) {
18
32
  };
19
33
  if (options?.diffEngine != null)
20
34
  body.use_diff_engine = options.diffEngine;
35
+ if (options?.scope != null) {
36
+ body.scope = { objects: serializeScopeObjects(options.scope.objects) };
37
+ }
21
38
  return body;
22
39
  }
23
40
  const DEFAULT_DESCRIBE_TTL_MS = 300_000; // 5 minutes
@@ -195,13 +212,8 @@ export class InstanceHandle {
195
212
  mode: options?.readMode ?? "single-answer",
196
213
  };
197
214
  if (options?.scope != null) {
198
- // Serialize to the API's identity wire shape: each object is
199
- // `{type, key: {key: {...}}}` (by user-defined primary key), plus `relations_scope`.
200
215
  body.scope = {
201
- objects: options.scope.objects.map((o) => ({
202
- type: o.type,
203
- key: { key: o.key },
204
- })),
216
+ objects: serializeScopeObjects(options.scope.objects),
205
217
  relations_scope: options.scope.relationsScope ?? "no_relations",
206
218
  };
207
219
  }
@@ -0,0 +1 @@
1
+ {"type":"module"}