@frockbot/plugin-memory 0.0.0 → 0.1.0

package/src/render.ts

@@ -0,0 +1,478 @@
+// The injected Memory block: GrokBot's shape, order, labels and caps.
+//
+// Parity target, `docs/research/grokbot-computer.md` §4.1a–b. Three scopes,
+// injected **user → project → own**, as *labelled paragraphs* rather than
+// headings, blank-line separated. Precedence runs the other way — own >
+// project > user, "the most specific wins" — so a fact a Bot holds itself is
+// not repeated in a shared block below it.
+//
+// The caps are GrokBot's constants, not ours:
+//
+//   own      30 recent facts, 4000-char recent budget, 500-char clamp per fact
+//   user     50 profile / 15 recent, 4000 / 2000 char budgets
+//   project  at most 3 Projects; 25 profile / 10 recent, 2500 / 1500 budgets
+//
+// DELIBERATELY NOT IMPLEMENTED: `resolveFrozenMemoryPrompt`. GrokBot freezes
+// the rendered block per compaction epoch and reuses it, and that freeze is
+// the best explanation for the divergence we observed — own profile facts
+// sitting on disk while the injected block said "No facts recorded yet"
+// (§3.6). Rendering fresh every Turn costs one listing and gives an injection
+// that matches the files; the constitution's requirement is that what was
+// injected is *recorded*, which `memory/injected` does, not that it is cached.
+import type { MemoryScopeNameV1 } from "@frockbot/kernel-contracts";
+import {
+  memoryFactKeyV1,
+  parseMemoryMarkerV1,
+  renderInjectedFactLineV1,
+  type SourcedMemoryFactV1,
+} from "./facts.js";
+import { memoryShardOfV1 } from "./roots.js";
+import type { MemoryTierReadV1 } from "./store.js";
+
+/** One tier's render bounds, in GrokBot's own units. */
+export interface MemoryRenderCapsV1 {
+  profileLimit: number;
+  recentLimit: number;
+  profileBudget: number;
+  recentBudget: number;
+  factClamp: number;
+}
+
+/** `recall(30)`, a 4000-char recent budget, a 500-char clamp per fact. */
+export const MEMORY_OWN_CAPS_V1: MemoryRenderCapsV1 = {
+  profileLimit: 200,
+  recentLimit: 30,
+  profileBudget: 4_000,
+  recentBudget: 4_000,
+  factClamp: 500,
+};
+
+/** profileLimit 50 / recentLimit 15, char budgets 4000 / 2000. */
+export const MEMORY_USER_CAPS_V1: MemoryRenderCapsV1 = {
+  profileLimit: 50,
+  recentLimit: 15,
+  profileBudget: 4_000,
+  recentBudget: 2_000,
+  factClamp: 500,
+};
+
+/** profileLimit 25 / recentLimit 10, char budgets 2500 / 1500. */
+export const MEMORY_PROJECT_CAPS_V1: MemoryRenderCapsV1 = {
+  profileLimit: 25,
+  recentLimit: 10,
+  profileBudget: 2_500,
+  recentBudget: 1_500,
+  factClamp: 500,
+};
+
+/**
+ * How many days a `[note] ` (or `[episode] `) fact keeps being injected.
+ *
+ * OURS, NOT GROKBOT'S. The register records only that the note tier "fades
+ * fast" (§2.2); no TTL, no observed expiry, no host source anywhere in the
+ * research. A fortnight is long enough that a note survives a week's gap in
+ * conversation and short enough to mean "fast", and it is one constant, here,
+ * beside the caps — not an env var and not a User setting, because a per-User
+ * knob would have to be recorded on every Turn for the model request to stay
+ * reconstructable.
+ *
+ * The fade is READ-TIME AND PURE. A faded note is still on disk, still
+ * greppable by the Bot, still returned by `memory_search`, still forgettable —
+ * it has stopped being *injected*, which is the strongest claim "fades fast"
+ * supports without deleting a User's data. There is no sweep, no alarm, and no
+ * write, so there is nothing to reconcile after an eviction.
+ */
+export const MEMORY_NOTE_TTL_DAYS = 14;
+
+/** `MEMORY_PROJECT_INJECTED_CAP`: at most three joined Projects are injected. */
+export const MEMORY_PROJECT_INJECTED_CAP = 3;
+
+/** One Project the Bot has joined, as the render needs it. */
+export interface MemoryProjectV1 {
+  projectId: string;
+  name: string;
+  description: string;
+}
+
+/** A Project's tier read together with the Project it belongs to. */
+export interface MemoryProjectTierV1 {
+  project: MemoryProjectV1;
+  tier: MemoryTierReadV1;
+}
+
+/** Everything one Turn renders from. */
+export interface MemoryInjectionInputV1 {
+  botId: string;
+  user: MemoryTierReadV1;
+  projects: MemoryProjectTierV1[];
+  /** Every joined Project, including the ones the cap left out. */
+  joined: MemoryProjectV1[];
+  own: MemoryTierReadV1;
+  /**
+   * `YYYY-MM-DD`: the oldest day a marked fact is still injected on.
+   *
+   * Required, and passed in rather than read from a clock here, because "the
+   * durable session event log reconstructs … every exact normalized model
+   * request". A filter on "today" computed inside this function would make the
+   * render unreproducible; a filter on a day the caller records in
+   * `memory/injected` replays identically a year later.
+   */
+  noteCutoff: string;
+}
+
+/** One fact that reached the prompt, as `memory/injected` records it. */
+export interface InjectedMemoryFactV1 {
+  scope: MemoryScopeNameV1;
+  projectId: string;
+  tier: "profile" | "log";
+  via: string;
+  learnedAt: string;
+  text: string;
+}
+
+/**
+ * Facts one scope faded out of this injection, as `memory/injected` records it.
+ *
+ * Kept apart from `omissions` deliberately: an omission means a cap or a
+ * failure cut a tier short and is a gap to repair, so a reader may alarm on
+ * it; a fade is the note tier working as designed. Folding the two together
+ * would make every Turn carrying an old note look degraded.
+ */
+export interface MemoryFadedV1 {
+  scope: MemoryScopeNameV1;
+  projectId: string;
+  count: number;
+}
+
+/** A tier a cap or a failure cut short, as `memory/injected` records it. */
+export interface MemoryOmissionV1 {
+  scope: MemoryScopeNameV1;
+  reason: string;
+}
+
+export interface MemoryInjectionV1 {
+  /** The rendered block, or `""` when there is nothing at all to inject. */
+  text: string;
+  facts: InjectedMemoryFactV1[];
+  omissions: MemoryOmissionV1[];
+  /** Marked facts dropped by the fade, per scope. Never an omission. */
+  faded: MemoryFadedV1[];
+}
+
+const USER_PARAGRAPH =
+  "User memory: facts shared by every Bot of this User. It is split into one shard folder per Bot so every file has a single writer. Never edit another Bot's shard — correct a shared fact by writing the correction into your own shard with memory_write, and newest wins.";
+const OWN_PARAGRAPH =
+  "Memory: your own memory. On conflict prefer your OWN memory first, then project memory, then user memory — the most specific wins; within a shared tier, newest wins.";
+
+interface TakenFacts {
+  lines: string[];
+  taken: SourcedMemoryFactV1[];
+  dropped: number;
+}
+
+/** Applies one tier's count limit, char budget and per-fact clamp, in order. */
+function take(
+  facts: SourcedMemoryFactV1[],
+  limit: number,
+  budget: number,
+  clamp: number,
+  withVia: boolean,
+): TakenFacts {
+  const lines: string[] = [];
+  const taken: SourcedMemoryFactV1[] = [];
+  let used = 0;
+  for (const fact of facts) {
+    if (taken.length >= limit) break;
+    const line = renderInjectedFactLineV1(
+      withVia ? fact : { date: fact.date, text: fact.text },
+      clamp,
+    );
+    if (used + line.length > budget && taken.length > 0) break;
+    used += line.length + 1;
+    lines.push(line);
+    taken.push(fact);
+  }
+  return { lines, taken, dropped: facts.length - taken.length };
+}
+
+function injected(
+  facts: SourcedMemoryFactV1[],
+  scope: MemoryScopeNameV1,
+  projectId: string,
+  tier: "profile" | "log",
+  withVia: boolean,
+): InjectedMemoryFactV1[] {
+  return facts.map((fact) => ({
+    scope,
+    projectId,
+    tier,
+    via: withVia ? fact.via : "",
+    learnedAt: fact.date,
+    text: fact.text,
+  }));
+}
+
+/**
+ * Drops the marked facts that have faded, before any cap is applied.
+ *
+ * Before, not after, so a faded note never occupies a slot a live fact could
+ * have used — the whole point of a tier that fades is that it stops competing
+ * for the budget.
+ */
+function live(
+  facts: SourcedMemoryFactV1[],
+  cutoff: string,
+): { kept: SourcedMemoryFactV1[]; faded: number } {
+  const kept = facts.filter((fact) => {
+    const { marker } = parseMemoryMarkerV1(fact.text);
+    return !marker || fact.date >= cutoff;
+  });
+  return { kept, faded: facts.length - kept.length };
+}
+
+function without(
+  facts: SourcedMemoryFactV1[],
+  seen: Set<string>,
+): SourcedMemoryFactV1[] {
+  return facts.filter((fact) => !seen.has(memoryFactKeyV1(fact.text)));
+}
+
+function remember(facts: SourcedMemoryFactV1[], seen: Set<string>): void {
+  for (const fact of facts) seen.add(memoryFactKeyV1(fact.text));
+}
+
+/**
+ * Renders the whole Memory block and reports exactly what reached the prompt.
+ *
+ * Pure: it reads nothing and writes nothing. That is what makes "the session
+ * event log records exactly what was injected" checkable — the caller records
+ * the `facts` this function returns, so the record cannot drift from the text.
+ */
+export function renderMemoryInjectionV1(
+  input: MemoryInjectionInputV1,
+): MemoryInjectionV1 {
+  const facts: InjectedMemoryFactV1[] = [];
+  const omissions: MemoryOmissionV1[] = [];
+  const blocks: string[] = [];
+
+  // Precedence is applied before rendering: the own tier claims a fact text,
+  // then the Projects, and only the remainder reaches the User block. The
+  // ordering of the *paragraphs* is the opposite — user, project, own — which
+  // is GrokBot's injected order exactly.
+  //
+  // The fade runs first of all, so precedence, caps and budgets all see only
+  // the surviving set.
+  const faded: MemoryFadedV1[] = [];
+  const fade = (
+    tier: MemoryTierReadV1,
+    scope: MemoryScopeNameV1,
+    projectId: string,
+  ) => {
+    const profile = live(tier.profile, input.noteCutoff);
+    const recent = live(tier.recent, input.noteCutoff);
+    const count = profile.faded + recent.faded;
+    if (count > 0) faded.push({ scope, projectId, count });
+    return {
+      profile: profile.kept,
+      recent: recent.kept,
+      recentFaded: recent.faded,
+    };
+  };
+  const ownLive = fade(input.own, "bot", "");
+  const userLive = fade(input.user, "user", "");
+
+  const claimed = new Set<string>();
+  remember([...ownLive.profile, ...ownLive.recent], claimed);
+
+  const shown = input.projects.slice(0, MEMORY_PROJECT_INJECTED_CAP);
+  const projectFacts = shown.map((entry) => {
+    const tier = fade(entry.tier, "project", entry.project.projectId);
+    const profile = without(tier.profile, claimed);
+    const recent = without(tier.recent, claimed);
+    return { entry, profile, recent };
+  });
+  for (const entry of projectFacts) {
+    remember([...entry.profile, ...entry.recent], claimed);
+  }
+
+  // User memory.
+  const userProfile = take(
+    without(userLive.profile, claimed),
+    MEMORY_USER_CAPS_V1.profileLimit,
+    MEMORY_USER_CAPS_V1.profileBudget,
+    MEMORY_USER_CAPS_V1.factClamp,
+    true,
+  );
+  const userRecent = take(
+    without(userLive.recent, claimed),
+    MEMORY_USER_CAPS_V1.recentLimit,
+    MEMORY_USER_CAPS_V1.recentBudget,
+    MEMORY_USER_CAPS_V1.factClamp,
+    true,
+  );
+  const userLines = [USER_PARAGRAPH];
+  if (userProfile.lines.length > 0) {
+    userLines.push("About the user (shared):", ...userProfile.lines);
+  }
+  if (userRecent.lines.length > 0) {
+    userLines.push("Recently (shared):", ...userRecent.lines);
+  }
+  if (userProfile.lines.length === 0 && userRecent.lines.length === 0) {
+    userLines.push("No shared facts recorded yet.");
+  }
+  blocks.push(userLines.join("\n"));
+  facts.push(
+    ...injected(userProfile.taken, "user", "", "profile", true),
+    ...injected(userRecent.taken, "user", "", "log", true),
+  );
+  if (input.user.unavailable) {
+    omissions.push({ scope: "user", reason: input.user.unavailable });
+  }
+  if (input.user.omitted) {
+    omissions.push({ scope: "user", reason: input.user.omitted });
+  }
+  const userDropped = userProfile.dropped + userRecent.dropped;
+  if (userDropped > 0) {
+    omissions.push({
+      scope: "user",
+      reason: `${userDropped} shared fact(s) beyond the injection cap were not injected`,
+    });
+  }
+
+  // Project memory, at most three.
+  for (const { entry, profile, recent } of projectFacts) {
+    const shard = memoryShardOfV1(entry.tier.root, input.botId);
+    const lines = [
+      `Project "${entry.project.name}" (${entry.project.projectId}) — your shard: ${shard}:`,
+    ];
+    if (entry.project.description) {
+      lines.push(entry.project.description);
+    }
+    const profileTaken = take(
+      profile,
+      MEMORY_PROJECT_CAPS_V1.profileLimit,
+      MEMORY_PROJECT_CAPS_V1.profileBudget,
+      MEMORY_PROJECT_CAPS_V1.factClamp,
+      true,
+    );
+    const recentTaken = take(
+      recent,
+      MEMORY_PROJECT_CAPS_V1.recentLimit,
+      MEMORY_PROJECT_CAPS_V1.recentBudget,
+      MEMORY_PROJECT_CAPS_V1.factClamp,
+      true,
+    );
+    if (profileTaken.lines.length > 0) {
+      lines.push("About this project (shared):", ...profileTaken.lines);
+    }
+    if (recentTaken.lines.length > 0) {
+      lines.push("Recently (shared):", ...recentTaken.lines);
+    }
+    if (profileTaken.lines.length === 0 && recentTaken.lines.length === 0) {
+      lines.push("No shared facts recorded yet for this project.");
+    }
+    const others = input.joined
+      .filter((project) => project.projectId !== entry.project.projectId)
+      .map((project) => project.projectId);
+    if (others.length > 0) lines.push(`Also a member of: ${others.join(", ")}`);
+    blocks.push(lines.join("\n"));
+    facts.push(
+      ...injected(
+        profileTaken.taken,
+        "project",
+        entry.project.projectId,
+        "profile",
+        true,
+      ),
+      ...injected(
+        recentTaken.taken,
+        "project",
+        entry.project.projectId,
+        "log",
+        true,
+      ),
+    );
+    if (entry.tier.unavailable) {
+      omissions.push({
+        scope: "project",
+        reason: `${entry.project.projectId}: ${entry.tier.unavailable}`,
+      });
+    }
+    if (entry.tier.omitted) {
+      omissions.push({
+        scope: "project",
+        reason: `${entry.project.projectId}: ${entry.tier.omitted}`,
+      });
+    }
+    const dropped = profileTaken.dropped + recentTaken.dropped;
+    if (dropped > 0) {
+      omissions.push({
+        scope: "project",
+        reason: `${entry.project.projectId}: ${dropped} shared fact(s) beyond the injection cap were not injected`,
+      });
+    }
+  }
+  if (input.projects.length > MEMORY_PROJECT_INJECTED_CAP) {
+    omissions.push({
+      scope: "project",
+      reason: `at most ${MEMORY_PROJECT_INJECTED_CAP} joined Projects are injected; ${
+        input.projects.length - MEMORY_PROJECT_INJECTED_CAP
+      } were not`,
+    });
+  }
+
+  // Own memory, last and most specific.
+  const ownProfile = take(
+    ownLive.profile,
+    MEMORY_OWN_CAPS_V1.profileLimit,
+    MEMORY_OWN_CAPS_V1.profileBudget,
+    MEMORY_OWN_CAPS_V1.factClamp,
+    false,
+  );
+  const ownRecent = take(
+    ownLive.recent,
+    MEMORY_OWN_CAPS_V1.recentLimit,
+    MEMORY_OWN_CAPS_V1.recentBudget,
+    MEMORY_OWN_CAPS_V1.factClamp,
+    false,
+  );
+  const ownLines = [OWN_PARAGRAPH];
+  if (ownProfile.lines.length > 0) {
+    ownLines.push("About the user:", ...ownProfile.lines);
+  }
+  if (ownRecent.lines.length > 0) {
+    ownLines.push("Recently:", ...ownRecent.lines);
+  }
+  if (ownProfile.lines.length === 0 && ownRecent.lines.length === 0) {
+    ownLines.push("No facts recorded yet.");
+  }
+  // Faded notes count here: the line points at what is really on disk, and a
+  // faded note is still on disk for the Bot to grep. It is *not* an omission
+  // below, because nothing was cut short.
+  const ownMore = ownRecent.dropped + ownLive.recentFaded;
+  if (ownMore > 0) {
+    ownLines.push(
+      `(${ownMore} more log facts on disk — grep the log/ folder for them.)`,
+    );
+  }
+  blocks.push(ownLines.join("\n"));
+  facts.push(
+    ...injected(ownProfile.taken, "bot", "", "profile", false),
+    ...injected(ownRecent.taken, "bot", "", "log", false),
+  );
+  if (input.own.unavailable) {
+    omissions.push({ scope: "bot", reason: input.own.unavailable });
+  }
+  if (input.own.omitted) {
+    omissions.push({ scope: "bot", reason: input.own.omitted });
+  }
+  const ownDropped = ownProfile.dropped + ownRecent.dropped;
+  if (ownDropped > 0) {
+    omissions.push({
+      scope: "bot",
+      reason: `${ownDropped} own fact(s) beyond the injection cap were not injected`,
+    });
+  }
+
+  return { text: blocks.join("\n\n"), facts, omissions, faded };
+}

