@vellumai/assistant 0.10.4-staging.1 → 0.10.4-staging.2

package/src/plugins/defaults/memory/graph/tool-handlers.ts

@@ -0,0 +1,195 @@
+// ---------------------------------------------------------------------------
+// Memory Tool handlers
+//
+// remember: save facts to the PKB (buffer.md + daily archive) under the v1
+// path, or to memory/buffer.md + memory/archive/<today>.md when memory v2 is
+// active.
+// ---------------------------------------------------------------------------
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { AssistantConfig } from "../../../../config/types.js";
+import { getLogger } from "../../../../util/logger.js";
+import { getWorkspaceDir } from "../../../../util/platform.js";
+import { enqueuePkbIndexJob } from "../jobs/embed-pkb-file.js";
+import { PKB_WORKSPACE_SCOPE } from "../pkb/types.js";
+
+const log = getLogger("graph-tool-handlers");
+
+// ---------------------------------------------------------------------------
+// remember handler — writes to PKB (v1) or memory/ (v2) buffer + daily archive
+// ---------------------------------------------------------------------------
+
+export interface RememberInput {
+  /**
+   * The fact(s) to remember. A single string records one fact; an array
+   * records several independent facts in one call (each becomes its own
+   * timestamped entry), so a single turn can batch unrelated facts instead of
+   * calling `remember` once per fact.
+   */
+  content: string | string[];
+  finish_turn?: boolean;
+}
+
+export interface RememberResult {
+  success: boolean;
+  message: string;
+}
+
+/**
+ * Normalize the `remember` content input to a list of non-empty facts.
+ * Accepts the single-string form or the batch array form, trims each fact, and
+ * drops blanks so an empty or whitespace-only input yields no facts.
+ */
+function normalizeFacts(content: string | string[]): string[] {
+  const raw = Array.isArray(content) ? content : [content];
+  return raw
+    .filter((fact): fact is string => typeof fact === "string")
+    .map((fact) => fact.trim())
+    .filter((fact) => fact.length > 0);
+}
+
+function rememberSuccessMessage(count: number): string {
+  return count === 1
+    ? "Saved to knowledge base."
+    : `Saved ${count} facts to knowledge base.`;
+}
+
+export function handleRemember(
+  input: RememberInput,
+  _conversationId: string,
+  _scopeId: string,
+  config: AssistantConfig,
+): RememberResult {
+  const facts = normalizeFacts(input.content);
+  if (facts.length === 0) {
+    return { success: false, message: "content is required" };
+  }
+  if (config.memory.enabled === false) {
+    return { success: false, message: "Memory is disabled." };
+  }
+
+  const workspaceDir = getWorkspaceDir();
+  const now = new Date();
+  // Each fact becomes its own timestamped bullet; a batched call writes them
+  // all in a single append so one turn can record several independent facts.
+  const entry = facts.map((fact) => formatRememberEntry(fact, now)).join("");
+  const message = rememberSuccessMessage(facts.length);
+
+  if (config.memory.v2.enabled) {
+    appendBufferAndArchive({
+      rootDir: join(workspaceDir, "memory"),
+      entry,
+      now,
+    });
+    // v2 path skips the PKB re-index queue — embedding for memory v2 happens
+    // via the dedicated `embed_concept_page` job after consolidation, not on
+    // every remember() write.
+    return { success: true, message };
+  }
+
+  const pkbDir = join(workspaceDir, "pkb");
+  const { bufferPath, archivePath } = appendBufferAndArchive({
+    rootDir: pkbDir,
+    entry,
+    now,
+  });
+  enqueuePkbReindex(pkbDir, bufferPath);
+  enqueuePkbReindex(pkbDir, archivePath);
+
+  return { success: true, message };
+}
+
+/**
+ * Format `now` as a buffer-entry timestamp (`Mon D, h:mm AM/PM`). Exported so
+ * the memory v2 consolidation job can present its cutoff in the same shape
+ * the buffer entries use, making the agent's "timestamp ≥ cutoff" comparison
+ * unambiguous at minute precision.
+ */
+export function formatBufferTimestamp(now: Date): string {
+  const month = now.toLocaleString("en-US", { month: "short" });
+  const day = now.getDate();
+  const hours = now.getHours();
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  const ampm = hours >= 12 ? "PM" : "AM";
+  const displayHour = hours % 12 || 12;
+  return `${month} ${day}, ${displayHour}:${minutes} ${ampm}`;
+}
+
+/**
+ * Build a timestamped bullet entry for `buffer.md` / `archive/<date>.md`.
+ *
+ * Format mirrors the long-standing v1 PKB layout so v2 buffers stay
+ * human-readable and downstream consumers (sweep, consolidation) can parse
+ * the same shape regardless of which path produced the entry.
+ *
+ * Exported so memory v2 sweep / extractor jobs format their auto-remembered
+ * entries identically to user-facing `remember()` calls.
+ */
+export function formatRememberEntry(content: string, now: Date): string {
+  return `- [${formatBufferTimestamp(now)}] ${content}\n`;
+}
+
+/**
+ * Append `entry` to `<rootDir>/buffer.md` and `<rootDir>/archive/<today>.md`,
+ * creating the archive directory and seeding the archive header if missing.
+ *
+ * Returns the absolute paths of both files so callers can fan out follow-up
+ * work (e.g. PKB re-indexing in the v1 path).
+ *
+ * Exported so memory v2 background jobs (`sweep`, future LLM-driven
+ * extractors) can append to `memory/buffer.md` + `memory/archive/<today>.md`
+ * with exactly the same format `remember()` produces, keeping the two write
+ * paths byte-compatible for downstream consumers (consolidation, search).
+ */
+export function appendBufferAndArchive(args: {
+  rootDir: string;
+  entry: string;
+  now: Date;
+}): { bufferPath: string; archivePath: string } {
+  const { rootDir, entry, now } = args;
+  const archiveDir = join(rootDir, "archive");
+  mkdirSync(archiveDir, { recursive: true });
+
+  const bufferPath = join(rootDir, "buffer.md");
+  appendFileSync(bufferPath, entry, "utf-8");
+
+  const yyyy = now.getFullYear();
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  const dd = String(now.getDate()).padStart(2, "0");
+  const archivePath = join(archiveDir, `${yyyy}-${mm}-${dd}.md`);
+  if (!existsSync(archivePath)) {
+    const month = now.toLocaleString("en-US", { month: "short" });
+    appendFileSync(
+      archivePath,
+      `# ${month} ${now.getDate()}, ${yyyy}\n\n`,
+      "utf-8",
+    );
+  }
+  appendFileSync(archivePath, entry, "utf-8");
+
+  return { bufferPath, archivePath };
+}
+
+/**
+ * Fire-and-forget enqueue of a PKB re-index job for a file we just wrote.
+ *
+ * Always indexes under {@link PKB_WORKSPACE_SCOPE}. See the comment on that
+ * constant for why PKB points are not per-conversation-scoped.
+ *
+ * Wrapped in try/catch so an enqueue failure (e.g. DB hiccup) cannot break
+ * the remember call — the write has already succeeded and the user's fact
+ * is safe on disk.
+ */
+function enqueuePkbReindex(pkbRoot: string, absPath: string): void {
+  try {
+    enqueuePkbIndexJob({
+      pkbRoot,
+      absPath,
+      memoryScopeId: PKB_WORKSPACE_SCOPE,
+    });
+  } catch (err) {
+    log.warn({ err, absPath }, "Failed to enqueue PKB re-index job");
+  }
+}

