@frockbot/plugin-memory 0.3.14 → 0.3.15

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@frockbot/plugin-memory",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "private": false,
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./agent": "./src/agent.ts",
+    "./chunk-index": "./src/chunk-index.ts",
     "./manifest": "./src/manifest.ts",
     "./projects": "./src/projects.ts",
     "./roots": "./src/roots.ts",
@@ -22,10 +23,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-agent-loop": "0.3.14",
-    "@frockbot/kernel-contracts": "0.3.14",
-    "@frockbot/secret-shapes": "0.3.14",
-    "@frockbot/workspace-store": "0.3.14",
+    "@frockbot/kernel-agent-loop": "0.3.15",
+    "@frockbot/kernel-contracts": "0.3.15",
+    "@frockbot/secret-shapes": "0.3.15",
+    "@frockbot/workspace-store": "0.3.15",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/agent.ts

@@ -39,9 +39,11 @@ import {
   buildMemoryIndexV1,
   emptyMemoryIndexV1,
   embedMemoryIndexV1,
+  memoryChunkVectorIdV1,
   updateMemoryIndexV1,
   type MemoryIndexV1,
 } from "./indexer.js";
+import type { MemoryChunkIndexWriterV1 } from "./chunk-index.js";
 import {
   parseProjectDocumentV1,
   projectDocumentPathV1,
@@ -99,6 +101,8 @@ export interface MemoryRuntimeHostV1 {
   projects?: MemoryProjectsV1;
   /** Optional derived-index bindings; Memory is complete without them. */
   vectorize?: MemoryVectorIndex;
+  /** Durable ledger for vectors derived from this Bot's own Memory root. */
+  chunkIndex?: MemoryChunkIndexWriterV1;
   embed?: EmbedMemory;
   ai?: MemoryAiBinding;
   embeddingModel?: string;
@@ -387,6 +391,19 @@ export class MemoryProjection {
     const embed = memoryEmbedderV1(this.#host);
     if (!embed || !this.#host.vectorize) return;
     try {
+      if (this.#host.chunkIndex) {
+        const ownVectorIds = await Promise.all(
+          this.#index.chunks
+            .filter(
+              (chunk) =>
+                chunk.scope === "bot" && chunk.botId === this.#host.owner.botId,
+            )
+            .map(memoryChunkVectorIdV1),
+        );
+        // Intent before effect: a crash after this write and before/during the
+        // upsert leaves at worst an id whose delete is a harmless no-op.
+        await this.#host.chunkIndex.record(ownVectorIds);
+      }
       await embedMemoryIndexV1(this.#index, embed, this.#host.vectorize);
     } catch (error) {
       // Embeddings are derived from the files and rebuildable; losing them

package/src/chunk-index.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeMemoryChunkIndexEntryV1,
+  memoryChunkIndexEntriesV1,
+  memoryChunkIndexKeyV1,
+} from "./chunk-index.js";
+
+describe("the durable Memory chunk index", () => {
+  test("deduplicates ids and round-trips each exact stored entry", () => {
+    const entries = memoryChunkIndexEntriesV1([
+      "chunk/a",
+      "chunk/a",
+      "chunk b",
+    ]);
+    expect(Object.keys(entries)).toEqual([
+      memoryChunkIndexKeyV1("chunk/a"),
+      memoryChunkIndexKeyV1("chunk b"),
+    ]);
+    for (const [key, value] of Object.entries(entries)) {
+      expect(decodeMemoryChunkIndexEntryV1(key, value)).toEqual(value);
+    }
+  });
+
+  test("refuses a record whose key names a different vector", () => {
+    expect(() =>
+      decodeMemoryChunkIndexEntryV1(memoryChunkIndexKeyV1("one"), {
+        schemaVersion: 1,
+        vectorId: "two",
+      }),
+    ).toThrow("does not match");
+  });
+});

package/src/chunk-index.ts

@@ -0,0 +1,62 @@
+/**
+ * The Bot-scoped ledger of Vectorize ids produced from its own Memory root.
+ *
+ * One id per key makes the ledger its own durable deletion cursor: a purge
+ * removes a key only after Vectorize accepted the matching delete. A retry
+ * after eviction therefore either advances to the next key or harmlessly
+ * repeats an id whose external delete succeeded before the local commit.
+ */
+export const MEMORY_CHUNK_INDEX_PREFIX_V1 = "memory:chunk-index:v1:";
+
+export interface MemoryChunkIndexEntryV1 {
+  schemaVersion: 1;
+  vectorId: string;
+}
+
+/** The narrow durable seam used before Bot-Memory vectors are upserted. */
+export interface MemoryChunkIndexWriterV1 {
+  record(vectorIds: readonly string[]): Promise<void>;
+}
+
+export function memoryChunkIndexKeyV1(vectorId: string): string {
+  if (!vectorId || new TextEncoder().encode(vectorId).byteLength > 64) {
+    throw new Error("Memory vector id must contain between 1 and 64 bytes");
+  }
+  return `${MEMORY_CHUNK_INDEX_PREFIX_V1}${encodeURIComponent(vectorId)}`;
+}
+
+export function decodeMemoryChunkIndexEntryV1(
+  key: string,
+  input: unknown,
+): MemoryChunkIndexEntryV1 {
+  if (
+    typeof input !== "object" ||
+    input === null ||
+    Array.isArray(input) ||
+    Reflect.get(input, "schemaVersion") !== 1 ||
+    typeof Reflect.get(input, "vectorId") !== "string" ||
+    Object.keys(input).some(
+      (field) => field !== "schemaVersion" && field !== "vectorId",
+    )
+  ) {
+    throw new Error("Stored Memory chunk index entry is invalid");
+  }
+  const vectorId = Reflect.get(input, "vectorId") as string;
+  if (memoryChunkIndexKeyV1(vectorId) !== key) {
+    throw new Error(
+      "Stored Memory chunk index key does not match its vector id",
+    );
+  }
+  return { schemaVersion: 1, vectorId };
+}
+
+export function memoryChunkIndexEntriesV1(
+  vectorIds: readonly string[],
+): Record<string, MemoryChunkIndexEntryV1> {
+  return Object.fromEntries(
+    [...new Set(vectorIds)].map((vectorId) => [
+      memoryChunkIndexKeyV1(vectorId),
+      { schemaVersion: 1, vectorId },
+    ]),
+  );
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./agent.js";
 export * from "./chunker.js";
+export * from "./chunk-index.js";
 export * from "./documents.js";
 export * from "./embeddings.js";
 export * from "./facts.js";