Prism MCP

Instructions

Implementation Reference

• src/tools/sessionMemoryHandlers.ts:958-1036 (handler)

  The core logic for the 'memory_checkout' tool, which reverts a project to a specific past version by loading a historical snapshot and saving it as the current state.

  export async function memoryCheckoutHandler(args: unknown) {
    if (!isMemoryCheckoutArgs(args)) {
      throw new Error("Invalid arguments for memory_checkout");
    }
  
    const { project, target_version } = args;
    const storage = await getStorage();
  
    console.error(
      `[memory_checkout] Reverting project="${project}" to version ${target_version}`
    );
  
    // 1. Find the target snapshot
    const history = await storage.getHistory(project, PRISM_USER_ID, 50);
    const targetState = history.find(h => h.version === target_version);
  
    if (!targetState) {
      const available = history.map(h => `v${h.version}`).join(", ") || "none";
      return {
        content: [{
          type: "text",
          text: `❌ Version ${target_version} not found in history for "${project}".\n\n` +
            `Available versions: ${available}\n\n` +
            `Use memory_history to see the full timeline.`,
        }],
        isError: true,
      };
    }
  
    // 2. Get current state for OCC
    const currentContext = await storage.loadContext(project, "quick", PRISM_USER_ID);
    const currentVersion = currentContext ? (currentContext as Record<string, unknown>).version as number : null;
  
    // 3. Build the revert handoff — copy the historical snapshot but mark it as a revert
    const revertHandoff = {
      ...targetState.snapshot,
      project,
      user_id: PRISM_USER_ID,
      last_summary: `[REVERTED TO v${target_version}] ${targetState.snapshot.last_summary || ""}`,
    };
  
    // 4. Save with OCC — pass current version to prevent race conditions
    const result = await storage.saveHandoff(revertHandoff, currentVersion);
  
    if (result.status === "conflict") {
      return {
        content: [{
          type: "text",
          text: `⚠️ Version conflict during checkout! Another session updated the project.\n\n` +
            `Current version: ${result.current_version}\n` +
            `Call session_load_context to see the latest state, then try again.`,
        }],
        isError: true,
      };
    }
  
    // 5. Save the revert itself to history (so you can undo the undo)
    const revertSnapshotEntry = {
      ...revertHandoff,
      version: result.version,
    };
    await storage.saveHistorySnapshot(revertSnapshotEntry).catch(err =>
      console.error(`[memory_checkout] History snapshot of revert failed (non-fatal): ${err}`)
    );
  
    const newVersion = result.version;
  
    return {
      content: [{
        type: "text",
        text: `🕰️ Time travel successful!\n\n` +
          `• Project: "${project}"\n` +
          `• Reverted from: v${currentVersion || "?"} → restored v${target_version}\n` +
          `• New current version: v${newVersion}\n` +
          `• Summary: ${targetState.snapshot.last_summary || "(no summary)"}\n\n` +
          `The project's memory has been restored to the state from ${targetState.created_at}.\n` +
          `This revert is also saved in history, so you can undo it with another memory_checkout.\n\n` +
          `🔑 Remember: pass expected_version: ${newVersion} on your next save.`,
      }],

• src/tools/sessionMemoryDefinitions.ts:464-485 (schema)

  The MCP Tool definition for 'memory_checkout', including its description and input schema.

  export const MEMORY_CHECKOUT_TOOL: Tool = {
    name: "memory_checkout",
    description:
      "Time travel! Restores the project's memory to a specific past version. " +
      "This overwrites the current handoff state with the historical snapshot, " +
      "like a Git revert — the version number moves forward (no data is lost). " +
      "Call memory_history first to find the correct target_version.",
    inputSchema: {
      type: "object",
      properties: {
        project: {
          type: "string",
          description: "Project identifier to revert.",
        },
        target_version: {
          type: "number",
          description: "The version number to restore from history (get this from memory_history).",
        },
      },
      required: ["project", "target_version"],
    },
  };

• src/tools/sessionMemoryDefinitions.ts:500-511 (helper)

  The type guard function to validate arguments for the 'memory_checkout' tool.

  export function isMemoryCheckoutArgs(
    args: unknown
  ): args is { project: string; target_version: number } {
    return (
      typeof args === "object" &&
      args !== null &&
      "project" in args &&
      typeof (args as { project: string }).project === "string" &&
      "target_version" in args &&
      typeof (args as { target_version: number }).target_version === "number"
    );
  }