Designing an Agent-first API: How we re-architected supermemory
文章目录
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, @ssreeram09 and @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 :)
