dsh-mnemon-provider-openviking 0.5.7 → 0.5.8
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 +2 -2
- package/lib/index.d.ts +14 -0
- package/lib/index.js +107 -23
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
An adapter for an existing OpenViking HTTP service and its filesystem-shaped memory resources.
|
|
4
4
|
|
|
5
|
-
Requires a reachable OpenViking endpoint supporting `POST /api/v1/content/write` with `mode: "create"
|
|
5
|
+
Requires a reachable OpenViking endpoint supporting `POST /api/v1/content/write` with `mode: "create"` and `wait: true`; tags are set afterwards through `POST /api/v1/content/set_tags` when the server offers it. Agent-authored memories use unique Markdown files; the adapter verifies completed indexing and exact full-content readback before returning `stored` with a reversible `id`. It does not create extraction sessions.
|
|
6
6
|
|
|
7
|
-
The supported scope is `viking://user/<user>/memories`. Existing `viking://user/memories` settings resolve through the configured user or authenticated `/api/v1/system/status` identity, without rewriting the local registry. A failed response, timeout, or mismatched readback produces an error instead of a committed receipt.
|
|
7
|
+
The supported scope is `viking://user/<user>/memories`. Existing `viking://user/memories` settings resolve through the configured user or authenticated `/api/v1/system/status` identity, without rewriting the local registry. A failed response, timeout, or mismatched readback produces an error instead of a committed receipt. When the server refused the write (an HTTP 4xx other than 408 or 409), the error says nothing was stored; otherwise it includes the requested URI because remote content may remain, so inspect it before retrying. Existing memories remain readable, and downgrading does not remove files written by this adapter.
|
|
8
8
|
|
|
9
9
|
## Use
|
|
10
10
|
|
package/lib/index.d.ts
CHANGED
|
@@ -17,7 +17,21 @@ declare class OpenVikingProvider implements MemoryProviderAdapter {
|
|
|
17
17
|
search(body: MemoryBody, request: SearchRequest, signal?: AbortSignal): Promise<ProviderSearchResult>;
|
|
18
18
|
graph(body: MemoryBody, signal?: AbortSignal): Promise<MemoryGraphSnapshot>;
|
|
19
19
|
list(body: MemoryBody, request: MemoryListRequest, signal?: AbortSignal): Promise<Insight[]>;
|
|
20
|
+
/**
|
|
21
|
+
* Each listed memory with its full content, leaving out one the server cannot read: its index
|
|
22
|
+
* can still list a file it no longer holds. When none can be read, the first failure is the
|
|
23
|
+
* answer, so a server that cannot be reached is never shown as an empty space, and a cancelled
|
|
24
|
+
* turn stops at once.
|
|
25
|
+
*/
|
|
26
|
+
private readAll;
|
|
20
27
|
remember(body: MemoryBody, request: RememberRequest, signal?: AbortSignal): Promise<JsonValue>;
|
|
28
|
+
/**
|
|
29
|
+
* Label a verified memory. Tags only describe it - its category is in the URI too - so a server
|
|
30
|
+
* without the endpoint, one that refuses or does not confirm the call, or one that is slow to
|
|
31
|
+
* answer leaves an exact memory that is just untagged. The wait is short, as for `/health`:
|
|
32
|
+
* the receipt is already true.
|
|
33
|
+
*/
|
|
34
|
+
private tag;
|
|
21
35
|
forget(body: MemoryBody, id: string, signal?: AbortSignal): Promise<JsonValue>;
|
|
22
36
|
private connection;
|
|
23
37
|
private validateUserNamespace;
|
package/lib/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { t as descriptor } from "./descriptor-1h1ZrvkP.js";
|
|
2
|
-
import { MEMORY_SPACE_PROVIDER_API_VERSION, NORMALIZED_RELEVANCE_SCORE, defineMemorySpaceProvider, defineMemorySpaceProviderDefinition } from "dsh-mnemon-source-memory-spaces/provider-sdk";
|
|
2
|
+
import { CATEGORIES, MEMORY_SPACE_PROVIDER_API_VERSION, NORMALIZED_RELEVANCE_SCORE, defineMemorySpaceProvider, defineMemorySpaceProviderDefinition } from "dsh-mnemon-source-memory-spaces/provider-sdk";
|
|
3
3
|
import { randomUUID } from "node:crypto";
|
|
4
4
|
//#region src/driver.ts
|
|
5
5
|
function object(value) {
|
|
@@ -11,6 +11,12 @@ function string(value) {
|
|
|
11
11
|
function number(value) {
|
|
12
12
|
return typeof value === "number" && Number.isFinite(value) ? value : void 0;
|
|
13
13
|
}
|
|
14
|
+
/** The categories Mnemon writes; anything else is stored, and read back, as general. */
|
|
15
|
+
const CATEGORY_NAMES = new Set(CATEGORIES);
|
|
16
|
+
function categoryOf(value) {
|
|
17
|
+
const category = string(value)?.trim().toLowerCase();
|
|
18
|
+
return category !== void 0 && CATEGORY_NAMES.has(category) ? category : "general";
|
|
19
|
+
}
|
|
14
20
|
const MEMORY_FOLDERS = {
|
|
15
21
|
preference: "preferences",
|
|
16
22
|
insight: "experiences",
|
|
@@ -19,11 +25,18 @@ const MEMORY_FOLDERS = {
|
|
|
19
25
|
fact: "entities",
|
|
20
26
|
general: "entities"
|
|
21
27
|
};
|
|
28
|
+
/**
|
|
29
|
+
* The slug's share of a file name, which Linux caps at 255 bytes: the stamp, the longest
|
|
30
|
+
* category, the UUID and the separators take 66, so 48 characters of four bytes would not fit.
|
|
31
|
+
*/
|
|
32
|
+
const SLUG_BYTES = 180;
|
|
22
33
|
function memoryUri(root, category, content) {
|
|
23
34
|
const folder = Object.hasOwn(MEMORY_FOLDERS, category) ? MEMORY_FOLDERS[category] : "entities";
|
|
24
35
|
const firstLine = content.split("\n").find((line) => line.trim().length > 0) ?? "memory";
|
|
25
|
-
const
|
|
26
|
-
|
|
36
|
+
const characters = Array.from(firstLine.replace(/^#+\s*/u, "").replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/gu, "")).slice(0, 48);
|
|
37
|
+
while (Buffer.byteLength(characters.join("").toLowerCase()) > SLUG_BYTES) characters.pop();
|
|
38
|
+
const slug = characters.join("").toLowerCase() || "memory";
|
|
39
|
+
return `${root}/${folder}/${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/gu, "").slice(0, 14)}-${slug}_${category}-${randomUUID()}.md`;
|
|
27
40
|
}
|
|
28
41
|
function safeUser(user) {
|
|
29
42
|
return /^[a-zA-Z0-9_.@-]+$/u.test(user) && user !== "." && user !== ".." && (user.match(/@/gu)?.length ?? 0) <= 1;
|
|
@@ -45,9 +58,27 @@ function queueFailed(value) {
|
|
|
45
58
|
return (number(queue?.error_count) ?? 0) > 0 || Array.isArray(queue?.errors) && queue.errors.length > 0;
|
|
46
59
|
});
|
|
47
60
|
}
|
|
48
|
-
|
|
61
|
+
/** What a folder holds, for files written before the category was in the name or by OpenViking itself. */
|
|
62
|
+
const FOLDER_CATEGORIES = {
|
|
63
|
+
preferences: "preference",
|
|
64
|
+
experiences: "insight",
|
|
65
|
+
events: "context",
|
|
66
|
+
entities: "fact"
|
|
67
|
+
};
|
|
68
|
+
/** The category in the file name Mnemon wrote, else one the server reports, else the folder's. */
|
|
69
|
+
function categoryFromUri(uri, reported) {
|
|
70
|
+
const named = /_([a-z]+)-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.md$/u.exec(uri)?.[1];
|
|
71
|
+
if (named !== void 0 && CATEGORY_NAMES.has(named)) return named;
|
|
72
|
+
const stated = string(reported);
|
|
73
|
+
if (stated !== void 0 && CATEGORY_NAMES.has(stated)) return stated;
|
|
49
74
|
const marker = "/memories/";
|
|
50
|
-
|
|
75
|
+
const folder = (uri.includes(marker) ? uri.slice(uri.indexOf(marker) + 10) : "").split("/")[0] ?? "";
|
|
76
|
+
return Object.hasOwn(FOLDER_CATEGORIES, folder) ? FOLDER_CATEGORIES[folder] : "general";
|
|
77
|
+
}
|
|
78
|
+
/** Whether the server turned the request down as sent, so it wrote nothing: not a timeout or a server fault. */
|
|
79
|
+
function refused(error) {
|
|
80
|
+
const status = error?.status;
|
|
81
|
+
return typeof status === "number" && status >= 400 && status < 500 && status !== 408 && status !== 409;
|
|
51
82
|
}
|
|
52
83
|
var OpenVikingProvider = class {
|
|
53
84
|
memorySpaces;
|
|
@@ -146,15 +177,16 @@ var OpenVikingProvider = class {
|
|
|
146
177
|
id: uri,
|
|
147
178
|
externalUri: uri,
|
|
148
179
|
content: string(item?.overview) ?? string(item?.abstract) ?? uri,
|
|
149
|
-
category:
|
|
180
|
+
category: categoryFromUri(uri, item?.category),
|
|
150
181
|
source: "external",
|
|
151
182
|
...score === void 0 ? {} : { score }
|
|
152
183
|
}];
|
|
153
184
|
}).slice(0, request.limit);
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
185
|
+
const { read, skipped } = await this.readAll(body, matches, signal);
|
|
186
|
+
return {
|
|
187
|
+
results: read,
|
|
188
|
+
...skipped === 0 ? {} : { hint: `${skipped} OpenViking ${skipped === 1 ? "result" : "results"} could not be read and ${skipped === 1 ? "was" : "were"} left out; the server's index can list a file it no longer holds.` }
|
|
189
|
+
};
|
|
158
190
|
}
|
|
159
191
|
async graph(body, signal) {
|
|
160
192
|
return {
|
|
@@ -184,39 +216,67 @@ var OpenVikingProvider = class {
|
|
|
184
216
|
uri
|
|
185
217
|
}];
|
|
186
218
|
}).slice(0, limit);
|
|
187
|
-
|
|
188
|
-
|
|
219
|
+
const { read } = await this.readAll(body, files.map(({ item, uri }) => ({
|
|
220
|
+
id: uri,
|
|
221
|
+
item
|
|
222
|
+
})), signal);
|
|
223
|
+
return read.map(({ item, id, content }) => {
|
|
189
224
|
const createdAt = string(item.modTime);
|
|
190
225
|
return {
|
|
191
|
-
id
|
|
192
|
-
externalUri:
|
|
226
|
+
id,
|
|
227
|
+
externalUri: id,
|
|
193
228
|
content,
|
|
194
|
-
category: categoryFromUri(
|
|
229
|
+
category: categoryFromUri(id),
|
|
195
230
|
source: "external",
|
|
196
231
|
...createdAt === void 0 ? {} : { createdAt }
|
|
197
232
|
};
|
|
198
|
-
})
|
|
233
|
+
});
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* Each listed memory with its full content, leaving out one the server cannot read: its index
|
|
237
|
+
* can still list a file it no longer holds. When none can be read, the first failure is the
|
|
238
|
+
* answer, so a server that cannot be reached is never shown as an empty space, and a cancelled
|
|
239
|
+
* turn stops at once.
|
|
240
|
+
*/
|
|
241
|
+
async readAll(body, items, signal) {
|
|
242
|
+
const settled = await Promise.allSettled(items.map(async (item) => ({
|
|
243
|
+
...item,
|
|
244
|
+
content: await this.readContent(body, item.id, signal)
|
|
245
|
+
})));
|
|
246
|
+
signal?.throwIfAborted();
|
|
247
|
+
const read = settled.flatMap((outcome) => outcome.status === "fulfilled" ? [outcome.value] : []);
|
|
248
|
+
const failed = settled.find((outcome) => outcome.status === "rejected");
|
|
249
|
+
if (read.length === 0 && failed !== void 0) throw failed.reason;
|
|
250
|
+
return {
|
|
251
|
+
read,
|
|
252
|
+
skipped: settled.length - read.length
|
|
253
|
+
};
|
|
199
254
|
}
|
|
200
255
|
async remember(body, request, signal) {
|
|
201
256
|
const root = await this.memoryRoot(body, signal);
|
|
202
|
-
const category =
|
|
257
|
+
const category = categoryOf(request.category);
|
|
203
258
|
const uri = memoryUri(root, category, request.content);
|
|
204
259
|
const tags = ["source=mnemon", `category=${category}`];
|
|
205
260
|
const importance = number(request.importance);
|
|
206
261
|
if (importance !== void 0) tags.push(`importance=${importance}`);
|
|
207
262
|
const writtenBytes = Buffer.byteLength(request.content, "utf8");
|
|
263
|
+
let written;
|
|
208
264
|
try {
|
|
209
|
-
|
|
265
|
+
written = object(await this.request(body, "/api/v1/content/write", {
|
|
210
266
|
method: "POST",
|
|
211
267
|
body: JSON.stringify({
|
|
212
268
|
uri,
|
|
213
269
|
content: request.content,
|
|
214
270
|
mode: "create",
|
|
215
271
|
wait: true,
|
|
216
|
-
timeout: this.requestTimeoutMs / 1e3
|
|
217
|
-
tags
|
|
272
|
+
timeout: this.requestTimeoutMs / 1e3
|
|
218
273
|
})
|
|
219
274
|
}, { signal }));
|
|
275
|
+
} catch (error) {
|
|
276
|
+
if (refused(error)) throw new Error(`OpenViking refused the write at ${uri}; nothing was stored. ${error instanceof Error ? error.message : String(error)}`, { cause: error });
|
|
277
|
+
throw new Error(`OpenViking write was not verified at ${uri}; remote content may remain. Inspect this URI before retrying. ${error instanceof Error ? error.message : String(error)}`, { cause: error });
|
|
278
|
+
}
|
|
279
|
+
try {
|
|
220
280
|
if (written?.uri !== uri || written.content_updated !== true || written.written_bytes !== writtenBytes || written.mode !== "create" || written.context_type !== "memory" || written.vector_status !== "complete" || !["complete", "skipped"].includes(String(written.semantic_status)) || queueFailed(written.queue_status)) throw new Error("content API did not confirm this exact memory and completed indexing");
|
|
221
281
|
if (await this.readContent(body, uri, signal) !== request.content) throw new Error("stored content does not match the requested text");
|
|
222
282
|
signal?.throwIfAborted();
|
|
@@ -231,9 +291,33 @@ var OpenVikingProvider = class {
|
|
|
231
291
|
externalUri: uri,
|
|
232
292
|
summary: `OpenViking stored the memory at ${uri} (category ${category}).`,
|
|
233
293
|
writtenBytes,
|
|
234
|
-
vectorStatus: "complete"
|
|
294
|
+
vectorStatus: "complete",
|
|
295
|
+
tagsApplied: await this.tag(body, uri, tags, signal)
|
|
235
296
|
};
|
|
236
297
|
}
|
|
298
|
+
/**
|
|
299
|
+
* Label a verified memory. Tags only describe it - its category is in the URI too - so a server
|
|
300
|
+
* without the endpoint, one that refuses or does not confirm the call, or one that is slow to
|
|
301
|
+
* answer leaves an exact memory that is just untagged. The wait is short, as for `/health`:
|
|
302
|
+
* the receipt is already true.
|
|
303
|
+
*/
|
|
304
|
+
async tag(body, uri, tags, signal) {
|
|
305
|
+
try {
|
|
306
|
+
return object(await this.request(body, "/api/v1/content/set_tags", {
|
|
307
|
+
method: "POST",
|
|
308
|
+
body: JSON.stringify({
|
|
309
|
+
uri,
|
|
310
|
+
tags,
|
|
311
|
+
mode: "replace"
|
|
312
|
+
})
|
|
313
|
+
}, {
|
|
314
|
+
signal,
|
|
315
|
+
timeoutMs: Math.min(this.requestTimeoutMs, 5e3)
|
|
316
|
+
}))?.tags_updated === true;
|
|
317
|
+
} catch {
|
|
318
|
+
return false;
|
|
319
|
+
}
|
|
320
|
+
}
|
|
237
321
|
async forget(body, id, signal) {
|
|
238
322
|
const root = await this.memoryRoot(body, signal);
|
|
239
323
|
const uri = id.trim();
|
|
@@ -324,7 +408,7 @@ var OpenVikingProvider = class {
|
|
|
324
408
|
const envelope = await response.json().catch(() => ({}));
|
|
325
409
|
if (!response.ok || envelope.status === "error") {
|
|
326
410
|
const trace = envelope.error?.trace_id ?? envelope.trace_id;
|
|
327
|
-
throw new Error(`${envelope.error?.message ?? `OpenViking HTTP ${response.status}`}${trace === void 0 ? "" : ` (trace ${trace})`}`);
|
|
411
|
+
throw Object.assign(/* @__PURE__ */ new Error(`${envelope.error?.message ?? `OpenViking HTTP ${response.status}`}${trace === void 0 ? "" : ` (trace ${trace})`}`), { status: response.status });
|
|
328
412
|
}
|
|
329
413
|
return envelope.result ?? envelope;
|
|
330
414
|
} catch (error) {
|
|
@@ -344,7 +428,7 @@ const definition = defineMemorySpaceProviderDefinition({
|
|
|
344
428
|
kind: "provider",
|
|
345
429
|
typeId: descriptor.id,
|
|
346
430
|
packageName: "dsh-mnemon-provider-openviking",
|
|
347
|
-
version: "0.5.
|
|
431
|
+
version: "0.5.8",
|
|
348
432
|
label: descriptor.label,
|
|
349
433
|
icon: descriptor.icon,
|
|
350
434
|
summary: descriptor.summary,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-mnemon-provider-openviking",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.8",
|
|
4
4
|
"description": "OpenViking Provider child for the Memory Spaces Source.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
36
|
"@types/node": "^22.0.0",
|
|
37
|
-
"dsh-mnemon-source-memory-spaces": "^0.5.
|
|
37
|
+
"dsh-mnemon-source-memory-spaces": "^0.5.19",
|
|
38
38
|
"tsdown": "^0.22.0",
|
|
39
39
|
"typescript": "^5.9.0",
|
|
40
40
|
"vitest": "^3.2.0"
|