npm - @cursor/july - Versions diffs - 0.1.92 → 0.1.94 - Mend

@cursor/july 0.1.92 → 0.1.94

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (448) hide show

package/dist/docs/storage.html CHANGED Viewed

@@ -9,18 +9,18 @@
     <link rel="preload stylesheet" href="/docs/assets/style.BRuM8477.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
-    <script type="module" src="/docs/assets/app.Bci6CM9E.js"></script>
+    <script type="module" src="/docs/assets/app.CFDEas4I.js"></script>
     <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
-    <link rel="modulepreload" href="/docs/assets/chunks/theme.BEA8BF3c.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/theme.Ct4NSiLm.js">
     <link rel="modulepreload" href="/docs/assets/chunks/framework.BCISBCiQ.js">
-    <link rel="modulepreload" href="/docs/assets/storage.md.JbjlHWZ6.lean.js">
+    <link rel="modulepreload" href="/docs/assets/storage.md.BOHeqk2M.lean.js">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
     <link rel="alternate" type="text/plain" href="/docs/llms.txt">
     <link rel="alternate" type="text/markdown" href="/docs/storage.md">
   </head>
   <body>
-    <div id="app"><div class="Layout" data-v-282c430e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-af8643bc></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-af8643bc>Skip to content</a><!--]--><!----><header class="VPNav" data-v-282c430e data-v-4751689a><div class="VPNavBar" data-v-4751689a data-v-d2a336f3><div class="wrapper" data-v-d2a336f3><div class="container" data-v-d2a336f3><div class="title" data-v-d2a336f3><div class="VPNavBarTitle has-sidebar" data-v-d2a336f3 data-v-3a787a7b><a class="title" href="/docs/" data-v-3a787a7b><!--[--><!--]--><!----><span data-v-3a787a7b>Agent SDK</span><!--[--><!--[--><!--[--><!--[--><span class="agent-sdk-version" title="@cursor/july 0.1.92" data-v-c26a5f4f>0.1.92</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-d2a336f3><div class="content-body" data-v-d2a336f3><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d2a336f3><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d2a336f3 data-v-b60c0a58><span id="main-nav-aria-label" class="visually-hidden" data-v-b60c0a58> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/example-agents/" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Examples</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d2a336f3 data-v-d559fc20><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-d559fc20 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-d2a336f3 data-v-75b97eb1 data-v-ed271fd4><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-ed271fd4><span class="vpi-more-horizontal icon" data-v-ed271fd4></span></button><div class="menu" data-v-ed271fd4><div class="VPMenu" data-v-ed271fd4 data-v-505057d2><!----><!--[--><!--[--><!----><div class="group" data-v-75b97eb1><div class="item appearance" data-v-75b97eb1><p class="label" data-v-75b97eb1>Appearance</p><div class="appearance-action" data-v-75b97eb1><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-75b97eb1 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d2a336f3 data-v-966f1ac7><span class="container" data-v-966f1ac7><span class="top" data-v-966f1ac7></span><span class="middle" data-v-966f1ac7></span><span class="bottom" data-v-966f1ac7></span></span></button></div></div></div></div><div class="divider" data-v-d2a336f3><div class="divider-line" data-v-d2a336f3></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-282c430e data-v-f96f8409><div class="container" data-v-f96f8409><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-f96f8409><span class="vpi-align-left menu-icon" data-v-f96f8409></span><span class="menu-text" data-v-f96f8409>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-f96f8409 data-v-1bc67f4b><button data-v-1bc67f4b>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-282c430e data-v-3d1258d2><div class="curtain" data-v-3d1258d2></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-3d1258d2><span class="visually-hidden" id="sidebar-aria-label" data-v-3d1258d2> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Getting started</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Convert a Cursor Automation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/concepts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Templates</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/demo.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Demo agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agentic Owners</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/pr-autofixer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR autofixer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 has-active" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Improving agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/storage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Guides</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Example agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Choose an example</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/weather-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Weather agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/slack-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/concierge.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concierge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/benny.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playbook router</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/oncall.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Alert investigator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/bugbot.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR evidence reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/approval-buddy.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Approval Buddy</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security Reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/fsd.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Remote PR coordinator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/knowledge-base.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Knowledge base</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/codebase-wiki.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Codebase wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/codeowners-review.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Codeowners review</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Operating</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-282c430e data-v-3b8d81ee><div class="VPDoc has-sidebar has-aside" data-v-3b8d81ee data-v-2e506a34><!--[--><!--]--><div class="container" data-v-2e506a34><div class="aside" data-v-2e506a34><div class="aside-curtain" data-v-2e506a34></div><div class="aside-container" data-v-2e506a34><div class="aside-content" data-v-2e506a34><div class="VPDocAside" data-v-2e506a34 data-v-b485a79e><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-b485a79e data-v-cc6b345c><div class="content" data-v-cc6b345c><div class="outline-marker" data-v-cc6b345c></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-cc6b345c>On this page</div><ul class="VPDocOutlineItem root" data-v-cc6b345c data-v-4f0215bf><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-b485a79e></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-2e506a34><div class="content-container" data-v-2e506a34><!--[--><!--]--><main class="main" data-v-2e506a34><div style="position:relative;" class="vp-doc _docs_storage" data-v-2e506a34><div><h1 id="storage" tabindex="-1">Storage <a class="header-anchor" href="#storage" aria-label="Permalink to &quot;Storage&quot;"></a></h1><p>The Agent SDK owns durable storage for sessions, continuation tokens, reminders, playground eval history, and live A/B samples. It chooses the keys (under <code>agentkit/v1/</code>), when to read and write, and how to restore after restart.</p><p>Keys have bounded length: caller-controlled segments (channel ids, continuation tokens) are URI-encoded, and any segment past 256 encoded bytes is replaced by its <code>sha256:…</code> digest — deterministically, so writes and lookups always agree. Backends can rely on this instead of imposing their own key-length caps (which would silently drop writes, since a throwing <code>put</code> is at-most-once).</p><p>By default that storage lives under <code>--state-root</code> on local disk. Fine for one machine; it does not survive replacing the host.</p><p>To keep the same framework storage across hosts, plug in a key-value backend with <code>agent/storage.ts</code>. You provide <code>put</code> / <code>get</code> / <code>delete</code> / <code>list</code>. The optional <code>cas</code> group adds conditional writes (see <a href="#conditional-writes-the-cas-group">Conditional writes</a>). The Agent SDK does the rest.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/storage.ts</span></span>
+    <div id="app"><div class="Layout" data-v-282c430e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-af8643bc></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-af8643bc>Skip to content</a><!--]--><!----><header class="VPNav" data-v-282c430e data-v-4751689a><div class="VPNavBar" data-v-4751689a data-v-d2a336f3><div class="wrapper" data-v-d2a336f3><div class="container" data-v-d2a336f3><div class="title" data-v-d2a336f3><div class="VPNavBarTitle has-sidebar" data-v-d2a336f3 data-v-3a787a7b><a class="title" href="/docs/" data-v-3a787a7b><!--[--><!--]--><!----><span data-v-3a787a7b>Agent SDK</span><!--[--><!--[--><!--[--><!--[--><span class="agent-sdk-version" title="@cursor/july 0.1.94" data-v-c26a5f4f>0.1.94</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-d2a336f3><div class="content-body" data-v-d2a336f3><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d2a336f3><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d2a336f3 data-v-b60c0a58><span id="main-nav-aria-label" class="visually-hidden" data-v-b60c0a58> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/demo.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d2a336f3 data-v-d559fc20><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-d559fc20 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-d2a336f3 data-v-75b97eb1 data-v-ed271fd4><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-ed271fd4><span class="vpi-more-horizontal icon" data-v-ed271fd4></span></button><div class="menu" data-v-ed271fd4><div class="VPMenu" data-v-ed271fd4 data-v-505057d2><!----><!--[--><!--[--><!----><div class="group" data-v-75b97eb1><div class="item appearance" data-v-75b97eb1><p class="label" data-v-75b97eb1>Appearance</p><div class="appearance-action" data-v-75b97eb1><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-75b97eb1 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d2a336f3 data-v-966f1ac7><span class="container" data-v-966f1ac7><span class="top" data-v-966f1ac7></span><span class="middle" data-v-966f1ac7></span><span class="bottom" data-v-966f1ac7></span></span></button></div></div></div></div><div class="divider" data-v-d2a336f3><div class="divider-line" data-v-d2a336f3></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-282c430e data-v-f96f8409><div class="container" data-v-f96f8409><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-f96f8409><span class="vpi-align-left menu-icon" data-v-f96f8409></span><span class="menu-text" data-v-f96f8409>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-f96f8409 data-v-1bc67f4b><button data-v-1bc67f4b>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-282c430e data-v-3d1258d2><div class="curtain" data-v-3d1258d2></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-3d1258d2><span class="visually-hidden" id="sidebar-aria-label" data-v-3d1258d2> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Getting started</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Convert a Cursor Automation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/concepts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Templates</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/demo.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Demo agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agentic Owners</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/pr-autofixer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR autofixer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 has-active" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Improving agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/storage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Guides</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Operating</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-282c430e data-v-3b8d81ee><div class="VPDoc has-sidebar has-aside" data-v-3b8d81ee data-v-2e506a34><!--[--><!--]--><div class="container" data-v-2e506a34><div class="aside" data-v-2e506a34><div class="aside-curtain" data-v-2e506a34></div><div class="aside-container" data-v-2e506a34><div class="aside-content" data-v-2e506a34><div class="VPDocAside" data-v-2e506a34 data-v-b485a79e><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-b485a79e data-v-cc6b345c><div class="content" data-v-cc6b345c><div class="outline-marker" data-v-cc6b345c></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-cc6b345c>On this page</div><ul class="VPDocOutlineItem root" data-v-cc6b345c data-v-4f0215bf><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-b485a79e></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-2e506a34><div class="content-container" data-v-2e506a34><!--[--><!--]--><main class="main" data-v-2e506a34><div style="position:relative;" class="vp-doc _docs_storage" data-v-2e506a34><div><h1 id="storage" tabindex="-1">Storage <a class="header-anchor" href="#storage" aria-label="Permalink to &quot;Storage&quot;"></a></h1><p>The Agent SDK owns durable storage for sessions, continuation tokens, reminders, playground eval history, and live A/B samples. It chooses the keys, when to read and write, and how to restore after restart.</p><p>The Agent SDK owns key encoding. Backends must accept the keys they are given. Do not fail <code>put</code> to enforce a shorter cap.</p><p>By default that storage lives under <code>--state-root</code> on local disk. Fine for one machine; it does not survive replacing the host.</p><p>To keep the same framework storage across hosts, plug in a key-value backend with <code>agent/storage.ts</code>. You provide <code>put</code> / <code>get</code> / <code>delete</code> / <code>list</code>. The optional <code>cas</code> group adds conditional writes (see <a href="#conditional-writes-the-cas-group">Conditional writes</a>).</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/storage.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/storage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -34,7 +34,7 @@
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    putIfVersion</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">key</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">value</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">expected</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> db.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">casUpdate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(key, value, expected),</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    listKeys</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> db.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">listKeysByPrefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(prefix),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>Import paths here use <code>@cursor/july/storage</code>. On projects still using <code>@anysphere/agent-serve</code>, swap the import. See <a href="/docs/#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="which-fields-to-provide" tabindex="-1">Which fields to provide <a class="header-anchor" href="#which-fields-to-provide" aria-label="Permalink to &quot;Which fields to provide&quot;"></a></h2><p>Implement the small KV core — <code>put</code>/<code>get</code>/<code>delete</code>/<code>list</code> plus the <code>cas</code> group — and you get <strong>full functionality</strong>: eval-run and A/B history are derived over the core automatically. The dedicated <code>evals</code> / <code>abs</code> groups are backend-native optimizations, not required-or-lose-history hooks.</p><table tabindex="0"><thead><tr><th>Field</th><th>Required</th><th>Role</th></tr></thead><tbody><tr><td><code>put</code></td><td>Yes</td><td>Write or update a value</td></tr><tr><td><code>cas</code></td><td>Optional</td><td>Conditional writes; see <a href="#conditional-writes-the-cas-group">Conditional writes</a></td></tr><tr><td><code>get</code></td><td>For restore</td><td>Look up one key (also: derived A/B snapshot backfill)</td></tr><tr><td><code>list</code></td><td>For restore</td><td>Return entries under a prefix, in key order (also: derived eval-runs hydrate)</td></tr><tr><td><code>delete</code></td><td>For cleanup</td><td>Remove a key (also: derived eval-runs pruning)</td></tr><tr><td><code>name</code></td><td>No</td><td>Label surfaced on <code>GET /v1/info</code> diagnostics</td></tr><tr><td><code>policy</code></td><td>No</td><td>Timing knobs; see <a href="#policy">Policy</a></td></tr><tr><td><code>evals</code></td><td>No</td><td>Backend-native eval-runs table; derived over the core when omitted — see <a href="#eval-and-a-b-tables">Eval and A/B tables</a></td></tr><tr><td><code>abs</code></td><td>No</td><td>Backend-native A/B metrics table; derived over the core when omitted — see <a href="#eval-and-a-b-tables">Eval and A/B tables</a></td></tr></tbody></table><p>A throwing <code>put</code> is logged and dropped. It never fails a turn. When resolving a missing continuation token, a throwing <code>get</code> fails the follow-up so a store outage does not open a new session. Return <code>undefined</code> only for a real miss.</p><h2 id="eval-and-a-b-tables" tabindex="-1">Eval and A/B tables <a class="header-anchor" href="#eval-and-a-b-tables" aria-label="Permalink to &quot;Eval and A/B tables&quot;"></a></h2><p>Two dedicated table groups carry structured rows instead of opaque KV values. Both are <strong>optional optimizations</strong>: when a group is not authored, <code>defineStorage</code> derives it over the KV core, so a backend that implements only the core loses nothing. Author a group only when the backend has a better native shape (a real database table, an analytics pipeline) — the built-in <code>fileKv</code> and <code>cursorHostedStorage</code> both do.</p><p><code>evals</code> keeps playground eval batches across restarts (<code>put</code>, <code>delete</code>, <code>list</code> over run snapshots keyed by <code>runId</code>). The Agent SDK upserts a snapshot as a batch starts, progresses, and finishes, prunes runs past the playground history window, and lists everything back at serve start. <strong>Derived form</strong>: one key per run under <code>agentkit/v1/{agent}/eval-runs/{runId}</code> — needs core <code>put</code> + <code>delete</code> + <code>list</code>. Only a core missing <code>delete</code> or <code>list</code> leaves eval history in process memory (cleared on restart). See <a href="./evals.html#configure-eval-runs">Evals</a>.</p><p><code>abs</code> exports live A/B metrics: <code>putSample</code> appends one cumulative metric sample per enrolled experiment on each completed or failed turn; optional <code>putSnapshot</code> / <code>getSnapshot</code> store and serve back the latest aggregate so a replacement host with no local sessions can still serve the A/Bs surface. <strong>Derived form</strong>: each sample lands as its own key (<code>agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}</code> — a blind append-only put, never a read-modify-write of one growing array) and the snapshot lives at the fixed <code>agentkit/v1/{agent}/ab-snapshot</code> key (last-write-wins is correct for &quot;latest aggregate&quot;). <code>putSample</code> and <code>putSnapshot</code> need only core <code>put</code>; <code>getSnapshot</code> needs core <code>get</code>. Session event logs remain the assignment source of truth either way. See <a href="./ab.html">Live A/B metrics</a>.</p><h2 id="policy" tabindex="-1">Policy <a class="header-anchor" href="#policy" aria-label="Permalink to &quot;Policy&quot;"></a></h2><p>Two knobs change behavior:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="which-fields-to-provide" tabindex="-1">Which fields to provide <a class="header-anchor" href="#which-fields-to-provide" aria-label="Permalink to &quot;Which fields to provide&quot;"></a></h2><p>Implement the small KV core (<code>put</code>/<code>get</code>/<code>delete</code>/<code>list</code> plus the <code>cas</code> group) and you get <strong>full functionality</strong>: eval-run and A/B history are derived over the core automatically. The dedicated <code>evals</code> / <code>abs</code> groups are backend-native optimizations, not required-or-lose-history hooks.</p><table tabindex="0"><thead><tr><th>Field</th><th>Required</th><th>Role</th></tr></thead><tbody><tr><td><code>put</code></td><td>Yes</td><td>Write or update a value</td></tr><tr><td><code>cas</code></td><td>Optional</td><td>Conditional writes; see <a href="#conditional-writes-the-cas-group">Conditional writes</a></td></tr><tr><td><code>get</code></td><td>For restore</td><td>Look up one key</td></tr><tr><td><code>list</code></td><td>For restore</td><td>Return entries under a prefix, in key order</td></tr><tr><td><code>delete</code></td><td>For cleanup</td><td>Remove a key</td></tr><tr><td><code>name</code></td><td>No</td><td>Label surfaced on <code>GET /v1/info</code> diagnostics</td></tr><tr><td><code>policy</code></td><td>No</td><td>Timing knobs; see <a href="#policy">Policy</a></td></tr><tr><td><code>evals</code></td><td>No</td><td>Backend-native eval-runs table; derived over the core when omitted. See <a href="#eval-and-a-b-tables">Eval and A/B tables</a></td></tr><tr><td><code>abs</code></td><td>No</td><td>Backend-native A/B metrics table; derived over the core when omitted. See <a href="#eval-and-a-b-tables">Eval and A/B tables</a></td></tr></tbody></table><p>A throwing <code>put</code> is logged and dropped. It never fails a turn. When resolving a missing continuation token, a throwing <code>get</code> fails the follow-up so a store outage does not open a new session. Return <code>undefined</code> only for a real miss.</p><h2 id="eval-and-a-b-tables" tabindex="-1">Eval and A/B tables <a class="header-anchor" href="#eval-and-a-b-tables" aria-label="Permalink to &quot;Eval and A/B tables&quot;"></a></h2><p>Two dedicated table groups carry structured rows instead of opaque KV values. Both are <strong>optional optimizations</strong>: when a group is not authored, <code>defineStorage</code> derives it over the KV core, so a backend that implements only the core loses nothing. Author a group only when the backend has a better native shape (a real database table, an analytics pipeline). The built-in <code>fileKv</code> and <code>cursorHostedStorage</code> both do.</p><p><code>evals</code> keeps playground eval batches across restarts (<code>put</code>, <code>delete</code>, <code>list</code> over run snapshots keyed by <code>runId</code>). A core missing <code>delete</code> or <code>list</code> leaves eval history in memory until restart. See <a href="./evals.html#configure-eval-runs">Evals</a>.</p><p><code>abs</code> exports live A/B metrics: <code>putSample</code> appends one cumulative metric sample per enrolled experiment on each completed or failed turn; optional <code>putSnapshot</code> / <code>getSnapshot</code> store and serve back the latest aggregate so a replacement host can still serve the A/Bs surface. <code>putSample</code> and <code>putSnapshot</code> need only core <code>put</code>; <code>getSnapshot</code> needs core <code>get</code>. Session event logs remain the assignment source of truth either way. See <a href="./ab.html">Live A/B metrics</a>.</p><h2 id="policy" tabindex="-1">Policy <a class="header-anchor" href="#policy" aria-label="Permalink to &quot;Policy&quot;"></a></h2><p>Two knobs change behavior:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: {</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // Batch event writes while the session is busy (default: once per turn)</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    debounceMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">30_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -42,15 +42,15 @@
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    restore: { maxSessions: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">500</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // put / get / delete / list …</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Knob</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code>debounceMs</code></td><td>unset (once per turn)</td><td>Wait this long after activity before writing event batches</td></tr><tr><td><code>restore</code></td><td>caps below</td><td>How much to load at serve start</td></tr><tr><td><code>restore.maxSessions</code></td><td><code>1000</code></td><td>Max sessions loaded at serve start</td></tr><tr><td><code>restore.maxAgeMs</code></td><td>30 days</td><td>Skip older sessions at serve start</td></tr><tr><td><code>restore.maxTotalBytes</code></td><td>1 GiB</td><td>Stop loading once this budget is reached</td></tr></tbody></table><p>Set <code>restore: &quot;off&quot;</code> on high-traffic hosts. Sessions then load when a follow-up arrives instead of at startup.</p><h2 id="restore-after-restart" tabindex="-1">Restore after restart <a class="header-anchor" href="#restore-after-restart" aria-label="Permalink to &quot;Restore after restart&quot;"></a></h2><p>With <code>get</code> and <code>list</code>, serve can rebuild local state from your store:</p><ul><li>At startup, the Agent SDK loads recent sessions up to the restore caps. Local disk wins when both sides have the same session. Reminders hydrate the same way into <code>--state-root/reminders</code>.</li><li>On demand, a missing continuation token resolves through the store and resumes that session.</li><li>Playground eval history and A/B aggregates can load from the same sink.</li></ul><p>A turn in flight at crash time is not replayed. The next follow-up resumes from the last flushed state.</p><h2 id="author-kv-ctx-host-kv" tabindex="-1">Author KV (<code>ctx.host.kv</code>) <a class="header-anchor" href="#author-kv-ctx-host-kv" aria-label="Permalink to &quot;Author KV (`ctx.host.kv`)&quot;"></a></h2><p>Handlers can store their own JSON under the same sink without minting framework keys:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">put</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alert-memory/abc&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { updated: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> prior</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alert-memory/abc&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>The Agent SDK prefixes author keys as <code>agentkit/v1/{agent}/kv/{key}</code> (same bounded encoding as continuation tokens). Writes <strong>await</strong> the sink and propagate errors — unlike session mirrors, which are at-most-once.</p><p>Without <code>agent/storage.ts</code>, <code>host.kv</code> falls back to files under <code>--state-root/kv</code>. That is fine for local dogfood; it does <strong>not</strong> survive replacing the host. For Cursor-managed hosting, prefer <code>@cursor/july/storage/cursor-hosted</code> so sessions and author KV share the platform Bugbot tables through a control-plane HTTP proxy (authenticated as the deployment pod credential — engines never receive a database URL).</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/storage.ts — Cursor-managed hosting</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Knob</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code>debounceMs</code></td><td>unset (once per turn)</td><td>Wait this long after activity before writing event batches</td></tr><tr><td><code>restore</code></td><td>caps below</td><td>How much to load at serve start</td></tr><tr><td><code>restore.maxSessions</code></td><td><code>1000</code></td><td>Max sessions loaded at serve start</td></tr><tr><td><code>restore.maxAgeMs</code></td><td>30 days</td><td>Skip older sessions at serve start</td></tr><tr><td><code>restore.maxTotalBytes</code></td><td>1 GiB</td><td>Stop loading once this budget is reached</td></tr></tbody></table><p>Set <code>restore: &quot;off&quot;</code> on high-traffic hosts. Sessions then load when a follow-up arrives instead of at startup.</p><h2 id="restore-after-restart" tabindex="-1">Restore after restart <a class="header-anchor" href="#restore-after-restart" aria-label="Permalink to &quot;Restore after restart&quot;"></a></h2><p>With <code>get</code> and <code>list</code>, serve can rebuild local state from your store:</p><ul><li>At startup, the Agent SDK loads recent sessions up to the restore caps.</li><li>On demand, a missing continuation token resolves through the store and resumes that session.</li><li>Playground eval history and A/B aggregates can load from the same sink.</li></ul><p>A turn in flight at crash time is not replayed. The next follow-up resumes from the last flushed state.</p><h2 id="author-kv-ctx-host-kv" tabindex="-1">Author KV (<code>ctx.host.kv</code>) <a class="header-anchor" href="#author-kv-ctx-host-kv" aria-label="Permalink to &quot;Author KV (`ctx.host.kv`)&quot;"></a></h2><p>Handlers can store their own JSON under the same sink without minting framework keys:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">put</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alert-memory/abc&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { updated: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> prior</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alert-memory/abc&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Writes <strong>await</strong> the sink and propagate errors, unlike session mirrors, which are at-most-once.</p><p>Without <code>agent/storage.ts</code>, <code>host.kv</code> is local-only and does not survive replacing the host. Hosted agents should author <code>cursorHostedStorage()</code> so session and <code>host.kv</code> records survive replace.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/storage.ts: Cursor-managed hosting</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/storage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { cursorHostedStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/storage/cursor-hosted&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  ...</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cursorHostedStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Built-in helpers:</p><table tabindex="0"><thead><tr><th>Import</th><th>Backend</th></tr></thead><tbody><tr><td><code>@cursor/july/storage/file-kv</code></td><td>File-per-key under <code>.agent-serve/kv</code></td></tr><tr><td><code>@cursor/july/storage/cursor-hosted</code></td><td>Platform Bugbot <code>agent_serve_*</code> via control-plane proxy</td></tr></tbody></table><h2 id="bring-your-own-backend" tabindex="-1">Bring your own backend <a class="header-anchor" href="#bring-your-own-backend" aria-label="Permalink to &quot;Bring your own backend&quot;"></a></h2><p>There is no built-in Postgres backend on purpose. Cursor&#39;s internal <code>agent_serve_*</code> tables are owned by the backend and reachable only through the hosted proxy, and this doc does not prescribe a schema — what you back the KV with is your call. Any durable store works:</p><ul><li><strong>Local disk</strong> — the built-in <code>fileKv</code> (single process only).</li><li><strong>Object storage (S3-class)</strong> — one object per key; conditional writes map directly onto the contract (<code>putIfAbsent</code> = put with <code>If-None-Match: *</code>, <code>putIfVersion</code> = put with <code>If-Match: &lt;etag&gt;</code>, the ETag is the version token, <code>listKeys</code> is a prefix listing).</li><li><strong>Redis, DynamoDB, a SQL table, …</strong> — anything that can do an atomic compare-and-set and a prefix listing.</li></ul><p>Implement the <code>StorageConfig</code> methods (and the optional <code>cas</code> group) against that store. The contract, defined at <code>@cursor/july/kv</code>: version tokens are opaque strings that change on every successful write — including plain <code>put</code>, so a stale token fences instead of clobbering; conditional writes are atomic; <code>listKeys</code> returns every key under the prefix. <code>@cursor/july/kv/memory</code> is a complete reference implementation to compare behavior against.</p><h2 id="conditional-writes-the-cas-group" tabindex="-1">Conditional writes (the <code>cas</code> group) <a class="header-anchor" href="#conditional-writes-the-cas-group" aria-label="Permalink to &quot;Conditional writes (the `cas` group)&quot;"></a></h2><p>The <code>cas</code> group is compare-and-swap over the same keyspace: <code>getWithVersion</code> / <code>putIfAbsent</code> / <code>putIfVersion</code> / <code>listKeys</code>, defined backend-agnostically at <code>@cursor/july/kv</code>. Plain storage works without it, so an existing backend keeps working across a platform upgrade. <code>defineStorage</code> rejects a partial group — implement all four methods or none. Version tokens are opaque strings that must change on every write (a counter column, a row version, a content hash). The built-in backends both include it: <code>fileKv</code> uses content-hash tokens (single-process correctness) and <code>cursorHostedStorage</code> the control-plane proxy (a <code>version</code> counter on the server). <code>memoryCasTable()</code> is for test fixtures and inert sinks only.</p></div></div></main><footer class="VPDocFooter" data-v-2e506a34 data-v-574f06fa><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-574f06fa><span class="visually-hidden" id="doc-footer-aria-label" data-v-574f06fa>Pager</span><div class="pager" data-v-574f06fa><a class="VPLink link pager-link prev" href="/docs/ab.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Previous page</span><span class="title" data-v-574f06fa>Live A/B metrics</span><!--]--></a></div><div class="pager" data-v-574f06fa><a class="VPLink link pager-link next" href="/docs/hillclimbing.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Next page</span><span class="title" data-v-574f06fa>Hillclimbing</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"CVzWxLoB\",\"building-with-agents.md\":\"DH8A_cHA\",\"concepts.md\":\"CRfU3bVg\",\"deployment.md\":\"DX_hc3ze\",\"evals.md\":\"a0SMN6r9\",\"example-agents_approval-buddy.md\":\"DNL83puR\",\"example-agents_benny.md\":\"C40vHRLc\",\"example-agents_bugbot.md\":\"BRGMi9O2\",\"example-agents_codebase-wiki.md\":\"Dftj_tPp\",\"example-agents_codeowners-review.md\":\"Bfta-lBU\",\"example-agents_concierge.md\":\"MrKpQndp\",\"example-agents_fsd.md\":\"ZWHWWZPE\",\"example-agents_index.md\":\"QZ8mhr6n\",\"example-agents_knowledge-base.md\":\"DqKqHQ9u\",\"example-agents_oncall.md\":\"DK4XkYTd\",\"example-agents_security-reviewer.md\":\"Bai6D0Ee\",\"example-agents_slack-agent.md\":\"D7Kdj5BV\",\"example-agents_weather-agent.md\":\"lVEAbWFf\",\"guides_agent-to-agent.md\":\"BCeVdJRJ\",\"guides_cloud-runtime.md\":\"BSMLIBHr\",\"guides_convert-automation.md\":\"D06eIzea\",\"guides_github.md\":\"Cdt1s2QC\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_mcp-oauth.md\":\"Du0f7pGU\",\"guides_opentelemetry.md\":\"bmPmkvJu\",\"guides_slack.md\":\"DiUmk_Oi\",\"guides_webhooks.md\":\"BpnIdO0i\",\"hillclimbing.md\":\"ywF3yDAd\",\"index.md\":\"BAaMXLFd\",\"quickstart.md\":\"DsrarzEg\",\"reference_agent-config.md\":\"Bqylgw50\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"DQZjCnyh\",\"reference_cli.md\":\"B7GkAJRC\",\"reference_connections.md\":\"DYidrb-j\",\"reference_hooks.md\":\"B9FSgdDe\",\"reference_http-api.md\":\"CSHVobzG\",\"reference_instructions.md\":\"DhNCOl7r\",\"reference_playground.md\":\"Dfb92yQf\",\"reference_project-layout.md\":\"CwkSbEWT\",\"reference_prompt.md\":\"DZUMtLPD\",\"reference_schedules.md\":\"DNipebiG\",\"reference_sessions.md\":\"tUFzz98S\",\"reference_skills.md\":\"B5ZEuHfG\",\"reference_subagents.md\":\"Xoav0AII\",\"reference_tools.md\":\"wpaJtHn6\",\"scaffolding-agents.md\":\"CRDDUtYJ\",\"storage.md\":\"JbjlHWZ6\",\"templates_agentic-owners.md\":\"DSJSIpWU\",\"templates_demo.md\":\"DhFcWN6j\",\"templates_pr-autofixer.md\":\"1HAR3RXE\",\"templates_security-reviewer.md\":\"ByFyRta2\",\"templates_triage.md\":\"CVlpctKS\",\"troubleshooting.md\":\"DYECCZiJ\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.92\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Built-in helpers:</p><table tabindex="0"><thead><tr><th>Import</th><th>Backend</th></tr></thead><tbody><tr><td><code>@cursor/july/storage/file-kv</code></td><td>File-per-key under the project state directory</td></tr><tr><td><code>@cursor/july/storage/cursor-hosted</code></td><td>Cursor-managed hosting; records survive replace</td></tr></tbody></table><h2 id="bring-your-own-backend" tabindex="-1">Bring your own backend <a class="header-anchor" href="#bring-your-own-backend" aria-label="Permalink to &quot;Bring your own backend&quot;"></a></h2><p>Any durable store works if it can put, get, delete, list by prefix, and optionally compare-and-set. Implement the <code>StorageConfig</code> methods (and the optional <code>cas</code> group) against that store. The contract, defined at <code>@cursor/july/kv</code>: version tokens are opaque strings that change on every successful write, including plain <code>put</code>, so a stale token fences instead of clobbering; conditional writes are atomic; <code>listKeys</code> returns every key under the prefix.</p><h2 id="conditional-writes-the-cas-group" tabindex="-1">Conditional writes (the <code>cas</code> group) <a class="header-anchor" href="#conditional-writes-the-cas-group" aria-label="Permalink to &quot;Conditional writes (the `cas` group)&quot;"></a></h2><p>The <code>cas</code> group is compare-and-swap over the same keyspace: <code>getWithVersion</code> / <code>putIfAbsent</code> / <code>putIfVersion</code> / <code>listKeys</code>, defined backend-agnostically at <code>@cursor/july/kv</code>. Plain storage works without it, so an existing backend keeps working across a platform upgrade. <code>defineStorage</code> rejects a partial group. Implement all four methods or none. Version tokens are opaque strings that must change on every write (a counter column, a row version, a content hash). The built-in backends both include the group.</p></div></div></main><footer class="VPDocFooter" data-v-2e506a34 data-v-574f06fa><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-574f06fa><span class="visually-hidden" id="doc-footer-aria-label" data-v-574f06fa>Pager</span><div class="pager" data-v-574f06fa><a class="VPLink link pager-link prev" href="/docs/ab.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Previous page</span><span class="title" data-v-574f06fa>Live A/B metrics</span><!--]--></a></div><div class="pager" data-v-574f06fa><a class="VPLink link pager-link next" href="/docs/hillclimbing.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Next page</span><span class="title" data-v-574f06fa>Hillclimbing</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DJo5r4R-\",\"building-with-agents.md\":\"DI4mEzlt\",\"concepts.md\":\"lwAgBIMI\",\"deployment.md\":\"D9msOFOW\",\"evals.md\":\"lfJoEVc8\",\"guides_agent-to-agent.md\":\"BDb0t1QV\",\"guides_cloud-runtime.md\":\"CkYbjnAX\",\"guides_convert-automation.md\":\"B4sjlodG\",\"guides_github.md\":\"Cnh2mL4a\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_mcp-oauth.md\":\"DPYmBCbV\",\"guides_opentelemetry.md\":\"bmPmkvJu\",\"guides_slack.md\":\"C32HsdKk\",\"guides_webhooks.md\":\"DKdA43Qm\",\"hillclimbing.md\":\"DhESf3OO\",\"index.md\":\"DRakGHFe\",\"quickstart.md\":\"Nj_LjW_a\",\"reference_agent-config.md\":\"Cp_x38Nl\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"Cd2f2iyV\",\"reference_cli.md\":\"Cw6_ICYG\",\"reference_connections.md\":\"BH8Oc0D0\",\"reference_hooks.md\":\"a8BJxMR5\",\"reference_http-api.md\":\"D89k1mdm\",\"reference_instructions.md\":\"CR7XSsGk\",\"reference_playground.md\":\"DnX5nL-B\",\"reference_project-layout.md\":\"Bv4KOtlB\",\"reference_prompt.md\":\"DnaD5dNK\",\"reference_schedules.md\":\"DI_JrHgq\",\"reference_sessions.md\":\"D0mIh4KK\",\"reference_skills.md\":\"8son6Hjm\",\"reference_subagents.md\":\"CfsIloPm\",\"reference_tools.md\":\"BHeXn2id\",\"scaffolding-agents.md\":\"D7UUkWw0\",\"storage.md\":\"BOHeqk2M\",\"templates_agentic-owners.md\":\"DqtPdm6f\",\"templates_demo.md\":\"DhFcWN6j\",\"templates_pr-autofixer.md\":\"DU7dQpor\",\"templates_security-reviewer.md\":\"CTa7u_l1\",\"templates_triage.md\":\"CVlpctKS\",\"troubleshooting.md\":\"Ctv3T8C2\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.94\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Templates\",\"link\":\"/templates/demo\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
   </body>
 </html>

package/dist/docs/storage.md CHANGED Viewed

@@ -2,15 +2,10 @@
 The Agent SDK owns durable storage for sessions, continuation tokens,
 reminders, playground eval history, and live A/B samples. It chooses the
-keys (under `agentkit/v1/`), when to read and write, and how to restore
-after restart.
+keys, when to read and write, and how to restore after restart.
-Keys have bounded length: caller-controlled segments (channel ids,
-continuation tokens) are URI-encoded, and any segment past 256 encoded
-bytes is replaced by its `sha256:…` digest — deterministically, so writes
-and lookups always agree. Backends can rely on this instead of imposing
-their own key-length caps (which would silently drop writes, since a
-throwing `put` is at-most-once).
+The Agent SDK owns key encoding. Backends must accept the keys they are
+given. Do not fail `put` to enforce a shorter cap.
 By default that storage lives under `--state-root` on local disk. Fine
 for one machine; it does not survive replacing the host.
@@ -18,8 +13,7 @@ for one machine; it does not survive replacing the host.
 To keep the same framework storage across hosts, plug in a key-value
 backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
 `list`. The optional `cas` group adds conditional writes (see
-[Conditional writes](#conditional-writes-the-cas-group)). The Agent SDK
-does the rest.
+[Conditional writes](#conditional-writes-the-cas-group)).
 ```ts
 // agent/storage.ts
@@ -39,15 +33,10 @@ export default defineStorage({
 });
 ```
-> [!NOTE]
-> Import paths here use `@cursor/july/storage`. On projects still
-> using `@anysphere/agent-serve`, swap the import. See
-> [Run the CLI](/docs/index.md#run-the-cli) for the full rename table.
 ## Which fields to provide
-Implement the small KV core — `put`/`get`/`delete`/`list` plus the `cas`
-group — and you get **full functionality**: eval-run and A/B history are
+Implement the small KV core (`put`/`get`/`delete`/`list` plus the `cas`
+group) and you get **full functionality**: eval-run and A/B history are
 derived over the core automatically. The dedicated `evals` / `abs` groups
 are backend-native optimizations, not required-or-lose-history hooks.
@@ -55,13 +44,13 @@ are backend-native optimizations, not required-or-lose-history hooks.
 | --- | --- | --- |
 | `put` | Yes | Write or update a value |
 | `cas` | Optional | Conditional writes; see [Conditional writes](#conditional-writes-the-cas-group) |
-| `get` | For restore | Look up one key (also: derived A/B snapshot backfill) |
-| `list` | For restore | Return entries under a prefix, in key order (also: derived eval-runs hydrate) |
-| `delete` | For cleanup | Remove a key (also: derived eval-runs pruning) |
+| `get` | For restore | Look up one key |
+| `list` | For restore | Return entries under a prefix, in key order |
+| `delete` | For cleanup | Remove a key |
 | `name` | No | Label surfaced on `GET /v1/info` diagnostics |
 | `policy` | No | Timing knobs; see [Policy](#policy) |
-| `evals` | No | Backend-native eval-runs table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
-| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
+| `evals` | No | Backend-native eval-runs table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
+| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
 A throwing `put` is logged and dropped. It never fails a turn. When
 resolving a missing continuation token, a throwing `get` fails the
@@ -75,30 +64,20 @@ values. Both are **optional optimizations**: when a group is not
 authored, `defineStorage` derives it over the KV core, so a backend that
 implements only the core loses nothing. Author a group only when the
 backend has a better native shape (a real database table, an analytics
-pipeline) — the built-in `fileKv` and `cursorHostedStorage` both do.
+pipeline). The built-in `fileKv` and `cursorHostedStorage` both do.
 `evals` keeps playground eval batches across restarts (`put`, `delete`,
-`list` over run snapshots keyed by `runId`). The Agent SDK upserts a
-snapshot as a batch starts, progresses, and finishes, prunes runs past
-the playground history window, and lists everything back at serve start.
-**Derived form**: one key per run under
-`agentkit/v1/{agent}/eval-runs/{runId}` — needs core `put` + `delete` +
-`list`. Only a core missing `delete` or `list` leaves eval history in
-process memory (cleared on restart). See
-[Evals](/docs/evals.md#configure-eval-runs).
+`list` over run snapshots keyed by `runId`). A core missing `delete` or
+`list` leaves eval history in memory until restart.
+See [Evals](/docs/evals.md#configure-eval-runs).
 `abs` exports live A/B metrics: `putSample` appends one cumulative
 metric sample per enrolled experiment on each completed or failed turn;
 optional `putSnapshot` / `getSnapshot` store and serve back the latest
-aggregate so a replacement host with no local sessions can still serve
-the A/Bs surface. **Derived form**: each sample lands as its own key
-(`agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` — a
-blind append-only put, never a read-modify-write of one growing array)
-and the snapshot lives at the fixed `agentkit/v1/{agent}/ab-snapshot`
-key (last-write-wins is correct for "latest aggregate"). `putSample` and
-`putSnapshot` need only core `put`; `getSnapshot` needs core `get`.
-Session event logs remain the assignment source of truth either way. See
-[Live A/B metrics](/docs/ab.md).
+aggregate so a replacement host can still serve the A/Bs surface.
+`putSample` and `putSnapshot` need only core `put`; `getSnapshot` needs
+core `get`. Session event logs remain the assignment source of truth
+either way. See [Live A/B metrics](/docs/ab.md).
 ## Policy
@@ -132,8 +111,6 @@ follow-up arrives instead of at startup.
 With `get` and `list`, serve can rebuild local state from your store:
 - At startup, the Agent SDK loads recent sessions up to the restore caps.
-  Local disk wins when both sides have the same session. Reminders
-  hydrate the same way into `--state-root/reminders`.
 - On demand, a missing continuation token resolves through the store
   and resumes that session.
 - Playground eval history and A/B aggregates can load from the same
@@ -152,19 +129,16 @@ await ctx.host.kv.put("alert-memory/abc", { updated: "…" });
 const prior = await ctx.host.kv.get("alert-memory/abc");
 ```
-The Agent SDK prefixes author keys as `agentkit/v1/{agent}/kv/{key}` (same
-bounded encoding as continuation tokens). Writes **await** the sink and
-propagate errors — unlike session mirrors, which are at-most-once.
+Writes **await** the sink and propagate errors, unlike session mirrors,
+which are at-most-once.
-Without `agent/storage.ts`, `host.kv` falls back to files under
-`--state-root/kv`. That is fine for local dogfood; it does **not**
-survive replacing the host. For Cursor-managed hosting, prefer
-`@cursor/july/storage/cursor-hosted` so sessions and author KV share the
-platform Bugbot tables through a control-plane HTTP proxy (authenticated
-as the deployment pod credential — engines never receive a database URL).
+Without `agent/storage.ts`, `host.kv` is local-only and does not
+survive replacing the host. Hosted agents should author
+`cursorHostedStorage()` so session and `host.kv` records survive
+replace.
 ```ts
-// agent/storage.ts — Cursor-managed hosting
+// agent/storage.ts: Cursor-managed hosting
 import { defineStorage } from "@cursor/july/storage";
 import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
@@ -177,32 +151,18 @@ Built-in helpers:
 | Import | Backend |
 | --- | --- |
-| `@cursor/july/storage/file-kv` | File-per-key under `.agent-serve/kv` |
-| `@cursor/july/storage/cursor-hosted` | Platform Bugbot `agent_serve_*` via control-plane proxy |
+| `@cursor/july/storage/file-kv` | File-per-key under the project state directory |
+| `@cursor/july/storage/cursor-hosted` | Cursor-managed hosting; records survive replace |
 ## Bring your own backend
-There is no built-in Postgres backend on purpose. Cursor's internal
-`agent_serve_*` tables are owned by the backend and reachable only
-through the hosted proxy, and this doc does not prescribe a schema —
-what you back the KV with is your call. Any durable store works:
-- **Local disk** — the built-in `fileKv` (single process only).
-- **Object storage (S3-class)** — one object per key; conditional
-  writes map directly onto the contract (`putIfAbsent` = put with
-  `If-None-Match: *`, `putIfVersion` = put with `If-Match: <etag>`,
-  the ETag is the version token, `listKeys` is a prefix listing).
-- **Redis, DynamoDB, a SQL table, …** — anything that can do an
-  atomic compare-and-set and a prefix listing.
-Implement the `StorageConfig` methods (and the optional `cas` group)
-against that store. The
-contract, defined at `@cursor/july/kv`: version tokens are opaque
-strings that change on every successful write — including plain
-`put`, so a stale token fences instead of clobbering; conditional
-writes are atomic; `listKeys` returns every key under the prefix.
-`@cursor/july/kv/memory` is a complete reference implementation to
-compare behavior against.
+Any durable store works if it can put, get, delete, list by prefix,
+and optionally compare-and-set. Implement the `StorageConfig` methods
+(and the optional `cas` group) against that store. The contract,
+defined at `@cursor/july/kv`: version tokens are opaque strings that
+change on every successful write, including plain `put`, so a stale
+token fences instead of clobbering; conditional writes are atomic;
+`listKeys` returns every key under the prefix.
 ## Conditional writes (the `cas` group)
@@ -210,10 +170,7 @@ The `cas` group is compare-and-swap over the same keyspace:
 `getWithVersion` / `putIfAbsent` / `putIfVersion` / `listKeys`, defined
 backend-agnostically at `@cursor/july/kv`. Plain storage works without
 it, so an existing backend keeps working across a platform upgrade.
-`defineStorage` rejects a partial group — implement all four methods or
+`defineStorage` rejects a partial group. Implement all four methods or
 none. Version tokens are opaque strings that must change on every write
 (a counter column, a row version, a content hash). The built-in backends
-both include it: `fileKv` uses content-hash tokens (single-process
-correctness) and `cursorHostedStorage` the control-plane proxy (a
-`version` counter on the server). `memoryCasTable()` is for test fixtures
-and inert sinks only.
+both include the group.