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 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"`, `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
+
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: import("dsh-mnemon-source-memory-spaces/provider-sdk").ProviderScoreSemantics;
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 { 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, 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,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
- 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;
54
85
  id = "openviking";
55
- scoreSemantics = NORMALIZED_RELEVANCE_SCORE;
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
- const matches = (Array.isArray(root?.memories) ? root.memories : []).flatMap((value) => {
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
- const score = number(item?.score);
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: string(item?.category) ?? categoryFromUri(uri),
195
+ category: categoryFromUri(uri, item?.category),
150
196
  source: "external",
151
197
  ...score === void 0 ? {} : { score }
152
198
  }];
153
- }).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
- }))) };
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
- return Promise.all(files.map(async ({ item, uri }) => {
188
- const content = await this.readContent(body, uri, signal);
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: uri,
192
- externalUri: uri,
241
+ id,
242
+ externalUri: id,
193
243
  content,
194
- category: categoryFromUri(uri),
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 = string(request.category) ?? "general";
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
- const written = object(await this.request(body, "/api/v1/content/write", {
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
- 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");
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.7",
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: "normalized-relevance"
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.7",
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.11",
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"