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 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"`, `wait: true`, and tags. 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.
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. The error includes the requested URI because remote content may remain; inspect it before retrying. Existing memories remain readable, and downgrading does not remove files written by this adapter.
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 slug = Array.from(firstLine.replace(/^#+\s*/u, "").replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/gu, "")).slice(0, 48).join("").toLowerCase() || "memory";
26
- return `${root}/${folder}/${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/gu, "").slice(0, 14)}-${slug}-${randomUUID()}.md`;
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
- function categoryFromUri(uri) {
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
- return (uri.includes(marker) ? uri.slice(uri.indexOf(marker) + 10) : "").split("/")[0]?.replace(/\.md$/u, "") || "general";
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: string(item?.category) ?? categoryFromUri(uri),
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
- return { results: await Promise.all(matches.map(async (item) => ({
155
- ...item,
156
- content: await this.readContent(body, item.id, signal)
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
- return Promise.all(files.map(async ({ item, uri }) => {
188
- const content = await this.readContent(body, uri, signal);
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: uri,
192
- externalUri: uri,
226
+ id,
227
+ externalUri: id,
193
228
  content,
194
- category: categoryFromUri(uri),
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 = string(request.category) ?? "general";
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
- const written = object(await this.request(body, "/api/v1/content/write", {
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.7",
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.7",
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.11",
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"