# Designing an Agent-first API: How we re-architected supermemory
**作者**: Dhravya Shah
**日期**: 2026-10-06T19:24:21.000Z
**来源**: [https://x.com/DhravyaShah/status/2107552558961275145](https://x.com/DhravyaShah/status/2107552558961275145)
---
We've been thinking deep about how we can make supermemory easier and better for agents - and today we're launching a new version of the API designed for agents!
This is the work of the legends in our team [@sohamdaga22](https://x.com/@sohamdaga22), [@ssreeram09](https://x.com/@ssreeram09) and [@maheshthedev](https://x.com/@maheshthedev) 🔥 over just 2 weeks.
Supermemory's API has evolved quite a bit since the very first version in 2024. It was extremely human-centered before - humans understand it, write code, and are happy with the DX.
# DX to AX: Humans are completely out of the loop
It's increasingly clear that agents are writing the code now. Humans are architecting it, telling the agents certain properties that they want, and then going off into the sunset with a glass of wine on the beach. That's life. and it's awesome!
Our API had become insanely overloaded with things humans-could-do. This is mainly because we wanted it to be "dead simple" once someone looks at the API reference, of what they can do with supermemory.
By v4, we had 41 operations split across /v3 and /v4, and MANY fields marked deprecated. Request bodies had become a place to put anything. Responses returned whatever the database had stored word-for-word, so we had a lot of things in the response body that were, absolutely not useful.
A few examples:
- Two search endpoints, with different parameter names for the same things (I have no idea why we kept this in our public spec for the longest time)
- Getting a document returned 23 fields, including internal IDs like activeContentUpdateId and tombstonedAt (???). These were supposed to be internal records only but slowly we started to expose some of them in the return signatures
- Adding one profile bucket meant reading the whole list, appending to it, and writing it all back. If you tried to send back just the bucket you wanted to add, the rest would get deleted.
In hindsight, all of this was quite sloppy and rushed. Rather than patch v4 again, we decided we would rethink everything from first principles and create the surface from scratch.
## simplify, simplify, simplify
So well, the first thing we did is think small: What's the minimum that an agent would need to integrate supermemory into a product?
We made all the fault points clear and now it's just a simple set of operations.
We accidentally made it much easier for humans too! Yay, great bonus.
## Making the scopes clear
There were a few implementations details about supermemory we always had to clarify. This would take a lot of time and mental energy in sales calls, integration docs, and explainers in general.
- Everything is in a "containerTag", or a tenant
- You can do filtering inside the tenant using metadata filters
- When adding, you can do a "filtered write"
- You can pair both of these to build any permissioned system
AAAAA too much to understand.
Now, since everything is in a "containerTag", now called namespaces (much better naming ngl), the boundaries of scoping are much clearer.
So now an agent won't forget to include a namespace, but the scope / boundary will be very clear. Before this was in the body, which was a bit confusing.
## Markdown negotiation.
A lot of our endpoints returned deeply nested JSON that we were expecting developers to parse and read in the right way. This was originally done for better configurability etc.
Now, we still return JSON back, but in almost all endpoints if the agent (or human) is directly calling it, we just send back a perfect crisp markdown back.
This is especially special for our endpoints which are meant to go directly to agents anyways, like
/profile (which gives the agent a general overview of the tenant)
/search (includes deep history of every single information, so that the agent has better knowledge)
This also gives us some superpowers on the server side to keep optimizing and do the best for the users as agents continue to improve!
## /feedback endpoint
The new API version also comes with a /feedback endpoint, which has a smooth integration directly into our slack and stuff, so that agents (or humans) can just submit feedback
And our internal coding agents can get on it right away 🥷
## Better types and naming
There's just three big challenges in programming.
Naming things.
Earlier, each tenant in supermemory was called "containerTags". It was neither a container, nor a tag. And it was insanely confusing to everyone because like, what is a containerTag?! This was the standard question that we had to explain again and again.
And yes, everyone essentially agreed
## Doing the basics right.
Agents have read millions of REST APIs. Every convention we create ourselves is one that is not intuitive to them, and has to be learnt.
So v5 is intentionally boring:
- Standard conventions. Scope goes in the path, short options in the query, content in the body. POST creates, PATCH updates, DELETE takes a list of IDs.
- Type-safe inputs. One filter shape (field, operator, value) shared across search, profile, and list. Boolean flags that changed each other’s behavior (like rerank and aggregate) became a single clean enum.
- Better defaults. For example, search now defaults to hybrid, returning memories and source chunks together, since that's what an agent asking a question usually wants.
- Only what's needed to actually get shit done. Every field we return is something that is relevant to the context window, with the rest being optional. This resulted in GET /document going from 23 fields to 7.
But boring is good. It's easier and more composable so we can rely on this for years until we have to change again 🫡
## Migration strategy
We first tested these changes on our own internal and external SDKs to see how easy it is for agents to adopt it. They nailed it every single time, no questions asked.
This was almost like the perfect design, with the details embedded in the structure of the API directly. No explanations needed!
We want the agents to focus on the right things in the context window not a dump from APIs. so now supermemory handles it very well!
One cool thing now is that we just have a prompt
```
Migrate this repository from Supermemory v3/v4 to v5. Fetch https://supermemory.ai/docs/migration/api-v5.md and follow it. First write a checklist in your reply, not as a file in the repository, of every legacy call site and of every Supermemory-specific name in this codebase: containerTag, containerTags, customId, entityContext, filterByMetadata, filters, including option names, config keys, environment variables and tests. Migrate them one by one and tick each off. Rename those names to the v5 ones (namespace, id, supportingContext, group, filter) with no aliases. A document belongs to exactly one namespace in v5, so a containerTags array becomes one namespace. If an operation has no v5 replacement, do not invent one: keep going, and list it at the end with the alternative the guide suggests.
```
The hope is that the developer just pastes this prompt and boom done :0
We also have set up internal tools to help our customers migrate (there's hundreds of thousands of them so we're hoping to see more traffic move over to the new endpoints), and set up a 3 and 6 month timeline for helping customers move over, after which we will deprecate the old version.
As agents are signing up and using supermemory more and more, we're really excited to make supermemory the most agent ready service out there :)
## 相关链接
- [Dhravya Shah](https://x.com/DhravyaShah)
- [@DhravyaShah](https://x.com/DhravyaShah)
- [23K](https://x.com/DhravyaShah/status/2107552558961275145/analytics)
- [@sohamdaga22](https://x.com/@sohamdaga22)
- [@ssreeram09](https://x.com/@ssreeram09)
- [@maheshthedev](https://x.com/@maheshthedev)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [3:24 AM · Oct 7, 2026](https://x.com/DhravyaShah/status/2107552558961275145)
- [23.4K Views](https://x.com/DhravyaShah/status/2107552558961275145/analytics)
- [View quotes](https://x.com/DhravyaShah/status/2107552558961275145/quotes)
---
*导出时间: 2026/10/7 22:17:45*
---
## 中文翻译
# 设计一个 Agent 优先的 API：我们如何重构 supermemory
**作者**: Dhravya Shah
**日期**: 2026-10-06T19:24:21.000Z
**来源**： [https://x.com/DhravyaShah/status/2107552558961275145](https://x.com/DhravyaShah/status/2107552558961275145)
---
我们一直在深入思考如何让 supermemory 对 agent（智能体）来说更简单、更好——今天，我们推出了一个专为 agent 设计的全新版本的 API！
这是我们团队的传奇人物 [@sohamdaga22](https://x.com/@sohamdaga22)、[@ssreeram09](https://x.com/@ssreeram09) 和 [@maheshthedev](https://x.com/@maheshthedev) 🔥 仅用两周时间完成的作品。
Supermemory 的 API 自 2024 年的第一个版本以来已经演进了不少。以前它极其以人为中心——人类理解它、编写代码，并对开发者体验（DX）感到满意。
# 从 DX 到 AX：人类完全退出了循环
越来越明显的是，现在编写代码的是 agent。人类负责架构设计，告诉 agent 他们想要的某些特性，然后就拿着一杯酒去海滩上享受日落了。这就是生活，而且太棒了！
我们的 API 变得极其臃肿，充满了“人类才能做的事”。这主要是因为我们希望任何人一看到 API 参考文档，就能明白他们可以用 supermemory 做什么，做到“极其简单”。
到了 v4，我们在 /v3 和 /v4 之间分散了 41 个操作，并且有大量字段被标记为已弃用。请求体变成了一个什么东西都能塞的地方。响应则原封不动地返回数据库存储的一切，所以响应体中有很多东西是绝对没用的。
举几个例子：
- 两个搜索端点，同样的东西却用不同的参数名（我不知道为什么我们这么长时间一直在公开规范里保留这个）
- 获取一个文档会返回 23 个字段，包括诸如 activeContentUpdateId 和 tombstonedAt（？？？）这样的内部 ID。这些本来应该只是内部记录，但我们慢慢地开始在返回签名中暴露其中一些
- 添加一个 profile bucket（配置桶）意味着要读取整个列表、追加内容，然后再全部写回。如果你试图只发回你想添加的那个 bucket，其余的都会被删除。
事后看来，这一切都相当草率和仓促。我们决定不再继续修补 v4，而是从第一性原理出发重新思考一切，从零开始创建这个 API 界面。
## 简化，简化，再简化
于是，我们做的第一件事就是往小了想：一个 agent 把 supermemory 集成到产品中所需要的最低要求是什么？
我们把所有的故障点都变得清晰明了，现在它只是一组简单的操作。
我们意外地也让人类用起来更容易了！耶，很棒的额外收获。
## 让作用域更清晰
关于 supermemory 有一些实现细节是我们总是不得不澄清的。这会在销售电话、集成文档和各类讲解中耗费大量时间和精力。
- 一切都在一个 "containerTag" 或租户中
- 你可以使用元数据过滤器在租户内部进行筛选
- 添加时，你可以进行“过滤写入”
- 你可以将这两者结合来构建任何权限系统
AAAAA 要理解的东西太多了。
现在，既然一切都在一个 "containerTag" 中——现在更名为 namespace（命名空间，说实话这个命名好多了）——作用域的边界就清晰多了。
所以现在 agent 不会忘记包含一个命名空间，而且作用域/边界会非常清晰。以前它放在请求体里，有点令人困惑。
## Markdown 协商。
我们的很多端点返回深度嵌套的 JSON，我们期望开发者以正确的方式解析和阅读它们。这最初是为了更好的可配置性等。
现在，我们仍然返回 JSON，但在几乎所有端点中，如果 agent（或人类）直接调用它，我们就会直接返回一份完美简洁的 markdown。
这对于那些本来就是直接面向 agent 的端点来说尤为特殊，比如
/profile（为 agent 提供该租户的总体概览）
/search（包含每条信息的深入历史，让 agent 拥有更好的知识）
这也给了我们在服务器端的一些超能力，随着 agent 的不断改进，我们可以持续优化，为用户提供最好的体验！
## /feedback 端点
新的 API 版本还带有一个 /feedback 端点，它与我们的 Slack 等工具无缝集成，这样 agent（或人类）就可以直接提交反馈
而我们的内部编码 agent 可以立即着手处理 🥷
## 更好的类型和命名
编程只有三大难题。
命名。
以前，supermemory 中的每个租户都叫 "containerTags"。它既不是容器，也不是标签。而且这让所有人都极其困惑，因为，containerTag 到底是什么？！这是我们不得不一遍又一遍解释的标准问题。
而且是的，大家基本上都同意这一点
## 把基础做对。
Agent 们已经读过数以百万计的 REST API。我们自己创造的每一个约定对他们来说都是不直观的，都需要学习。
所以 v5 刻意做得“无聊”：
- 标准约定。作用域放在路径中，短选项放在查询参数中，内容放在请求体中。POST 用于创建，PATCH 用于更新，DELETE 接受一组 ID。
- 类型安全的输入。一个统一的过滤器形状（field、operator、value），在 search、profile 和 list 之间共享。那些会相互改变行为的布尔标志（如 rerank 和 aggregate）变成了一个干净的单一枚举。
- 更好的默认值。例如，搜索现在默认为混合（hybrid）模式，同时返回记忆和源文档分块，因为提出问题的 agent 通常就想要这些。
- 只保留真正把事情办成所需的东西。我们返回的每个字段都是与上下文窗口相关的内容，其余的都是可选的。这使得 GET /document 从 23 个字段减少到 7 个。
但“无聊”是好事。它更简单、更易于组合，所以我们可以依赖它用上好几年，直到不得不再次改变 🫡
## 迁移策略
我们首先在自己的内部和外部 SDK 上测试了这些改动，看看 agent 采用起来有多容易。他们每次都完美搞定，毫无问题。
这几乎就像是完美的设计，细节直接嵌入在 API 的结构中。无需任何解释！
我们希望 agent 能专注于上下文窗口中正确的内容，而不是一堆 API 的垃圾数据。所以现在 supermemory 在这方面处理得非常好！
现在有一个很酷的事情是，我们只需要一个提示词
```
Migrate this repository from Supermemory v3/v4 to v5. Fetch https://supermemory.ai/docs/migration/api-v5.md and follow it. First write a checklist in your reply, not as a file in the repository, of every legacy call site and of every Supermemory-specific name in this codebase: containerTag, containerTags, customId, entityContext, filterByMetadata, filters, including option names, config keys, environment variables and tests. Migrate them one by one and tick each off. Rename those names to the v5 ones (namespace, id, supportingContext, group, filter) with no aliases. A document belongs to exactly one namespace in v5, so a containerTags array becomes one namespace. If an operation has no v5 replacement, do not invent one: keep going, and list it at the end with the alternative the guide suggests.
```
希望开发者只需粘贴这个提示词，砰，搞定 :0
我们还建立了内部工具来帮助我们的客户进行迁移（他们有成千上万个，所以我们希望看到更多流量转移到新的端点），并设立了 3 个月和 6 个月的时间线来帮助客户完成迁移，之后我们将弃用旧版本。
随着越来越多的 agent 注册并使用 supermemory，我们非常期待把 supermemory 打造成市面上对 agent 最友好的服务 :)
## 相关链接
- [Dhravya Shah](https://x.com/DhravyaShah)
- [@DhravyaShah](https://x.com/DhravyaShah)
- [23K](https://x.com/DhravyaShah/status/2107552558961275145/analytics)
- [@sohamdaga22](https://x.com/@sohamdaga22)
- [@ssreeram09](https://x.com/@ssreeram09)
- [@maheshthedev](https://x.com/@maheshthedev)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [3:24 AM · Oct 7, 2026](https://x.com/DhravyaShah/status/2107552558961275145)
- [23.4K Views](https://x.com/DhravyaShah/status/2107552558961275145/analytics)
- [View quotes](https://x.com/DhravyaShah/status/2107552558961275145/quotes)
---
*导出时间: 2026/10/7 22:17:45* 