package/src/plugins/defaults/memory/graph/tools.ts

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// Memory Tool definitions for agentic recall and remember.
+// ---------------------------------------------------------------------------
+
+import type { ToolDefinition } from "../../../../providers/types.js";
+import {
+  ALL_RECALL_SOURCES,
+  MAX_RECALL_MAX_RESULTS,
+  MIN_RECALL_MAX_RESULTS,
+} from "../context-search/limits.js";
+
+const RECALL_DEPTHS = ["fast", "standard", "deep"] as const;
+
+/**
+ * Explicit local information search across memory, conversations, and
+ * workspace files.
+ */
+export const graphRecallDefinition = {
+  name: "recall",
+  description:
+    'Search local information the moment you feel uncertain. Use recall for memory, past conversations, and workspace files — before you guess, before you ask, before you hedge. Auto-injection is incomplete by design; it surfaces patterns, not the specifics you need to answer well. If you catch yourself reaching for "I think", "I believe", "if I remember", "didn\'t we", "last time" — that\'s the signal. Recall. If a turn references someone, a place, a decision, a document, or prior work you should be able to find locally — recall. Call it multiple times per conversation if the turn warrants it. Be specific in your query for best results.',
+  input_schema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description:
+          "What you're looking for. Be specific and descriptive: include the topic, person, project, decision, time period, or file clues when known.",
+      },
+      sources: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: [...ALL_RECALL_SOURCES],
+        },
+        description:
+          "Optional local sources to search. Omit to search memory, conversations, and workspace files.",
+      },
+      max_results: {
+        type: "integer",
+        minimum: MIN_RECALL_MAX_RESULTS,
+        maximum: MAX_RECALL_MAX_RESULTS,
+        description: "Maximum number of evidence items to return.",
+      },
+      depth: {
+        type: "string",
+        enum: [...RECALL_DEPTHS],
+        description:
+          "Search effort. Use fast for quick lookups, standard by default, and deep when the answer may require multiple local searches.",
+      },
+    },
+    required: ["query"],
+  },
+} satisfies ToolDefinition;
+
+/**
+ * `remember` tool description. The retrospective pass catches what isn't
+ * captured in the moment, so the in-conversation pressure stays at a
+ * judgment framing: pause when something feels worth marking, not because
+ * the volume is required.
+ */
+const REMEMBER_DESCRIPTION =
+  "Remember anything concrete shared in conversation: corrections, plans, decisions, felt moments, names, dates, commitments, preferences. Corrections are the highest priority — call `remember` the same turn the correction lands. You don't have to call this on every turn; a retrospective pass reviews the conversation after each message-count / time interval and saves what you didn't capture. Use judgment: pause and remember when something feels worth marking, not because the volume is required.";
+
+/**
+ * Save a fact to the assistant's knowledge base. The fact is appended to
+ * `buffer.md` (immediately available in the next conversation) and the daily
+ * archive (permanent date-indexed record). When `memory.v2.enabled` is true,
+ * writes go under `memory/`; otherwise they go under `pkb/`. Consolidation
+ * of the buffer into longer-form storage runs as a separate periodic job in
+ * both modes.
+ */
+export const graphRememberDefinition = {
+  name: "remember",
+  description: REMEMBER_DESCRIPTION,
+  input_schema: {
+    type: "object",
+    properties: {
+      content: {
+        anyOf: [
+          { type: "string" },
+          { type: "array", items: { type: "string" }, minItems: 1 },
+        ],
+        description:
+          "The fact(s) to remember. Pass a single string for one fact, or an array of strings to record several independent facts in one call. When a turn surfaces multiple unrelated facts, pass them all as an array in one call rather than calling `remember` once per fact. Write naturally — a preference, a detail, a commitment, a plan. No need to categorize.",
+      },
+      finish_turn: {
+        type: "boolean",
+        description:
+          "When you have nothing else to say and want to yield the turn you MUST set this to true. When true, your turn ends after this tool call. It's critical that you do this in order to avoid unnecessary LLM calls.",
+      },
+    },
+    required: ["content"],
+  },
+} satisfies ToolDefinition;

