@frockbot/plugin-memory 0.3.6 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-memory",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "private": false,
   "type": "module",
   "exports": {
@@ -22,10 +22,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-agent-loop": "0.3.6",
-    "@frockbot/kernel-contracts": "0.3.6",
-    "@frockbot/secret-shapes": "0.3.6",
-    "@frockbot/workspace-store": "0.3.6",
+    "@frockbot/kernel-agent-loop": "0.3.7",
+    "@frockbot/kernel-contracts": "0.3.7",
+    "@frockbot/secret-shapes": "0.3.7",
+    "@frockbot/workspace-store": "0.3.7",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/agent.test.ts

@@ -205,7 +205,10 @@ describe("memory_forget", () => {
     );
 
     expect(result.isError).toBe(false);
-    expect(result.content).toContain("retraction");
+    // The result the model paraphrases says what happened, not how: the
+    // retraction, the shard and "newest wins" are this Package's mechanics.
+    expect(result.content).toContain("Forgotten");
+    expect(result.content).not.toContain("shard");
     const written = session.events.find(
       (event) => event.type === "memory/written",
     );

package/src/agent.ts

@@ -32,8 +32,8 @@ import type {} from "@frockbot/kernel-agent-loop/agent";
 import type { Plugin } from "cordis";
 import { createMemoryEmbedder } from "./embeddings.js";
 import {
-  listAllMemoryDocumentsV1,
-  type MemoryDocumentV1,
+  readAllMemoryDocumentsV1,
+  type MemoryDocumentListingV1,
 } from "./documents.js";
 import {
   buildMemoryIndexV1,
@@ -46,6 +46,7 @@ import {
   parseProjectDocumentV1,
   projectDocumentPathV1,
   renderProjectDocumentV1,
+  type MemoryProjectsOutcomeV1,
   type MemoryProjectsV1,
 } from "./projects.js";
 export type {
@@ -166,6 +167,15 @@ export class MemoryProjection {
   };
   #index: MemoryIndexV1 = emptyMemoryIndexV1();
   #turn: number | undefined;
+  /** This Turn's one Project-membership read, shared by injection and index. */
+  #roots:
+    | Promise<{
+        own: WorkspaceMemoryRootV1;
+        user: WorkspaceMemoryRootV1;
+        projects: MemoryProjectV1[];
+        unavailable?: string;
+      }>
+    | undefined;
 
   constructor(host: MemoryRuntimeHostV1) {
     this.#host = host;
@@ -197,6 +207,21 @@ export class MemoryProjection {
     user: WorkspaceMemoryRootV1;
     projects: MemoryProjectV1[];
     unavailable?: string;
+  }> {
+    // One membership read per Turn, shared by the injection and the index.
+    // Two calls meant two cross-Durable-Object round trips, and worse: if the
+    // second failed, `roots()` answered "no Projects" and the index silently
+    // omitted every Project document the injection had just included, with
+    // nothing recording that they disagreed.
+    this.#roots ??= this.readRoots();
+    return this.#roots;
+  }
+
+  private async readRoots(): Promise<{
+    own: WorkspaceMemoryRootV1;
+    user: WorkspaceMemoryRootV1;
+    projects: MemoryProjectV1[];
+    unavailable?: string;
   }> {
     const owner = this.#host.owner;
     const roots = {
@@ -221,6 +246,8 @@ export class MemoryProjection {
   async refresh(turn: number, session: Session): Promise<MemoryInjectionV1> {
     const store = this.#host.store;
     const owner = this.#host.owner;
+    // A new Turn reads membership again; within one Turn the read is shared.
+    this.#roots = undefined;
     const { own, user, projects, unavailable } = await this.roots();
     const ownTier = await store.read(own);
     const userTier = await store.read(user);
@@ -295,10 +322,31 @@ export class MemoryProjection {
     return this.#injection;
   }
 
-  /** Rebuilds the derived index incrementally from the current files. */
-  async reindex(): Promise<{ documentsChanged: number; chunksTotal: number }> {
-    const documents = await this.documents();
-    const update = await updateMemoryIndexV1(this.#index, documents);
+  /**
+   * Rebuilds the derived index incrementally from the current files.
+   *
+   * A listing that could not be read whole updates nothing. The indexer reads
+   * an absent document as a deleted one, so applying a short listing turned a
+   * transient object-storage blip into a permanent, silent deletion of that
+   * document's chunks — `memory_search` simply found less, with no event and
+   * no omission to say why. Keeping the previous index costs at worst one
+   * stale chunk until the next Turn.
+   */
+  async reindex(): Promise<{
+    documentsChanged: number;
+    chunksTotal: number;
+    /** True when the files could not be read whole and nothing was applied. */
+    deferred?: true;
+  }> {
+    const listing = await this.documents();
+    if (!listing.complete) {
+      return {
+        documentsChanged: 0,
+        chunksTotal: this.#index.chunks.length,
+        deferred: true,
+      };
+    }
+    const update = await updateMemoryIndexV1(this.#index, listing.documents);
     this.#index = update.index;
     await this.embed();
     return {
@@ -307,16 +355,26 @@ export class MemoryProjection {
     };
   }
 
-  /** Throws the derived index away and builds it again from the files. */
-  async rebuild(): Promise<{ chunksTotal: number }> {
-    this.#index = await buildMemoryIndexV1(await this.documents());
+  /**
+   * Throws the derived index away and builds it again from the files.
+   *
+   * An explicit rebuild on a partial listing is refused rather than half
+   * done: "rebuild the index" that quietly drops what it could not read is
+   * worse than a rebuild that says it could not run.
+   */
+  async rebuild(): Promise<{ chunksTotal: number; deferred?: true }> {
+    const listing = await this.documents();
+    if (!listing.complete) {
+      return { chunksTotal: this.#index.chunks.length, deferred: true };
+    }
+    this.#index = await buildMemoryIndexV1(listing.documents);
     await this.embed();
     return { chunksTotal: this.#index.chunks.length };
   }
 
-  private async documents(): Promise<MemoryDocumentV1[]> {
+  private async documents(): Promise<MemoryDocumentListingV1> {
     const { own, user, projects } = await this.roots();
-    return listAllMemoryDocumentsV1(this.#host.store.reads, [
+    return readAllMemoryDocumentsV1(this.#host.store.reads, [
       own,
       user,
       ...projects.map((project) =>
@@ -342,6 +400,9 @@ export class MemoryProjection {
     this.#injection = { text: "", facts: [], omissions: [], faded: [] };
     this.#index = emptyMemoryIndexV1();
     this.#turn = undefined;
+    // Membership is exactly the thing a `project_*` tool just changed, so the
+    // memoized read goes with the rest of the projection.
+    this.#roots = undefined;
   }
 }
 
@@ -607,9 +668,13 @@ export function createMemoryWriteTool(
       await session.flush();
       await projection.reindex();
       return {
+        // What the model paraphrases to the user. A path, a generation id
+        // and "it reaches your prompt on your next Turn" are this Package's
+        // mechanics, and we watched a Bot read them straight back to someone
+        // who had only said where they lived.
         content: outcome.duplicate
-          ? `That fact was already recorded in ${decoded.scope} memory; nothing changed.`
-          : `Recorded in ${decoded.scope} memory (${decoded.tier}) at ${outcome.path} as generation ${outcome.generationId}. It reaches your prompt on your next Turn.`,
+          ? `Already remembered; nothing changed.`
+          : `Remembered.`,
         isError: false,
       };
     },
@@ -678,8 +743,14 @@ export function createMemoryForgetTool(
         action: "forget",
         scope: decoded.scope,
         projectId: decoded.project ?? "",
-        tier: "log",
-        path: `${decoded.scope}/forget`,
+        // A forget is not a tier and has no path until it has run: it may
+        // rewrite the profile file, one or more log files, or write a
+        // retraction. Naming `log` and `<scope>/forget` here made the intent
+        // disagree with its own outcome — a forget of a profile fact recorded
+        // `tier: "log", path: "bot/forget"` and then `path: "profile.md"`.
+        // `pending` says plainly that the files are not known yet.
+        tier: "pending",
+        path: "",
         contentHash,
       });
       await session.flush();
@@ -732,8 +803,8 @@ export function createMemoryForgetTool(
       await projection.reindex();
       return {
         content: outcome.retracted
-          ? `That fact was recorded by another Bot, so it was not edited. A retraction is now in your own shard and newest wins, so it stops being injected on your next Turn.`
-          : `Forgotten. The line is gone from ${outcome.path}.`,
+          ? `Forgotten. Another of your Bots had recorded it too, and it will stop coming up for them as well.`
+          : `Forgotten.`,
         isError: false,
       };
     },
@@ -1003,17 +1074,46 @@ export function createProjectTools(
         }
       }
 
-      const outcome =
-        action === "create"
-          ? await host.projects.create({
-              projectId: decoded.project,
-              name: decoded.name || decoded.project,
-              description: decoded.description ?? "",
-            })
-          : action === "join"
-            ? await host.projects.join(decoded.project)
-            : await host.projects.leave(decoded.project);
+      // The descriptor above is already durable in object storage. If the
+      // membership authority now refuses or throws, the file is real, the
+      // membership is unchanged, and — before this — nothing was recorded at
+      // all, so the durable log said no Project change happened while a
+      // descriptor for it sat in R2. Whatever the answer, it is recorded.
+      let outcome: MemoryProjectsOutcomeV1;
+      try {
+        outcome =
+          action === "create"
+            ? await host.projects.create({
+                projectId: decoded.project,
+                name: decoded.name || decoded.project,
+                description: decoded.description ?? "",
+              })
+            : action === "join"
+              ? await host.projects.join(decoded.project)
+              : await host.projects.leave(decoded.project);
+      } catch (error) {
+        outcome = {
+          status: "refused",
+          reason:
+            error instanceof Error
+              ? error.message
+              : "the Project membership authority is unavailable",
+        };
+      }
       if (outcome.status !== "ok") {
+        session.append({
+          type: "memory/project-changed",
+          ...position,
+          effectId,
+          action,
+          projectId: decoded.project,
+          // Membership did not change, and the event says so by carrying the
+          // membership as it stands rather than the one that was asked for.
+          projects: (await host.projects.joined().catch(() => [])).map(
+            (project) => project.projectId,
+          ),
+        });
+        await session.flush();
         return refusal(`${name} was refused: ${outcome.reason}`);
       }
       session.append({
@@ -1030,7 +1130,7 @@ export function createProjectTools(
         content: `Projects you have joined: ${
           outcome.joined.map((project) => project.projectId).join(", ") ||
           "none"
-        }. Project memory changes reach your prompt on your next Turn.`,
+        }.`,
         isError: false,
       };
     },
@@ -1118,7 +1218,31 @@ export function createMemoryRuntimePlugin(
         // own prompt on the next Turn, which is what makes the injected block
         // and the `memory/injected` record describe the same thing.
         if (step === 1 || projection.loadedTurn() !== turn) {
-          await projection.refresh(turn, agent.session);
+          try {
+            await projection.refresh(turn, agent.session);
+          } catch (error) {
+            // Memory is remote, and a remote read that throws used to fail
+            // the whole Turn as `model-error`. A Turn with no Memory is a
+            // worse Turn; a Turn that does not happen is no Turn at all. The
+            // gap is recorded so it is visible in durable state rather than
+            // being a silent change in the Bot's behaviour.
+            agent.session.append({
+              type: "memory/injected",
+              turn,
+              sources: [],
+              facts: [],
+              omissions: [
+                {
+                  scope: "bot",
+                  reason:
+                    error instanceof Error
+                      ? error.message
+                      : "Memory could not be read for this Turn",
+                },
+              ],
+            });
+            await agent.session.flush();
+          }
         }
         return next();
       }),

package/src/documents.ts

@@ -10,6 +10,7 @@
 import type {
   MemoryScopeNameV1,
   WorkspaceMemoryRootV1,
+  WorkspacePathV1,
   WorkspaceReadsV1,
 } from "@frockbot/kernel-contracts";
 import {
@@ -17,7 +18,7 @@ import {
   memoryProjectIdOfRootV1,
   memoryScopeOfRootV1,
 } from "./roots.js";
-import { MEMORY_MAX_FILES_PER_TIER, MEMORY_MAX_LIST_PAGES } from "./store.js";
+import { MEMORY_MAX_LIST_PAGES, selectNewestMemoryFilesV1 } from "./store.js";
 
 /** One Memory file, addressed by its content and its generation. */
 export interface MemoryDocumentV1 {
@@ -42,56 +43,120 @@ export function memoryDocumentKeyV1(document: {
   return `${document.scope}:${document.projectId}:${document.path}`;
 }
 
+/**
+ * Every document of one tier, and whether the tier was read whole.
+ *
+ * `complete: false` means something under this root could not be read. That
+ * distinction is the whole point of the shape: the indexer treats an absent
+ * document as a deleted one, so a partial listing offered as if it were whole
+ * made a transient object-storage blip delete chunks from the search index
+ * permanently and silently.
+ */
+export interface MemoryDocumentListingV1 {
+  documents: MemoryDocumentV1[];
+  complete: boolean;
+}
+
 /**
  * Reads every Memory file under one root. A file that cannot be read is
- * skipped rather than thrown: an index is derived state, and a partial rebuild
+ * skipped rather than thrown — an index is derived state, and a partial read
  * that says so beats a Turn that fails because one object was briefly
- * unreachable.
+ * unreachable — and the listing says it was partial.
  */
-export async function listMemoryDocumentsV1(
+export async function readMemoryDocumentsV1(
   reads: WorkspaceReadsV1,
   root: WorkspaceMemoryRootV1,
-): Promise<MemoryDocumentV1[]> {
+): Promise<MemoryDocumentListingV1> {
   const scope = memoryScopeOfRootV1(root);
   const projectId = memoryProjectIdOfRootV1(root);
-  const documents: MemoryDocumentV1[] = [];
+  const candidates: Array<{
+    path: WorkspacePathV1;
+    kind: "profile" | "log";
+    shard: string;
+    generation: { writtenAt: string; generationId: string };
+  }> = [];
+  let complete = true;
   let cursor: string | undefined;
-  for (let page = 0; page < MEMORY_MAX_LIST_PAGES; page += 1) {
+  let pages = 0;
+  for (; pages < MEMORY_MAX_LIST_PAGES; pages += 1) {
     const outcome = await reads.list(
       cursor === undefined ? { root } : { root, cursor },
     );
-    if (outcome.status !== "ok") return documents;
+    if (outcome.status !== "ok") return { documents: [], complete: false };
     for (const entry of outcome.entries) {
-      if (documents.length >= MEMORY_MAX_FILES_PER_TIER) return documents;
       const classified = memoryFileKindV1(root, entry.path.path);
       if (!classified) continue;
-      const read = await reads.read(entry.path);
-      if (read.status !== "ok") continue;
-      documents.push({
-        scope,
-        projectId,
-        path: entry.path.path,
-        botId: classified.shard,
+      candidates.push({
+        path: entry.path,
         kind: classified.kind,
-        text: new TextDecoder().decode(read.file.bytes),
-        contentHash: read.file.generation.contentHash,
-        generationId: read.file.generation.generationId,
+        shard: classified.shard,
+        generation: entry.generation,
       });
     }
     if (!outcome.cursor) break;
     cursor = outcome.cursor;
   }
-  return documents;
+  if (cursor !== undefined && pages >= MEMORY_MAX_LIST_PAGES) complete = false;
+  // The same selection the injected block makes, and for the same reason:
+  // the two used to disagree — the block kept the *newest* files by recorded
+  // generation while this kept the *first* in listing order, so past the cap
+  // injection covered recent Memory and `memory_search` covered ancient
+  // Memory, with nothing recording the divergence.
+  const selected = selectNewestMemoryFilesV1(candidates);
+  if (selected.length < candidates.length) complete = false;
+  const documents: MemoryDocumentV1[] = [];
+  for (const candidate of selected) {
+    const read = await reads.read(candidate.path);
+    if (read.status !== "ok") {
+      complete = false;
+      continue;
+    }
+    documents.push({
+      scope,
+      projectId,
+      path: candidate.path.path,
+      botId: candidate.shard,
+      kind: candidate.kind,
+      text: new TextDecoder().decode(read.file.bytes),
+      contentHash: read.file.generation.contentHash,
+      generationId: read.file.generation.generationId,
+    });
+  }
+  return { documents, complete };
 }
 
-/** Every Memory document of every root a Bot can see, in tier order. */
-export async function listAllMemoryDocumentsV1(
+/** The documents of one tier, without saying whether the tier was read whole. */
+export async function listMemoryDocumentsV1(
   reads: WorkspaceReadsV1,
-  roots: WorkspaceMemoryRootV1[],
+  root: WorkspaceMemoryRootV1,
 ): Promise<MemoryDocumentV1[]> {
+  return (await readMemoryDocumentsV1(reads, root)).documents;
+}
+
+/**
+ * Every Memory document of every root a Bot can see, in tier order, and
+ * whether every one of those roots was read whole. One partial tier makes the
+ * whole listing partial: the index is updated across tiers at once, and a
+ * caller that cannot tell which tier was short cannot safely delete from it.
+ */
+export async function readAllMemoryDocumentsV1(
+  reads: WorkspaceReadsV1,
+  roots: WorkspaceMemoryRootV1[],
+): Promise<MemoryDocumentListingV1> {
   const documents: MemoryDocumentV1[] = [];
+  let complete = true;
   for (const root of roots) {
-    documents.push(...(await listMemoryDocumentsV1(reads, root)));
+    const listing = await readMemoryDocumentsV1(reads, root);
+    documents.push(...listing.documents);
+    complete &&= listing.complete;
   }
-  return documents;
+  return { documents, complete };
+}
+
+/** Every Memory document of every root a Bot can see, in tier order. */
+export async function listAllMemoryDocumentsV1(
+  reads: WorkspaceReadsV1,
+  roots: WorkspaceMemoryRootV1[],
+): Promise<MemoryDocumentV1[]> {
+  return (await readAllMemoryDocumentsV1(reads, roots)).documents;
 }

package/src/embeddings.ts

@@ -1,3 +1,4 @@
+import { remoteCallV1 } from "@frockbot/kernel-contracts";
 import {
   EMBEDDING_MODEL,
   type EmbedMemory,
@@ -13,9 +14,11 @@ export function createMemoryEmbedder(
   return async (texts) => {
     const vectors: number[][] = [];
     for (let index = 0; index < texts.length; index += MAX_BATCH_SIZE) {
-      const response = await ai.run(model, {
-        text: texts.slice(index, index + MAX_BATCH_SIZE),
-      });
+      // Workers AI is remote in every environment. Without a deadline a hung
+      // binding held the whole Turn open to the platform limit.
+      const response = await remoteCallV1("the embedding model", () =>
+        ai.run(model, { text: texts.slice(index, index + MAX_BATCH_SIZE) }),
+      );
       vectors.push(...response.data);
     }
     return vectors;

package/src/indexer.test.ts

@@ -4,7 +4,10 @@
 // the files in one pass.
 import { describe, expect, test } from "bun:test";
 import type { WorkspaceWriterV1 } from "@frockbot/kernel-contracts";
-import { listAllMemoryDocumentsV1 } from "./documents.ts";
+import {
+  listAllMemoryDocumentsV1,
+  readMemoryDocumentsV1,
+} from "./documents.ts";
 import {
   buildMemoryIndexV1,
   emptyMemoryIndexV1,
@@ -89,3 +92,58 @@ describe("the derived Memory index", () => {
     expect(emptied.index).toEqual(await buildMemoryIndexV1([]));
   });
 });
+
+describe("a tier that could not be read whole says so", () => {
+  test("a failed listing is partial, not empty", async () => {
+    const files = createTestMemoryFilesV1({ userId: "user-1" });
+    const store = new MemoryStore({
+      files,
+      owner: OWNER,
+      clock: () => new Date("2026-08-31T10:00:00.000Z"),
+    });
+    const root = botMemoryRootV1(OWNER);
+    await store.write({
+      root,
+      tier: "profile",
+      fact: "A fact worth chunking.",
+      writer: WRITER,
+    });
+    expect((await readMemoryDocumentsV1(files, root)).complete).toBe(true);
+
+    // Object storage blips on the listing exactly once.
+    const list = files.list.bind(files);
+    files.list = () =>
+      Promise.resolve({ status: "unavailable" as const, reason: "R2 blip" });
+
+    const listing = await readMemoryDocumentsV1(files, root);
+    // The distinction that matters: nothing was read, and the caller is told,
+    // so the indexer cannot mistake "unreadable" for "deleted".
+    expect(listing.documents).toEqual([]);
+    expect(listing.complete).toBe(false);
+
+    files.list = list;
+    expect((await readMemoryDocumentsV1(files, root)).complete).toBe(true);
+  });
+
+  test("a file that cannot be read leaves the tier partial", async () => {
+    const files = createTestMemoryFilesV1({ userId: "user-1" });
+    const store = new MemoryStore({
+      files,
+      owner: OWNER,
+      clock: () => new Date("2026-08-31T10:00:00.000Z"),
+    });
+    const root = botMemoryRootV1(OWNER);
+    await store.write({
+      root,
+      tier: "profile",
+      fact: "A fact worth chunking.",
+      writer: WRITER,
+    });
+    files.read = () =>
+      Promise.resolve({ status: "unavailable" as const, reason: "R2 blip" });
+
+    const listing = await readMemoryDocumentsV1(files, root);
+    expect(listing.documents).toEqual([]);
+    expect(listing.complete).toBe(false);
+  });
+});

package/src/render.ts

@@ -56,6 +56,15 @@ export const MEMORY_USER_CAPS_V1: MemoryRenderCapsV1 = {
   factClamp: 500,
 };
 
+/**
+ * The whole injected Memory block's ceiling, over and above the per-tier caps.
+ *
+ * The per-tier caps bound each section but not their sum, so a Bot in three
+ * Projects injected the sum of every cap on every Turn. This is the one number
+ * that bounds what Memory costs a request, whatever a Bot has joined.
+ */
+export const MEMORY_INJECTION_BUDGET_V1 = 12_000;
+
 /** profileLimit 25 / recentLimit 10, char budgets 2500 / 1500. */
 export const MEMORY_PROJECT_CAPS_V1: MemoryRenderCapsV1 = {
   profileLimit: 25,
@@ -124,7 +133,12 @@ export interface MemoryInjectionInputV1 {
 export interface InjectedMemoryFactV1 {
   scope: MemoryScopeNameV1;
   projectId: string;
-  tier: "profile" | "log";
+  /**
+   * The tier the fact was written as, not the file it happens to sit in. A
+   * note lives in the log file; recording it as `log` left a reader of the
+   * durable event unable to tell the two apart.
+   */
+  tier: "profile" | "log" | "note";
   via: string;
   learnedAt: string;
   text: string;
@@ -205,7 +219,12 @@ function injected(
   return facts.map((fact) => ({
     scope,
     projectId,
-    tier,
+    // A note lives in the log file, and the event used to say `log` while the
+    // write that produced it said `note` — so a reader of the durable record
+    // could not tell the two tiers apart, and the only sign was a `[note] `
+    // prefix inside the text. The marker on the recorded text is what the
+    // tier was; the file it sits in is not.
+    tier: parseMemoryMarkerV1(fact.text).marker === "note" ? "note" : tier,
     via: withVia ? fact.via : "",
     learnedAt: fact.date,
     text: fact.text,
@@ -474,5 +493,28 @@ export function renderMemoryInjectionV1(
     });
   }
 
-  return { text: blocks.join("\n\n"), facts, omissions, faded };
+  // A global bound over the per-tier ones. Each tier is capped on its own, so
+  // a Bot in three Projects could inject the sum of every cap — about 26 000
+  // characters — on every Turn, growing with membership rather than with
+  // anything the User did. The block is assembled most-general first and the
+  // Bot's own memory last, so the trim drops from the front: the most
+  // specific tier, which wins on conflict anyway, is the one kept.
+  const text = blocks.join("\n\n");
+  if (text.length <= MEMORY_INJECTION_BUDGET_V1) {
+    return { text, facts, omissions, faded };
+  }
+  const kept: string[] = [];
+  let spent = 0;
+  for (const block of blocks.toReversed()) {
+    if (spent + block.length > MEMORY_INJECTION_BUDGET_V1) break;
+    kept.unshift(block);
+    spent += block.length;
+  }
+  omissions.push({
+    scope: "user",
+    reason: `the injected Memory block exceeded ${MEMORY_INJECTION_BUDGET_V1} characters; ${
+      blocks.length - kept.length
+    } of ${blocks.length} section(s), least specific first, were not injected`,
+  });
+  return { text: kept.join("\n\n"), facts, omissions, faded };
 }

package/src/roots.ts

@@ -91,13 +91,29 @@ export function memoryProjectIdOfRootV1(root: WorkspaceMemoryRootV1): string {
   return root.kind === "project-memory" ? root.projectId : "";
 }
 
-/** `log/YYYY-MM.md`, the monthly file a dated fact is appended to. */
-export function memoryLogRelativeV1(at: Date): string {
+/**
+ * `log/YYYY-MM.md`, the monthly file a dated fact is appended to, or
+ * `log/YYYY-MM.NN.md` once that month has rolled over.
+ *
+ * A month rolls over when its file reaches the per-file byte cap. Without
+ * that, a busy month's file grew past the cap and then the *whole tier*
+ * vanished from injection — the read skips an oversized file and `forget`
+ * answers `unavailable` for the tier, so no tool could trim it back.
+ */
+export function memoryLogRelativeV1(at: Date, part = 0): string {
   const year = at.getUTCFullYear().toString().padStart(4, "0");
   const month = (at.getUTCMonth() + 1).toString().padStart(2, "0");
-  return `${MEMORY_LOG_DIRECTORY}/${year}-${month}.md`;
+  // `p` and not a bare number: the tier merge relies on path order, and
+  // `2026-08.01.md` sorts *before* `2026-08.md` while `2026-08.p01.md` sorts
+  // after it. The first file of a month keeps its existing name, so nothing
+  // already written moves.
+  const suffix = part > 0 ? `.p${part.toString().padStart(2, "0")}` : "";
+  return `${MEMORY_LOG_DIRECTORY}/${year}-${month}${suffix}.md`;
 }
 
+/** How many rollover parts one month may have before a write is refused. */
+export const MEMORY_MAX_LOG_PARTS_V1 = 99;
+
 /** The relative path, inside a shard, one tier writes to. */
 export function memoryTierRelativeV1(tier: MemoryTierV1, at: Date): string {
   return tier === "profile" ? MEMORY_PROFILE_FILE : memoryLogRelativeV1(at);
@@ -117,6 +133,16 @@ export function memoryFilePathV1(
   return memoryShardPathV1(root, botId, memoryTierRelativeV1(tier, at));
 }
 
+/** One month's log file, or one of its rollover parts, in a Bot's shard. */
+export function memoryLogPathV1(
+  root: WorkspaceMemoryRootV1,
+  botId: string,
+  at: Date,
+  part: number,
+): WorkspacePathV1 {
+  return memoryShardPathV1(root, botId, memoryLogRelativeV1(at, part));
+}
+
 /** The prefix a Bot's own files sit under; `""` for the Bot Memory root. */
 export function memoryShardOfV1(
   root: WorkspaceMemoryRootV1,
@@ -153,6 +179,11 @@ export function memoryFileKindV1(
     shard = root.botId;
   }
   if (tail === MEMORY_PROFILE_FILE) return { kind: "profile", shard };
-  if (/^log\/\d{4}-\d{2}\.md$/.test(tail)) return { kind: "log", shard };
+  // `log/YYYY-MM.md` and its rollover parts `log/YYYY-MM.NN.md`. Both sort
+  // after the month they belong to and before the next one, which is the
+  // order the tier merge relies on.
+  if (/^log\/\d{4}-\d{2}(\.p\d{2})?\.md$/.test(tail)) {
+    return { kind: "log", shard };
+  }
   return undefined;
 }

package/src/searcher.ts

@@ -9,7 +9,10 @@
 // Precedence here is the Memory precedence: own (`bot`) before `project`
 // before `user`, "the most specific wins", applied after scoring so a strong
 // shared hit still ranks above a weak own one within the same document.
-import type { MemoryScopeNameV1 } from "@frockbot/kernel-contracts";
+import {
+  remoteCallV1,
+  type MemoryScopeNameV1,
+} from "@frockbot/kernel-contracts";
 import {
   memoryVectorNamespaceV1,
   type MemoryIndexChunkV1,
@@ -89,19 +92,37 @@ export async function searchMemoryV1(
       const [vector] = await options.embed([query]);
       if (vector) {
         const namespaces = new Set(candidates.map(memoryVectorNamespaceV1));
-        const byHash = new Map(
-          candidates.map((chunk) => [chunk.hash, chunk] as const),
+        // Keyed on the document *and* the chunk hash. Keying on the chunk
+        // hash alone made two identical chunks in different documents collide,
+        // so one of the two locations was unreachable from a vector hit.
+        const byHash = new Map<string, MemoryIndexChunkV1>(
+          candidates.map((chunk) => [
+            `${chunk.documentKey} ${chunk.hash}`,
+            chunk,
+          ]),
         );
         for (const namespace of namespaces) {
-          const response = await options.vectorize.query(vector, {
-            topK: Math.min(options.maxResults * 3, 20),
-            namespace,
-            returnMetadata: "all",
-          });
+          const response = await remoteCallV1("the memory index", () =>
+            options.vectorize!.query(vector, {
+              topK: Math.min(options.maxResults * 3, 20),
+              namespace,
+              returnMetadata: "all",
+            }),
+          );
           for (const match of response.matches) {
             const hash = match.metadata?.hash;
+            // The document key is rebuilt from the metadata the upsert wrote,
+            // so a chunk is matched to the document it actually came from.
+            const scope = match.metadata?.scope;
+            const projectId = match.metadata?.projectId;
+            const path = match.metadata?.path;
             const chunk =
-              typeof hash === "string" ? byHash.get(hash) : undefined;
+              typeof hash === "string" &&
+              typeof scope === "string" &&
+              typeof projectId === "string" &&
+              typeof path === "string"
+                ? byHash.get(`${scope}:${projectId}:${path} ${hash}`)
+                : undefined;
             if (!chunk) continue;
             scored.set(
               chunk,

package/src/store.test.ts

@@ -171,6 +171,65 @@ describe("the Memory writer", () => {
   });
 });
 
+describe("a month's log rolls over instead of killing its tier", () => {
+  test("keeps writing, keeps reading, and every fact survives", async () => {
+    const { files, store } = storeFor("bot-1");
+    const root = botMemoryRootV1(OWNER);
+    const writer = writerFor("bot-1");
+    // Facts big enough that a few hundred fill one 256 KB file.
+    const filler = "y".repeat(1_900);
+
+    for (let index = 0; index < 200; index += 1) {
+      const outcome = await store.write({
+        root,
+        tier: "log",
+        fact: `${index} ${filler}`,
+        writer,
+      });
+      // The write that used to push the file past the cap and strand the
+      // whole tier now lands in the next part instead.
+      expect(outcome.status).toBe("ok");
+    }
+
+    const listing = await files.list({ root });
+    expect(listing.status).toBe("ok");
+    if (listing.status !== "ok") return;
+    const logs = listing.entries
+      .map((entry) => entry.path.path)
+      .filter((path) => path.startsWith("log/"))
+      .sort();
+    // It rolled: the month has more than one file, named so it still sorts
+    // inside its own month.
+    expect(logs.length).toBeGreaterThan(1);
+    // The first file keeps its existing name and the parts sort after it, so
+    // the tier merge's "newest month last" still holds inside the month.
+    expect(logs[0]).toBe("log/2026-08.md");
+    expect(logs[1]).toBe("log/2026-08.p01.md");
+    // No file is past the cap, so the read skips nothing…
+    for (const entry of listing.entries) {
+      expect(entry.generation.size).toBeLessThanOrEqual(256 * 1024);
+    }
+    // …and the tier is whole rather than `unavailable`.
+    const tier = await store.read(root);
+    expect(tier.unavailable).toBeUndefined();
+    expect(tier.recent.length).toBeGreaterThan(0);
+  });
+
+  test("refuses a single write that cannot fit in any file", async () => {
+    const { store } = storeFor("bot-1");
+    const root = botMemoryRootV1(OWNER);
+    // The profile tier is curated and does not roll: an oversized commit is a
+    // refusal the User can see, never a file the reader has to skip.
+    const outcome = await store.write({
+      root,
+      tier: "profile",
+      fact: "z".repeat(2_001),
+      writer: writerFor("bot-1"),
+    });
+    expect(outcome.status).toBe("refused");
+  });
+});
+
 describe("forgetting", () => {
   test("removes a fact this Bot recorded from its own shard", async () => {
     const { store } = storeFor("bot-1");
@@ -225,6 +284,50 @@ describe("forgetting", () => {
     expect((await two.store.read(root)).profile).toEqual([]);
   });
 
+  test("retracts a shared fact that this Bot's own shard also holds", async () => {
+    const files = createTestMemoryFilesV1({ userId: "user-1" });
+    const root = userMemoryRootV1(OWNER);
+    const one = storeFor("bot-1", files);
+    const two = storeFor("bot-2", files);
+    // Both Bots learned the same thing. Mine is a plain fact and theirs is
+    // marked as a note, so the merge keeps both — this is the case where my
+    // own shard *and* another's hold it.
+    await one.store.write({
+      root,
+      tier: "profile",
+      fact: "Tim teaches on Tuesdays.",
+      writer: writerFor("bot-1"),
+    });
+    await two.store.write({
+      root,
+      tier: "profile",
+      fact: "[note] Tim teaches on Tuesdays.",
+      writer: writerFor("bot-2"),
+    });
+    expect((await one.store.read(root)).profile).toHaveLength(2);
+
+    const forgotten = await one.store.forget({
+      root,
+      fact: "Tim teaches on Tuesdays.",
+      writer: writerFor("bot-1"),
+    });
+
+    // Removing my own line used to return here, leaving the other Bot's copy
+    // injected forever under a result that said it was forgotten.
+    expect(forgotten).toMatchObject({ status: "ok", retracted: true });
+    const mine = await files.read({
+      root,
+      path: "by-agent/bot-1/profile.md",
+    });
+    expect(
+      mine.status === "ok" ? new TextDecoder().decode(mine.file.bytes) : "",
+    ).not.toContain("Tim teaches on Tuesdays.");
+    // The other Bot's shard is never edited, and the merged tier is clean for
+    // both readers.
+    expect((await one.store.read(root)).profile).toEqual([]);
+    expect((await two.store.read(root)).profile).toEqual([]);
+  });
+
   test("removes every marker variant of a fact, given the body or the marker", async () => {
     const { store } = storeFor("bot-1");
     const root = botMemoryRootV1(OWNER);

package/src/store.ts

@@ -40,7 +40,9 @@ import {
 import {
   memoryFileKindV1,
   memoryFilePathV1,
+  memoryLogPathV1,
   memoryShardOfV1,
+  MEMORY_MAX_LOG_PARTS_V1,
   type MemoryOwnerV1,
   type MemoryTierV1,
 } from "./roots.js";
@@ -50,6 +52,46 @@ import { refuseMemorySecretV1 } from "./secrets.js";
 export const MEMORY_MAX_LIST_PAGES = 8;
 /** Most Memory files read to render one tier. */
 export const MEMORY_MAX_FILES_PER_TIER = 64;
+
+/**
+ * How much longer than a fact a retraction of it may be: the `[forgotten] `
+ * prefix, and the marker the retracted text may already carry.
+ */
+const MEMORY_RETRACTION_HEADROOM = 32;
+
+/**
+ * The files of one tier that a bounded read keeps, in path order.
+ *
+ * One function, used by the injected block and by the search index, because
+ * they used to choose differently: the block kept the newest files by
+ * recorded generation and the index kept the first in listing order. Past the
+ * cap that meant injection covered recent Memory while `memory_search`
+ * covered ancient Memory, and nothing recorded that they disagreed.
+ *
+ * The newest are kept, by `writtenAt` with the generation id breaking a tie —
+ * both recorded by the write that produced the file — and the survivors are
+ * returned in path order, which is the order the tier merge relies on.
+ */
+export function selectNewestMemoryFilesV1<
+  T extends {
+    path: { path: string };
+    generation: { writtenAt: string; generationId: string };
+  },
+>(files: readonly T[], limit = MEMORY_MAX_FILES_PER_TIER): T[] {
+  const newest = [...files]
+    .sort(
+      (left, right) =>
+        left.generation.writtenAt.localeCompare(right.generation.writtenAt) ||
+        left.generation.generationId.localeCompare(
+          right.generation.generationId,
+        ),
+    )
+    .slice(-limit);
+  const kept = new Set(newest.map((file) => file.path.path));
+  return files
+    .filter((file) => kept.has(file.path.path))
+    .sort((left, right) => left.path.path.localeCompare(right.path.path));
+}
 /** The longest fact this Package will record. */
 export const MEMORY_MAX_FACT_LENGTH = 2_000;
 /** The largest Memory file this Package will rewrite. */
@@ -73,7 +115,12 @@ export interface MemoryTierReadV1 {
   profile: SourcedMemoryFactV1[];
   recent: SourcedMemoryFactV1[];
   sources: MemorySourceV1[];
-  /** Log facts held on disk beyond what `recent` carries, before any cap. */
+  /**
+   * How many log facts the tier read resolved. It equals `recent.length`:
+   * `read` applies no cap of its own, so there is nothing "beyond" it — the
+   * caps live in the renderer. The field was documented as the surplus and
+   * assigned the total, which is a difference nothing could act on.
+   */
   logTotal: number;
   /** Set when the tier could not be read in full; rendered as an omission. */
   unavailable?: string;
@@ -214,26 +261,22 @@ export class MemoryStore {
       .sort((left, right) =>
         left.entry.path.path.localeCompare(right.entry.path.path),
       );
-    // The bound keeps the *newest* files, by recorded generation: what Memory
-    // is for is injecting recent facts, so a tier past the bound loses its
-    // oldest months rather than its newest. `writtenAt` orders them and the
-    // generation id breaks a tie, because both are recorded by the write that
-    // produced the file. The kept files are then restored to path order, which
-    // is the order the merge below relies on.
-    const newest = [...classifiedFiles]
-      .sort((left, right) => {
-        const a = left.entry.generation;
-        const b = right.entry.generation;
-        return (
-          a.writtenAt.localeCompare(b.writtenAt) ||
-          a.generationId.localeCompare(b.generationId)
-        );
-      })
-      .slice(-MEMORY_MAX_FILES_PER_TIER);
-    const kept = new Set(newest.map(({ entry }) => entry.path.path));
-    const files = classifiedFiles.filter(({ entry }) =>
-      kept.has(entry.path.path),
+    // The bound keeps the *newest* files: what Memory is for is injecting
+    // recent facts, so a tier past the bound loses its oldest months rather
+    // than its newest. The selection is shared with the search index, so the
+    // injected block and `memory_search` cover the same files.
+    const selected = selectNewestMemoryFilesV1(
+      classifiedFiles.map(({ entry, classified }) => ({
+        path: entry.path,
+        generation: entry.generation,
+        entry,
+        classified,
+      })),
     );
+    const files = selected.map(({ entry, classified }) => ({
+      entry,
+      classified,
+    }));
     if (classifiedFiles.length > files.length) {
       const dropped = classifiedFiles.length - files.length;
       omissions.push(
@@ -242,14 +285,21 @@ export class MemoryStore {
     }
     if (omissions.length > 0) result.omitted = omissions.join("; ");
 
+    // Every unreadable file is named, not just the last one. Assigning
+    // `result.unavailable` per file overwrote the reason each time, so a tier
+    // where three files failed reported one reason and was injected as if it
+    // were whole.
+    const unreadable: string[] = [];
     for (const { entry, classified } of files) {
       if (entry.generation.size > MEMORY_MAX_FILE_BYTES) {
-        result.unavailable = `a Memory file exceeds ${MEMORY_MAX_FILE_BYTES} bytes`;
+        unreadable.push(
+          `"${entry.path.path}" exceeds ${MEMORY_MAX_FILE_BYTES} bytes`,
+        );
         continue;
       }
       const read = await this.#files.read(entry.path);
       if (read.status !== "ok") {
-        result.unavailable = read.reason;
+        unreadable.push(`"${entry.path.path}": ${read.reason}`);
         continue;
       }
       result.sources.push({
@@ -271,6 +321,10 @@ export class MemoryStore {
       else log.push(...sourced);
     }
 
+    if (unreadable.length > 0) {
+      result.unavailable = `${unreadable.length} Memory file(s) could not be read: ${unreadable.join("; ")}`;
+    }
+
     // Retractions cross files inside a tier: a `[forgotten]` line in the log
     // suppresses the profile fact it names, which is what "newest wins" means
     // once forgetting exists at all.
@@ -299,9 +353,19 @@ export class MemoryStore {
     fact: string;
     writer: WorkspaceWriterV1;
     at?: Date;
+    /** Set only by `forget`: a retraction of a fact already on disk. */
+    retraction?: true;
   }): Promise<MemoryWriteOutcomeV1> {
     const text = request.fact.trim();
-    if (!text || text.length > MEMORY_MAX_FACT_LENGTH) {
+    // The cap bounds what a Bot may *record*. A retraction is a fact the
+    // Package writes about a fact that is already on disk, so measuring the
+    // retraction against the same cap made a fact longer than
+    // `MEMORY_MAX_FACT_LENGTH` minus the prefix impossible to forget — the
+    // one operation that shrinks Memory refused because Memory was too big.
+    const cap = request.retraction
+      ? MEMORY_MAX_FACT_LENGTH + MEMORY_RETRACTION_HEADROOM
+      : MEMORY_MAX_FACT_LENGTH;
+    if (!text || text.length > cap) {
       return {
         status: "refused",
         reason: `a fact must be between 1 and ${MEMORY_MAX_FACT_LENGTH} characters`,
@@ -310,12 +374,8 @@ export class MemoryStore {
     const secret = refuseMemorySecretV1(text);
     if (secret) return { status: "refused", reason: secret.reason };
     const at = request.at ?? this.#clock();
-    const path = memoryFilePathV1(
-      request.root,
-      this.owner.botId,
-      request.tier,
-      at,
-    );
+    const path = await this.tierWritePath(request.root, request.tier, at);
+    if ("status" in path) return path;
     const refusal = this.refuseForeignShard(path, request.writer);
     if (refusal) return refusal;
     const line: MemoryFactV1 = { date: memoryDayV1(at), text };
@@ -328,6 +388,47 @@ export class MemoryStore {
     });
   }
 
+  /**
+   * The file this tier's next fact goes in, rolling the log over when the
+   * current file is full.
+   *
+   * A log file that grew past the per-file cap used to take its whole tier
+   * down with it: the read skips an oversized file, so the tier vanished from
+   * injection, and `forget` answered `unavailable` for it, so no tool could
+   * trim it back. Rolling to `log/YYYY-MM.NN.md` keeps every fact, keeps
+   * every file readable, and needs no migration — the existing month file is
+   * part 0 and stays exactly where it is.
+   *
+   * The profile tier does not roll: it is a bounded, curated file, and one
+   * that reached the cap is a real refusal the User should see.
+   */
+  private async tierWritePath(
+    root: WorkspaceMemoryRootV1,
+    tier: MemoryTierV1,
+    at: Date,
+  ): Promise<WorkspacePathV1 | MemoryWriteOutcomeV1> {
+    const path = memoryFilePathV1(root, this.owner.botId, tier, at);
+    if (tier === "profile") return path;
+    for (let part = 0; part <= MEMORY_MAX_LOG_PARTS_V1; part += 1) {
+      const candidate = memoryLogPathV1(root, this.owner.botId, at, part);
+      const head = await this.#files.stat(candidate);
+      if (head.status === "not-found") return candidate;
+      if (head.status !== "ok")
+        return { status: head.status, reason: head.reason };
+      // Room for at least one more fact of the maximum size, so a write never
+      // pushes a file past the cap and strands it.
+      if (
+        head.entry.generation.size + MEMORY_MAX_FACT_LENGTH <
+        MEMORY_MAX_FILE_BYTES
+      )
+        return candidate;
+    }
+    return {
+      status: "refused",
+      reason: `this month's Memory log already has ${MEMORY_MAX_LOG_PARTS_V1} files`,
+    };
+  }
+
   /**
    * Forgets one fact by its recorded text, ignoring any marker on it.
    *
@@ -381,33 +482,36 @@ export class MemoryStore {
     const mine = [...tier.profile, ...tier.recent].filter(
       (fact) => fact.botId === this.owner.botId && matches(fact.text),
     );
+    // Both halves always run. Removing my own line and returning left another
+    // Bot's copy of the same fact being injected forever, under a tool result
+    // that said "Forgotten. The line is gone from …" — so a shared fact two
+    // Bots had recorded came back on the very next Turn.
+    const ownWrites: MemoryFileChangeV1[] = [];
+    let ownLast: MemoryWriteOutcomeV1 | undefined;
     if (mine.length > 0) {
-      // The Bot owns every file the fact sits in, so removing the line is both
-      // permitted and the honest record: nothing else recorded it.
-      let last: MemoryWriteOutcomeV1 | undefined;
-      // Each rewritten file is recorded as it lands, so a failure part-way
-      // through still answers with the generations that already exist on disk.
-      const written: MemoryFileChangeV1[] = [];
+      // Removing the line from my own shard is permitted and is the honest
+      // record for the copies I wrote. Each rewritten file is recorded as it
+      // lands, so a failure part-way through still answers with the
+      // generations that already exist on disk.
       for (const source of tier.sources) {
         if (source.botId !== this.owner.botId) continue;
         const path: WorkspacePathV1 = { root: request.root, path: source.path };
         const refusal = this.refuseForeignShard(path, request.writer);
-        if (refusal) return { ...refusal, written };
+        if (refusal) return { ...refusal, written: ownWrites };
         const outcome = await this.rewrite(path, request.writer, (facts) => {
           const kept = facts.filter((fact) => !matches(fact.text));
           return kept.length === facts.length ? "unchanged" : kept;
         });
-        if (outcome.status !== "ok") return { ...outcome, written };
+        if (outcome.status !== "ok") return { ...outcome, written: ownWrites };
         if (!outcome.duplicate) {
-          last = outcome;
-          written.push({
+          ownLast = outcome;
+          ownWrites.push({
             path: outcome.path,
             generationId: outcome.generationId,
             contentHash: outcome.contentHash,
           });
         }
       }
-      if (last) return { ...last, written };
     }
 
     const elsewhere = [
@@ -419,13 +523,16 @@ export class MemoryStore {
       ),
     ];
     if (elsewhere.length === 0) {
+      // Nothing else holds it. My own removal, if there was one, is the whole
+      // answer.
+      if (ownLast) return { ...ownLast, written: ownWrites };
       return {
         status: "refused",
         reason: `no fact matching "${text}" is recorded in this tier`,
       };
     }
-    const written: MemoryFileChangeV1[] = [];
-    let last: MemoryWriteOutcomeV1 | undefined;
+    const written: MemoryFileChangeV1[] = [...ownWrites];
+    let last: MemoryWriteOutcomeV1 | undefined = ownLast;
     for (const recorded of elsewhere) {
       const retraction = await this.write({
         root: request.root,
@@ -433,6 +540,7 @@ export class MemoryStore {
         fact: memoryRetractionTextV1(recorded),
         writer: request.writer,
         at,
+        retraction: true,
       });
       if (retraction.status !== "ok") return { ...retraction, written };
       last = retraction;
@@ -541,6 +649,21 @@ export class MemoryStore {
     writer: WorkspaceWriterV1,
     current: WorkspaceGenerationV1 | undefined,
   ): Promise<MemoryWriteOutcomeV1> {
+    // The cap is checked here rather than only in `writeFile`, because this is
+    // the path every fact takes. A commit that sailed past it left a file the
+    // read then skipped, taking the whole tier out of injection with no tool
+    // able to trim it. A `forget` shrinking an already-oversized file is the
+    // one thing that must still get through: refusing it would make the
+    // condition unrecoverable.
+    if (
+      bytes.byteLength > MEMORY_MAX_FILE_BYTES &&
+      bytes.byteLength >= (current?.size ?? 0)
+    ) {
+      return {
+        status: "refused",
+        reason: `this Memory file would exceed ${MEMORY_MAX_FILE_BYTES} bytes`,
+      };
+    }
     const outcome = await this.#files.write({
       path,
       bytes,