xmemory 3.7.0 → 3.8.1
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.
- package/README.md +3 -0
- package/dist/cjs/client.js +369 -0
- package/dist/cjs/index.js +27 -0
- package/dist/cjs/instance.js +388 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/types.js +128 -0
- package/dist/esm/client.d.ts +73 -0
- package/dist/esm/index.d.ts +16 -0
- package/dist/esm/instance.d.ts +154 -0
- package/dist/{instance.js → esm/instance.js} +27 -3
- package/dist/esm/package.json +1 -0
- package/dist/esm/types.d.ts +813 -0
- package/package.json +21 -4
- /package/dist/{client.d.ts → cjs/client.d.ts} +0 -0
- /package/dist/{index.d.ts → cjs/index.d.ts} +0 -0
- /package/dist/{instance.d.ts → cjs/instance.d.ts} +0 -0
- /package/dist/{types.d.ts → cjs/types.d.ts} +0 -0
- /package/dist/{client.js → esm/client.js} +0 -0
- /package/dist/{index.js → esm/index.js} +0 -0
- /package/dist/{types.js → esm/types.js} +0 -0
|
@@ -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
|
+
}
|
|
@@ -193,8 +193,21 @@ function buildJsonSchemaProps(params) {
|
|
|
193
193
|
* exactly the deployments that have no link — the case the comparison exists for.
|
|
194
194
|
* Same treatment `read` already gives `reader_results`.
|
|
195
195
|
*/
|
|
196
|
+
/**
|
|
197
|
+
* An *own* property of a decoded response, or `undefined`.
|
|
198
|
+
*
|
|
199
|
+
* A response is JSON, so a field the server omitted is answered by
|
|
200
|
+
* `Object.prototype` — and normalizing with `result.field ?? default` then writes
|
|
201
|
+
* that inherited value back as an own property, where nothing downstream can tell
|
|
202
|
+
* it apart from something the server actually sent. Prototype pollution anywhere in
|
|
203
|
+
* the process could fabricate sub-answers or a trace id this way.
|
|
204
|
+
*/
|
|
205
|
+
function own(result, key) {
|
|
206
|
+
return Object.hasOwn(result, key) ? result[key] : undefined;
|
|
207
|
+
}
|
|
196
208
|
function withConsoleUrl(result) {
|
|
197
|
-
|
|
209
|
+
const url = own(result, "console_url");
|
|
210
|
+
return { ...result, console_url: typeof url === "string" ? url : null };
|
|
198
211
|
}
|
|
199
212
|
export class InstanceHandle {
|
|
200
213
|
id;
|
|
@@ -226,7 +239,17 @@ export class InstanceHandle {
|
|
|
226
239
|
body,
|
|
227
240
|
timeoutMs: options?.timeoutMs,
|
|
228
241
|
});
|
|
229
|
-
|
|
242
|
+
// Every documented field set explicitly, so each one is an *own* property of
|
|
243
|
+
// what callers get back. Spreading alone leaves an omitted field to be answered
|
|
244
|
+
// by `Object.prototype` when the caller reads it.
|
|
245
|
+
const readerResults = own(result, "reader_results");
|
|
246
|
+
const traceId = own(result, "trace_id");
|
|
247
|
+
return withConsoleUrl({
|
|
248
|
+
...result,
|
|
249
|
+
reader_result: own(result, "reader_result") ?? null,
|
|
250
|
+
reader_results: Array.isArray(readerResults) ? readerResults : [],
|
|
251
|
+
trace_id: typeof traceId === "string" ? traceId : null,
|
|
252
|
+
});
|
|
230
253
|
}
|
|
231
254
|
async write(input, options) {
|
|
232
255
|
return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write`, { body: buildWriteBody(input, options), timeoutMs: options?.timeoutMs }));
|
|
@@ -238,7 +261,8 @@ export class InstanceHandle {
|
|
|
238
261
|
});
|
|
239
262
|
// `trace_id` is normalized here as well because this result declares it for the
|
|
240
263
|
// first time, and the wire omits it exactly as it omits the console link.
|
|
241
|
-
|
|
264
|
+
const traceId = own(result, "trace_id");
|
|
265
|
+
return withConsoleUrl({ ...result, trace_id: typeof traceId === "string" ? traceId : null });
|
|
242
266
|
}
|
|
243
267
|
async writeStatus(writeId, options) {
|
|
244
268
|
return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"type":"module"}
|