package/src/plugins/defaults/memory/hooks/init.ts

@@ -0,0 +1,26 @@
+/**
+ * Memory plugin `init` hook — start the periodic PKB filing/compaction service.
+ *
+ * Skipped under memory v2, whose consolidation job owns periodic background
+ * memory processing; running filing alongside it would be redundant.
+ */
+
+import type { HookFunction, InitContext } from "@vellumai/plugin-api";
+
+import { getConfig } from "../../../../config/loader.js";
+import { getLogger } from "../../../../util/logger.js";
+import { FilingService } from "../filing-service.js";
+
+const log = getLogger("filing-service");
+
+const init: HookFunction<InitContext> = async () => {
+  if (getConfig().memory.v2.enabled) {
+    log.info(
+      "Filing service skipped — memory v2 consolidation is the active background memory job",
+    );
+    return;
+  }
+  new FilingService().start();
+};
+
+export default init;

package/src/plugins/defaults/memory/hooks/post-compact.ts

@@ -0,0 +1,115 @@
+/**
+ * Default `memoryRetrieval` post-compaction hook.
+ *
+ * After the agent loop compacts a conversation mid-turn it must re-apply the
+ * runtime injections — the NOW.md scratchpad, PKB context, memory-v2 static
+ * block, workspace top-level context, Slack chronological snapshot, and the
+ * per-turn context blocks — onto the continuation history before the turn
+ * continues. This hook is the memory system's home for that transform: it
+ * clears any per-turn injection blocks the base already carries on its tail
+ * ({@link stripTailInjectionsForReinjection}) so re-injection is idempotent,
+ * re-applies the injections via {@link applyRuntimeInjections}, writes the
+ * edited history back onto the context, and re-tracks the memory graph's cached
+ * nodes against the re-injected history. The injection blocks the transform
+ * captures are not needed by the re-injection caller, so only the messages
+ * propagate.
+ *
+ * The base the loop hands in is the full injected history (the loop does not
+ * pre-strip it), so the tail strip is what keeps injection idempotency a
+ * property of the injection machinery rather than of the agent loop.
+ *
+ * Every per-turn input the live conversation can supply is self-resolved from
+ * it (looked up by id) rather than threaded in by the loop:
+ * - The trust snapshot comes from the conversation's turn-start trust snapshot
+ *   ({@link Conversation.currentTurnTrustContext}), and the inbound actor
+ *   context from the turn-start actor snapshot
+ *   ({@link Conversation.currentTurnInboundActorContext}) — both frozen at turn
+ *   start, not read live. Post-compaction runs mid-turn in a later tool
+ *   iteration, where the live trust can be overwritten by a concurrent
+ *   request's actor and the contact/member registry the actor context derives
+ *   from can be mutated by contact tools; reading the frozen snapshots re-emits
+ *   the values the turn's initial assembly resolved.
+ * - The memory graph handle comes from the plugin's own conversation-keyed
+ *   registry ({@link getLiveGraphMemory}).
+ * - The call site and transcript inputs self-resolve inside
+ *   {@link applyRuntimeInjections}.
+ *
+ * The loop supplies only the irreducible turn-identity fields on the public
+ * {@link PostCompactContext}.
+ */
+
+import type { HookFunction, PostCompactContext } from "@vellumai/plugin-api";
+
+import { getConfig } from "../../../../config/loader.js";
+import { findConversationOrSubagent } from "../../../../daemon/conversation-registry.js";
+import {
+  applyRuntimeInjections,
+  resolveTurnModelProfileLabel,
+} from "../../../../daemon/conversation-runtime-assembly.js";
+import {
+  FALLBACK_TURN_TRUST,
+  resolveTrustClass,
+} from "../../../../daemon/trust-context.js";
+import { getLiveGraphMemory } from "../graph/conversation-graph-memory.js";
+import { stripTailInjectionsForReinjection } from "../tail-reinjection-strip.js";
+
+const postCompact: HookFunction<PostCompactContext> = async (ctx) => {
+  const {
+    history,
+    requestId,
+    conversationId,
+    isNonInteractive,
+    injectionMode,
+  } = ctx;
+  const mode = injectionMode ?? "full";
+  const config = getConfig();
+  const conversation = findConversationOrSubagent(conversationId);
+  // Trust and the inbound actor context are read from the conversation's
+  // turn-start snapshots rather than live state: post-compaction runs mid-turn
+  // in a later tool iteration, where the live trust can be overwritten by a
+  // concurrent request's actor and the contact/member registry the actor
+  // context derives from can be mutated by contact tools. The snapshots are the
+  // values the turn's initial assembly resolved.
+  const trust =
+    conversation?.currentTurnTrustContext ??
+    conversation?.trustContext ??
+    FALLBACK_TURN_TRUST;
+  const actorContext = conversation?.currentTurnInboundActorContext ?? null;
+  // Render the `model_profile:` label from the turn-start notice key, using
+  // the call site self-resolved from the live conversation — the same
+  // derivation the first-call user-prompt-submit assembly uses.
+  const modelProfile = resolveTurnModelProfileLabel(
+    conversation?.currentTurnModelProfileNoticeKey ?? null,
+    conversation?.currentCallSite ?? "mainAgent",
+    config.llm,
+    conversationId,
+  );
+  // Clear any per-turn injection blocks the base already carries on its tail
+  // before re-injecting, so the continuation history holds a single copy of
+  // each block rather than double-stacking on the injected base the loop hands
+  // in.
+  const strippedHistory = stripTailInjectionsForReinjection(history);
+  const result = await applyRuntimeInjections(strippedHistory, {
+    isNonInteractive,
+    modelProfile,
+    actorContext,
+    mode,
+    requestId,
+    conversationId,
+    trust,
+  });
+  // Write the re-injected history back onto the threaded context; the loop
+  // reads it from there once the hook settles.
+  ctx.history = result.messages;
+  // Re-track the nodes the memory graph last injected so they survive against
+  // the re-injected history. Untrusted actors never received a memory-graph
+  // injection, so there is nothing to re-track. The live graph handle is looked
+  // up from the plugin's own registry by the turn's conversation id — the same
+  // instance the turn's retrieval mutated.
+  const isTrustedActor = resolveTrustClass(trust) === "guardian";
+  if (isTrustedActor) {
+    getLiveGraphMemory(conversationId)?.retrackCachedNodes();
+  }
+};
+
+export default postCompact;

package/src/plugins/defaults/memory/hooks/shutdown.ts

@@ -0,0 +1,14 @@
+/**
+ * Memory plugin `shutdown` hook — stop the periodic PKB filing/compaction
+ * service, draining any in-flight run before the daemon exits.
+ */
+
+import type { HookFunction, ShutdownContext } from "@vellumai/plugin-api";
+
+import { FilingService } from "../filing-service.js";
+
+const shutdown: HookFunction<ShutdownContext> = async () => {
+  await FilingService.getInstance()?.stop();
+};
+
+export default shutdown;