package/src/roots.ts

@@ -0,0 +1,158 @@
+// Where a Memory fact lives: which durable root, which shard, which file.
+//
+// "Memory is Markdown files under durable roots of the Workspace in three
+// tiers: a Bot Memory root per Bot, a User Memory root shared by the User's
+// Bots, and a Project Memory root per Project that a Bot has joined."
+//
+// Sharding is not decided here. `memoryShardPathV1` in
+// `@frockbot/kernel-contracts` owns `by-agent/<botId>/`, and this module calls
+// it; a second spelling of the shard prefix is exactly the bug the contract
+// exists to prevent. What this module owns is GrokBot's file layout inside a
+// shard — `profile.md` beside `log/YYYY-MM.md` — and the mapping from a
+// scope name to a root.
+import {
+  memoryShardPathV1,
+  memoryShardPrefixV1,
+  type MemoryScopeNameV1,
+  type WorkspaceMemoryRootV1,
+  type WorkspacePathV1,
+} from "@frockbot/kernel-contracts";
+
+/** The Bot whose Memory is being read or written, and its User. */
+export interface MemoryOwnerV1 {
+  userId: string;
+  botId: string;
+}
+
+/**
+ * The three write tiers within a scope (`docs/research/grokbot-computer.md`
+ * §2.2): `profile` is foundational and kept in mind every Turn, `log` is dated
+ * history and the default, `note` "fades fast". A note is not a separate file:
+ * GrokBot stores it as a `[note] ` prefix on the fact text in the same monthly
+ * log, and so does this Package.
+ */
+export type MemoryTierV1 = "profile" | "log" | "note";
+
+/** The file a `profile`-tier fact is written to, inside a shard. */
+export const MEMORY_PROFILE_FILE = "profile.md";
+/** The directory dated facts live in, inside a shard. */
+export const MEMORY_LOG_DIRECTORY = "log";
+
+const PROJECT_ID = /^[a-z0-9][a-z0-9-]{0,127}$/;
+
+/** True for a Project slug the `project-memory` root will accept. */
+export function isMemoryProjectIdV1(value: unknown): value is string {
+  return typeof value === "string" && PROJECT_ID.test(value);
+}
+
+export function botMemoryRootV1(owner: MemoryOwnerV1): WorkspaceMemoryRootV1 {
+  return { kind: "bot-memory", userId: owner.userId, botId: owner.botId };
+}
+
+export function userMemoryRootV1(owner: MemoryOwnerV1): WorkspaceMemoryRootV1 {
+  return { kind: "user-memory", userId: owner.userId };
+}
+
+export function projectMemoryRootV1(
+  owner: MemoryOwnerV1,
+  projectId: string,
+): WorkspaceMemoryRootV1 {
+  if (!isMemoryProjectIdV1(projectId)) {
+    throw new Error(`Project slug "${projectId}" is invalid`);
+  }
+  return { kind: "project-memory", userId: owner.userId, projectId };
+}
+
+/** The root one scope names, with a Project slug required for `project`. */
+export function memoryScopeRootV1(
+  scope: MemoryScopeNameV1,
+  owner: MemoryOwnerV1,
+  projectId?: string,
+): WorkspaceMemoryRootV1 {
+  if (scope === "bot") return botMemoryRootV1(owner);
+  if (scope === "user") return userMemoryRootV1(owner);
+  if (projectId === undefined) {
+    throw new Error("the project scope requires a Project slug");
+  }
+  return projectMemoryRootV1(owner, projectId);
+}
+
+/** The scope name a root belongs to. */
+export function memoryScopeOfRootV1(
+  root: WorkspaceMemoryRootV1,
+): MemoryScopeNameV1 {
+  if (root.kind === "bot-memory") return "bot";
+  if (root.kind === "user-memory") return "user";
+  return "project";
+}
+
+/** The Project slug a root names, or `""` for the two unprojected tiers. */
+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 {
+  const year = at.getUTCFullYear().toString().padStart(4, "0");
+  const month = (at.getUTCMonth() + 1).toString().padStart(2, "0");
+  return `${MEMORY_LOG_DIRECTORY}/${year}-${month}.md`;
+}
+
+/** 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);
+}
+
+/**
+ * The full path a Bot's fact is written to. Shared roots place it under the
+ * writing Bot's own shard; the Bot Memory root is already single-writer, so
+ * its shard is the root.
+ */
+export function memoryFilePathV1(
+  root: WorkspaceMemoryRootV1,
+  botId: string,
+  tier: MemoryTierV1,
+  at: Date,
+): WorkspacePathV1 {
+  return memoryShardPathV1(root, botId, memoryTierRelativeV1(tier, at));
+}
+
+/** The prefix a Bot's own files sit under; `""` for the Bot Memory root. */
+export function memoryShardOfV1(
+  root: WorkspaceMemoryRootV1,
+  botId: string,
+): string {
+  return memoryShardPrefixV1(root, botId);
+}
+
+/**
+ * Classifies one relative path inside a root as a Memory file, or not.
+ *
+ * A Memory root holds only `profile.md` and `log/*.md` per shard; anything
+ * else — a stray file, a derived index, a directory marker — is data the
+ * renderer ignores rather than parses. The shard prefix is stripped first, so
+ * the same predicate answers for all three tiers.
+ */
+export function memoryFileKindV1(
+  root: WorkspaceMemoryRootV1,
+  relative: string,
+): { kind: "profile" | "log"; shard: string } | undefined {
+  let shard = "";
+  let tail = relative;
+  if (root.kind !== "bot-memory") {
+    const segments = relative.split("/");
+    if (segments.length < 3 || segments[0] !== "by-agent") return undefined;
+    try {
+      shard = decodeURIComponent(segments[1] ?? "");
+    } catch {
+      return undefined;
+    }
+    if (!shard) return undefined;
+    tail = segments.slice(2).join("/");
+  } else {
+    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 };
+  return undefined;
+}