@cursor/july 0.1.22 → 0.1.23

package/src/memory.ts

@@ -0,0 +1,215 @@
+/**
+ * Session memory — a journal of what every session of this agent did, so
+ * later sessions can recall and build on past work.
+ *
+ * The write side is {@link memoryHook}, authored as a thin re-export at
+ * `agent/hooks/memory.ts` (scaffolded by `agentkit init`): after each turn
+ * it appends one record (timestamp, session, user message, final result,
+ * usage) to `<stateRoot>/memory/journal.jsonl`.
+ *
+ * There is no read-side API. The framework symlinks `<stateRoot>/memory`
+ * into every session workspace as `memory/`, so agents read the journal
+ * with their normal file tools (`instructions.md` points them at it). That
+ * filesystem visibility is why memory does not route through
+ * `defineStorage` sinks, which are opaque to the model. A custom
+ * {@link MemoryBackend} (database, vector store, …) supplies its own read
+ * path — typically a server tool under `agent/tools/`, which can resolve
+ * state via `ctx.stateRoot`.
+ *
+ * TODO(agent-store): once agent-serve can mount the agent's AgentStore
+ * (durable S3-backed filesystem shared across serve hosts and cloud VMs),
+ * ship an AgentStore-backed backend and make it the default. The journal
+ * format is designed to survive that move unchanged.
+ */
+
+import { appendFile, mkdir, rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { defineHook } from "./hooks.js";
+import type { HookContext, HookDefinition, TurnUsage } from "./types.js";
+
+/** Name of the shared memory directory under the agent state root. */
+export const MEMORY_DIR_NAME = "memory";
+
+/** One journal line: what a single turn did. */
+export type TurnMemoryRecord = {
+  /** ISO timestamp of when the turn finished. */
+  at: string;
+  sessionId: string;
+  channelId: string;
+  status: "completed" | "failed";
+  /** Session title, when the channel set one. */
+  title?: string;
+  /** Cursor SDK agent id (cloud: `bc-…`; local: the session id). */
+  sdkAgentId?: string;
+  /** The user message that started the turn (truncated). */
+  userMessage?: string;
+  /** Final assistant text of the turn, or the failure message (truncated). */
+  result?: string;
+  usage?: TurnUsage;
+};
+
+/** Where turn records go. Receives the agent's state root per append. */
+export interface MemoryBackend {
+  appendTurn(
+    record: TurnMemoryRecord,
+    ctx: { stateRoot: string }
+  ): Promise<void>;
+}
+
+export interface FileMemoryBackendOptions {
+  /**
+   * Rotate `journal.jsonl` to a timestamped sibling once it exceeds this
+   * size, keeping the file agents grep small. Default 5 MiB.
+   */
+  maxJournalBytes?: number;
+}
+
+/**
+ * Default backend: append-only JSONL at `<stateRoot>/memory/journal.jsonl`
+ * — the directory the framework symlinks into session workspaces. Rotated
+ * segments stay alongside as `journal-<epoch-ms>.jsonl`.
+ */
+export function fileMemoryBackend(
+  options: FileMemoryBackendOptions = {}
+): MemoryBackend {
+  const maxJournalBytes = options.maxJournalBytes ?? 5 * 1024 * 1024;
+  // Event dispatch is serialized per session but concurrent across
+  // sessions, so appends to the shared journal are chained per path. A
+  // failed append must not poison the chain for later turns.
+  const appendChains = new Map<string, Promise<void>>();
+  // Same-millisecond rotations must not reuse a segment name — POSIX
+  // rename would silently replace the earlier archive.
+  let rotationSeq = 0;
+  return {
+    async appendTurn(record, ctx) {
+      const dir = join(ctx.stateRoot, MEMORY_DIR_NAME);
+      const path = join(dir, "journal.jsonl");
+      const prior = appendChains.get(path) ?? Promise.resolve();
+      const next = prior
+        .catch(() => {})
+        .then(async () => {
+          await mkdir(dir, { recursive: true });
+          const size = (await stat(path).catch(() => undefined))?.size ?? 0;
+          if (size >= maxJournalBytes) {
+            rotationSeq += 1;
+            await rename(
+              path,
+              join(dir, `journal-${Date.now()}-${rotationSeq}.jsonl`)
+            );
+          }
+          await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+        });
+      appendChains.set(path, next);
+      await next;
+    },
+  };
+}
+
+export interface MemoryHookOptions {
+  /** Where records go. Defaults to {@link fileMemoryBackend}. */
+  backend?: MemoryBackend;
+  /** Truncation cap for stored userMessage / result text. Default 2000. */
+  maxTextLength?: number;
+}
+
+function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+
+/**
+ * Observe-only hook that journals every turn. Author it as
+ * `agent/hooks/memory.ts`:
+ *
+ * ```ts
+ * import { memoryHook } from "@cursor/july/memory";
+ * export default memoryHook();
+ * ```
+ */
+export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
+  const backend = options.backend ?? fileMemoryBackend();
+  const maxTextLength = options.maxTextLength ?? 2000;
+  // Inbound message per turn (truncated at receipt so large pastes are not
+  // retained), keyed `<sessionId>/<turnId>` — `message.received` and the
+  // turn-end events share a turnId. Entries drop at turn end and any
+  // stragglers (turns that never reached a terminal event) at session end.
+  const pendingMessages = new Map<string, string>();
+  const pendingKey = (ctx: HookContext, turnId: string | undefined): string =>
+    `${ctx.session.id}/${turnId ?? "?"}`;
+
+  const record = async (
+    ctx: HookContext,
+    turnId: string | undefined,
+    status: TurnMemoryRecord["status"],
+    result: string | undefined,
+    usage: TurnUsage | undefined
+  ): Promise<void> => {
+    const key = pendingKey(ctx, turnId);
+    const userMessage = pendingMessages.get(key);
+    pendingMessages.delete(key);
+    const entry: TurnMemoryRecord = {
+      at: new Date().toISOString(),
+      sessionId: ctx.session.id,
+      channelId: ctx.channel.id,
+      status,
+    };
+    if (ctx.session.title !== undefined) {
+      entry.title = ctx.session.title;
+    }
+    if (ctx.session.sdkAgentId !== undefined) {
+      entry.sdkAgentId = ctx.session.sdkAgentId;
+    }
+    if (userMessage !== undefined) {
+      entry.userMessage = userMessage;
+    }
+    if (result !== undefined) {
+      entry.result = truncate(result, maxTextLength);
+    }
+    if (usage !== undefined) {
+      entry.usage = usage;
+    }
+    await backend.appendTurn(entry, { stateRoot: ctx.stateRoot });
+  };
+
+  const sweepSession = (ctx: HookContext): void => {
+    for (const key of pendingMessages.keys()) {
+      if (key.startsWith(`${ctx.session.id}/`)) {
+        pendingMessages.delete(key);
+      }
+    }
+  };
+
+  return defineHook({
+    events: {
+      async "message.received"(event, ctx) {
+        pendingMessages.set(
+          pendingKey(ctx, event.turnId),
+          truncate(event.data.text, maxTextLength)
+        );
+      },
+      async "turn.completed"(event, ctx) {
+        await record(
+          ctx,
+          event.turnId,
+          "completed",
+          event.data.result,
+          event.data.usage
+        );
+      },
+      async "turn.failed"(event, ctx) {
+        await record(
+          ctx,
+          event.turnId,
+          "failed",
+          event.data.message,
+          undefined
+        );
+      },
+      async "session.completed"(_event, ctx) {
+        sweepSession(ctx);
+      },
+      async "session.failed"(_event, ctx) {
+        sweepSession(ctx);
+      },
+    },
+  });
+}

package/src/types.ts

@@ -492,6 +492,11 @@ export interface ToolContext {
   session: SessionInfo;
   /** Absolute path of the session's materialized workspace directory. */
   workspaceDir: string;
+  /**
+   * Absolute path of the agent's durable state root (shared across every
+   * session of this agent).
+   */
+  stateRoot: string;
   /** Shared host services (MCP / GitHub / Slack). */
   host: HostContext;
   /**
@@ -1564,6 +1569,12 @@ export interface HookContext {
   agent: { name: string };
   channel: { id: string; continuationToken: string | null };
   session: SessionInfo;
+  /**
+   * Absolute path of the agent's durable state root (shared across every
+   * session of this agent). Hooks that maintain derived state (e.g. the
+   * memory journal) write here.
+   */
+  stateRoot: string;
 }
 
 export type HookHandler<TEvent extends SessionEvent = SessionEvent> = (