xmemory 3.7.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.
- package/README.md +3 -0
- package/dist/cjs/client.js +369 -0
- package/dist/cjs/index.js +27 -0
- package/dist/cjs/instance.js +364 -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/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/{instance.js → esm/instance.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
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"type":"module"}
|