dsh-mnemon-provider-openviking 0.5.7 → 0.5.9
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 +6 -2
- package/lib/index.d.ts +17 -1
- package/lib/index.js +130 -32
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,9 +2,13 @@
|
|
|
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
|
+
|
|
9
|
+
## Search
|
|
10
|
+
|
|
11
|
+
OpenViking `keyword` search uses `POST /api/v1/search/grep` for case-insensitive literal text, with regex metacharacters escaped. It scopes `uri` to the selected user memory root and bounds `node_limit` to the Source search budget (1–50; direct adapter default 10). Repeated lines in one file count as one result; only safe in-root memory Markdown files are hydrated through `content/read`, and no relevance score is invented. `smart`/`basic` keep `search/find`. A missing grep endpoint or invalid response is reported as an error rather than a semantic fallback; arbitrary regular-expression input is not exposed. The request uses the common fields of OpenViking 0.4.16 and 0.5.1.1.
|
|
8
12
|
|
|
9
13
|
## Use
|
|
10
14
|
|
package/lib/index.d.ts
CHANGED
|
@@ -8,7 +8,9 @@ interface OpenVikingProviderOptions {
|
|
|
8
8
|
declare class OpenVikingProvider implements MemoryProviderAdapter {
|
|
9
9
|
private readonly memorySpaces;
|
|
10
10
|
readonly id: "openviking";
|
|
11
|
-
readonly scoreSemantics:
|
|
11
|
+
readonly scoreSemantics: Readonly<{
|
|
12
|
+
kind: "provider-native";
|
|
13
|
+
}>;
|
|
12
14
|
private readonly requestFetch;
|
|
13
15
|
private readonly requestTimeoutMs;
|
|
14
16
|
constructor(memorySpaces: MemorySpaceAuthority, options?: OpenVikingProviderOptions);
|
|
@@ -17,7 +19,21 @@ declare class OpenVikingProvider implements MemoryProviderAdapter {
|
|
|
17
19
|
search(body: MemoryBody, request: SearchRequest, signal?: AbortSignal): Promise<ProviderSearchResult>;
|
|
18
20
|
graph(body: MemoryBody, signal?: AbortSignal): Promise<MemoryGraphSnapshot>;
|
|
19
21
|
list(body: MemoryBody, request: MemoryListRequest, signal?: AbortSignal): Promise<Insight[]>;
|
|
22
|
+
/**
|
|
23
|
+
* Each listed memory with its full content, leaving out one the server cannot read: its index
|
|
24
|
+
* can still list a file it no longer holds. When none can be read, the first failure is the
|
|
25
|
+
* answer, so a server that cannot be reached is never shown as an empty space, and a cancelled
|
|
26
|
+
* turn stops at once.
|
|
27
|
+
*/
|
|
28
|
+
private readAll;
|
|
20
29
|
remember(body: MemoryBody, request: RememberRequest, signal?: AbortSignal): Promise<JsonValue>;
|
|
30
|
+
/**
|
|
31
|
+
* Label a verified memory. Tags only describe it - its category is in the URI too - so a server
|
|
32
|
+
* without the endpoint, one that refuses or does not confirm the call, or one that is slow to
|
|
33
|
+
* answer leaves an exact memory that is just untagged. The wait is short, as for `/health`:
|
|
34
|
+
* the receipt is already true.
|
|
35
|
+
*/
|
|
36
|
+
private tag;
|
|
21
37
|
forget(body: MemoryBody, id: string, signal?: AbortSignal): Promise<JsonValue>;
|
|
22
38
|
private connection;
|
|
23
39
|
private validateUserNamespace;
|
package/lib/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { t as descriptor } from "./descriptor-1h1ZrvkP.js";
|
|
2
|
-
import {
|
|
2
|
+
import { CATEGORIES, MEMORY_SPACE_PROVIDER_API_VERSION, 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,14 +58,32 @@ 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;
|
|
54
85
|
id = "openviking";
|
|
55
|
-
scoreSemantics =
|
|
86
|
+
scoreSemantics = Object.freeze({ kind: "provider-native" });
|
|
56
87
|
requestFetch;
|
|
57
88
|
requestTimeoutMs;
|
|
58
89
|
constructor(memorySpaces, options = {}) {
|
|
@@ -127,34 +158,50 @@ var OpenVikingProvider = class {
|
|
|
127
158
|
}
|
|
128
159
|
}
|
|
129
160
|
async search(body, request, signal) {
|
|
161
|
+
const keyword = request.mode === "keyword";
|
|
162
|
+
signal?.throwIfAborted();
|
|
163
|
+
if (keyword && request.query.trim() === "") return { results: [] };
|
|
164
|
+
const limit = keyword ? Math.min(50, Math.max(1, Math.floor(number(request.limit) ?? 10))) : request.limit;
|
|
130
165
|
const memoryRoot = await this.memoryRoot(body, signal);
|
|
131
|
-
const root = object(await this.request(body, "/api/v1/search/find", {
|
|
166
|
+
const root = object(await this.request(body, keyword ? "/api/v1/search/grep" : "/api/v1/search/find", {
|
|
132
167
|
method: "POST",
|
|
133
|
-
body: JSON.stringify({
|
|
168
|
+
body: JSON.stringify(keyword ? {
|
|
169
|
+
uri: memoryRoot,
|
|
170
|
+
pattern: request.query.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"),
|
|
171
|
+
case_insensitive: true,
|
|
172
|
+
node_limit: limit
|
|
173
|
+
} : {
|
|
134
174
|
query: request.query,
|
|
135
175
|
target_uri: memoryRoot,
|
|
136
176
|
context_type: ["memory"],
|
|
137
177
|
limit: request.limit
|
|
138
178
|
})
|
|
139
179
|
}, { signal }));
|
|
140
|
-
|
|
180
|
+
if (keyword && !Array.isArray(root?.matches)) throw new Error("OpenViking keyword search did not return matches");
|
|
181
|
+
const values = keyword ? root?.matches : root?.memories;
|
|
182
|
+
const entries = Array.isArray(values) ? values : [];
|
|
183
|
+
const seen = /* @__PURE__ */ new Set();
|
|
184
|
+
const matches = entries.flatMap((value) => {
|
|
141
185
|
const item = object(value);
|
|
142
186
|
const uri = string(item?.uri);
|
|
143
187
|
if (uri === void 0 || !isMemoryFile(uri, memoryRoot)) return [];
|
|
144
|
-
|
|
188
|
+
if (keyword && seen.has(uri)) return [];
|
|
189
|
+
seen.add(uri);
|
|
190
|
+
const score = keyword ? void 0 : number(item?.score);
|
|
145
191
|
return [{
|
|
146
192
|
id: uri,
|
|
147
193
|
externalUri: uri,
|
|
148
194
|
content: string(item?.overview) ?? string(item?.abstract) ?? uri,
|
|
149
|
-
category:
|
|
195
|
+
category: categoryFromUri(uri, item?.category),
|
|
150
196
|
source: "external",
|
|
151
197
|
...score === void 0 ? {} : { score }
|
|
152
198
|
}];
|
|
153
|
-
}).slice(0,
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
199
|
+
}).slice(0, limit);
|
|
200
|
+
const { read, skipped } = await this.readAll(body, matches, signal);
|
|
201
|
+
return {
|
|
202
|
+
results: read,
|
|
203
|
+
...skipped === 0 ? {} : { hint: `${skipped} OpenViking ${skipped === 1 ? "result" : "results"} could not be read and ${skipped === 1 ? "was" : "were"} left out; the server can list a file it no longer holds.` }
|
|
204
|
+
};
|
|
158
205
|
}
|
|
159
206
|
async graph(body, signal) {
|
|
160
207
|
return {
|
|
@@ -184,40 +231,67 @@ var OpenVikingProvider = class {
|
|
|
184
231
|
uri
|
|
185
232
|
}];
|
|
186
233
|
}).slice(0, limit);
|
|
187
|
-
|
|
188
|
-
|
|
234
|
+
const { read } = await this.readAll(body, files.map(({ item, uri }) => ({
|
|
235
|
+
id: uri,
|
|
236
|
+
item
|
|
237
|
+
})), signal);
|
|
238
|
+
return read.map(({ item, id, content }) => {
|
|
189
239
|
const createdAt = string(item.modTime);
|
|
190
240
|
return {
|
|
191
|
-
id
|
|
192
|
-
externalUri:
|
|
241
|
+
id,
|
|
242
|
+
externalUri: id,
|
|
193
243
|
content,
|
|
194
|
-
category: categoryFromUri(
|
|
244
|
+
category: categoryFromUri(id),
|
|
195
245
|
source: "external",
|
|
196
246
|
...createdAt === void 0 ? {} : { createdAt }
|
|
197
247
|
};
|
|
198
|
-
})
|
|
248
|
+
});
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* Each listed memory with its full content, leaving out one the server cannot read: its index
|
|
252
|
+
* can still list a file it no longer holds. When none can be read, the first failure is the
|
|
253
|
+
* answer, so a server that cannot be reached is never shown as an empty space, and a cancelled
|
|
254
|
+
* turn stops at once.
|
|
255
|
+
*/
|
|
256
|
+
async readAll(body, items, signal) {
|
|
257
|
+
const settled = await Promise.allSettled(items.map(async (item) => ({
|
|
258
|
+
...item,
|
|
259
|
+
content: await this.readContent(body, item.id, signal)
|
|
260
|
+
})));
|
|
261
|
+
signal?.throwIfAborted();
|
|
262
|
+
const read = settled.flatMap((outcome) => outcome.status === "fulfilled" ? [outcome.value] : []);
|
|
263
|
+
const failed = settled.find((outcome) => outcome.status === "rejected");
|
|
264
|
+
if (read.length === 0 && failed !== void 0) throw failed.reason;
|
|
265
|
+
return {
|
|
266
|
+
read,
|
|
267
|
+
skipped: settled.length - read.length
|
|
268
|
+
};
|
|
199
269
|
}
|
|
200
270
|
async remember(body, request, signal) {
|
|
201
271
|
const root = await this.memoryRoot(body, signal);
|
|
202
|
-
const category =
|
|
272
|
+
const category = categoryOf(request.category);
|
|
203
273
|
const uri = memoryUri(root, category, request.content);
|
|
204
274
|
const tags = ["source=mnemon", `category=${category}`];
|
|
205
275
|
const importance = number(request.importance);
|
|
206
276
|
if (importance !== void 0) tags.push(`importance=${importance}`);
|
|
207
277
|
const writtenBytes = Buffer.byteLength(request.content, "utf8");
|
|
278
|
+
let written;
|
|
208
279
|
try {
|
|
209
|
-
|
|
280
|
+
written = object(await this.request(body, "/api/v1/content/write", {
|
|
210
281
|
method: "POST",
|
|
211
282
|
body: JSON.stringify({
|
|
212
283
|
uri,
|
|
213
284
|
content: request.content,
|
|
214
285
|
mode: "create",
|
|
215
|
-
wait: true
|
|
216
|
-
timeout: this.requestTimeoutMs / 1e3,
|
|
217
|
-
tags
|
|
286
|
+
wait: true
|
|
218
287
|
})
|
|
219
288
|
}, { signal }));
|
|
220
|
-
|
|
289
|
+
} catch (error) {
|
|
290
|
+
if (refused(error)) throw new Error(`OpenViking refused the write at ${uri}; nothing was stored. ${error instanceof Error ? error.message : String(error)}`, { cause: error });
|
|
291
|
+
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 });
|
|
292
|
+
}
|
|
293
|
+
try {
|
|
294
|
+
if (written?.uri !== uri || written.content_updated !== true || (number(written.written_bytes) ?? -1) < 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
295
|
if (await this.readContent(body, uri, signal) !== request.content) throw new Error("stored content does not match the requested text");
|
|
222
296
|
signal?.throwIfAborted();
|
|
223
297
|
} catch (error) {
|
|
@@ -231,9 +305,33 @@ var OpenVikingProvider = class {
|
|
|
231
305
|
externalUri: uri,
|
|
232
306
|
summary: `OpenViking stored the memory at ${uri} (category ${category}).`,
|
|
233
307
|
writtenBytes,
|
|
234
|
-
vectorStatus: "complete"
|
|
308
|
+
vectorStatus: "complete",
|
|
309
|
+
tagsApplied: await this.tag(body, uri, tags, signal)
|
|
235
310
|
};
|
|
236
311
|
}
|
|
312
|
+
/**
|
|
313
|
+
* Label a verified memory. Tags only describe it - its category is in the URI too - so a server
|
|
314
|
+
* without the endpoint, one that refuses or does not confirm the call, or one that is slow to
|
|
315
|
+
* answer leaves an exact memory that is just untagged. The wait is short, as for `/health`:
|
|
316
|
+
* the receipt is already true.
|
|
317
|
+
*/
|
|
318
|
+
async tag(body, uri, tags, signal) {
|
|
319
|
+
try {
|
|
320
|
+
return object(await this.request(body, "/api/v1/content/set_tags", {
|
|
321
|
+
method: "POST",
|
|
322
|
+
body: JSON.stringify({
|
|
323
|
+
uri,
|
|
324
|
+
tags,
|
|
325
|
+
mode: "replace"
|
|
326
|
+
})
|
|
327
|
+
}, {
|
|
328
|
+
signal,
|
|
329
|
+
timeoutMs: Math.min(this.requestTimeoutMs, 5e3)
|
|
330
|
+
}))?.tags_updated === true;
|
|
331
|
+
} catch {
|
|
332
|
+
return false;
|
|
333
|
+
}
|
|
334
|
+
}
|
|
237
335
|
async forget(body, id, signal) {
|
|
238
336
|
const root = await this.memoryRoot(body, signal);
|
|
239
337
|
const uri = id.trim();
|
|
@@ -324,7 +422,7 @@ var OpenVikingProvider = class {
|
|
|
324
422
|
const envelope = await response.json().catch(() => ({}));
|
|
325
423
|
if (!response.ok || envelope.status === "error") {
|
|
326
424
|
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})`}`);
|
|
425
|
+
throw Object.assign(/* @__PURE__ */ new Error(`${envelope.error?.message ?? `OpenViking HTTP ${response.status}`}${trace === void 0 ? "" : ` (trace ${trace})`}`), { status: response.status });
|
|
328
426
|
}
|
|
329
427
|
return envelope.result ?? envelope;
|
|
330
428
|
} catch (error) {
|
|
@@ -344,7 +442,7 @@ const definition = defineMemorySpaceProviderDefinition({
|
|
|
344
442
|
kind: "provider",
|
|
345
443
|
typeId: descriptor.id,
|
|
346
444
|
packageName: "dsh-mnemon-provider-openviking",
|
|
347
|
-
version: "0.5.
|
|
445
|
+
version: "0.5.9",
|
|
348
446
|
label: descriptor.label,
|
|
349
447
|
icon: descriptor.icon,
|
|
350
448
|
summary: descriptor.summary,
|
|
@@ -355,7 +453,7 @@ const definition = defineMemorySpaceProviderDefinition({
|
|
|
355
453
|
capabilities: descriptor.capabilities,
|
|
356
454
|
fields: descriptor.fields,
|
|
357
455
|
secrets: descriptor.fields.filter((field) => field.input === "secret").map((field) => field.key),
|
|
358
|
-
scoreSemantics: "
|
|
456
|
+
scoreSemantics: "provider-native"
|
|
359
457
|
},
|
|
360
458
|
create: (context) => new OpenVikingProvider(context.memorySpaces ?? context.memoryBodies, { requestTimeoutMs: context.config.timeoutMs })
|
|
361
459
|
});
|
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.9",
|
|
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.23",
|
|
38
38
|
"tsdown": "^0.22.0",
|
|
39
39
|
"typescript": "^5.9.0",
|
|
40
40
|
"vitest": "^3.2.0"
|