What you get on v2
v2 is a rewrite of the memory layer, not a version bump. Alongside everything v1 did:Knowledge bases
Ingest documents and search them alongside conversational memory, with categories,
topics and tags.
Fix what EverOS remembers
Correct an episode, delete specific memories by id, or add, update and delete
profile items directly, instead of waiting for extraction to correct itself. Rate
memories to track which ones your users reject.
Memory tags
Attach your own labels to memories.
Sharper agent memory
Agent memory splits into reusable skills and distilled cases, retrievable
separately.
Finer retrieval control
Score thresholds, optional LLM reranking, and per-query profile inclusion.
Multi-app scoping
Partition memory by app and project under a single key.
Do I need to do anything?
1
Do you call /api/v1/* ?
Directly over HTTP, or through any client library. If yes, those calls now fail with
403, and you need to migrate.2
Do you depend on everos-cloud 0.4.x or earlier?
Check your
requirements.txt or pyproject.toml for everos-cloud<1,
everos-cloud>=0.4, or the older evermemos package. If yes, you need to migrate.3
Neither?
You are already on v2. Nothing to do.
What happened to your data
We migrated it into v2 as part of the retirement, under the same API key. You do not need to export, re-ingest or backfill anything. v1 was switched off first, so every v1 write was captured. How group memories were mapped is described under Group memory.Migrating your code
Option 1: run the migration tool
The tool runs inside your AI coding assistant. It reads your code and tells you exactly what would change before it changes anything, for the Python SDK and for raw HTTP calls in any language. Start with a report. This edits nothing. In Claude Code--scan (or ask without the words --scan). It snapshots your working tree, works on its
own branch, and rewrites the mechanical parts: the user id moves onto each message,
timestamps become milliseconds, filters becomes user_id, and a handful of fields and
types are renamed. Anything with no v2 equivalent is marked in place rather than guessed
at. If it finds such places it stops and asks before editing; pass --yes to proceed with
them marked. The report ends with the exact command that undoes the run.
Two things the tool does not do: it does not run your test suite, and it does not install
the new package. Do both yourself, against a non-production key, before you switch traffic.
Option 2: by hand
Everything that changes is documented below, in the order you will meet it. Python SDK users should also read Upgrade Python SDK to 1.x: the 1.x SDK speaks only the v2 API, so upgrading it is the migration.Not sure which way to go?
Reply to your migration email, or contact us, and we will talk through your setup and work out a migration plan with you.What changes
Endpoints
Note the singularmemory in v2. A search and replace that only swaps v1 for v2
will not work.
Timestamps must be in milliseconds
v2 rejects a seconds-scale timestamp rather than silently rescaling it, because a batch mixing both scales would mis-order and mis-split sessions.The owner moves onto each message
session_id is now required, between 1 and 128 characters. It is the unit that
extraction works on.
Reads take the owner as a top-level field
user_id or agent_id is required on both get and search. Owner and
type must agree: a user_id owner may ask for episode or profile, an agent_id
owner may ask for agent_case or agent_skill.
Memory type values
New scoping fields
Every memory call acceptsapp_id and project_id, both defaulting to "default".
You can ignore them, but reads must use the same pair as the write. A mismatched pair
returns empty results rather than an error.
This is a partition, not a security boundary. The security boundary is the tenant
resolved from your API key.
Responses
request_id moved to the top level of the envelope, and the human-readable message
field is gone.
search responses, raw_messages becomes unprocessed_messages, and the single
agent_memory object becomes two arrays, agent_cases and agent_skills.
delete returned 204 No Content on v1. On v2 it returns 200 with a body reporting
what matched.
Errors
status_code rather than matching on message. Code that matched the
literal string "HTTP_ERROR" will never match again.
Capabilities that changed shape
Group memory
Group memory
v1 had a group as an addressable object:
/api/v1/memories/group, a /groups
registry, and group_id as a read filter.v2 has no group endpoints, but group data can be mapped onto v2 in several ways, and
the best one depends on how your product uses groups.Unless you asked us for another mapping, each group’s memories were migrated to the v2
project with the same id: group_id: "team-alpha" became project_id: "team-alpha"
(with app_id: "default"). Memories without a group id, or with an auto-assigned id
starting with gen_, went to the default project. A memory with several participants
was migrated as one copy per participant.v2 reads need exactly one of user_id or agent_id, so a query over a whole group
becomes one query per participant.If this mapping does not fit your product, contact us and we will work out a plan
with you.Sender registry
Sender registry
/api/v1/senders has no v2 equivalent. If you used it only to attach display names,
pass sender_name on each message instead. Note that this changes “register once”
into “send every time”, so the name has to be available at write time.Memory space settings
Memory space settings
/api/v1/settings, covering timezone and llm_custom_setting, has no v2
equivalent. If you relied on either, contact us.Single-memory delete
Single-memory delete
v1 accepted
{"memory_id": "..."} to delete one memory. On v2 that is
POST /api/v2/memory/delete_by_ids with memory_type: "episode" and the ids (up to
50 per call) as get or search returned them. POST /api/v2/memory/delete clears
a whole scope instead: user_id, agent_id or session_id.Note the scope semantics: deleting by user_id alone removes that user’s episodes
and their profile. Adding session_id removes what that session produced and leaves
the profile in place.Async Python client
Async Python client
everos-cloud 1.x ships no async client. AsyncEverOS was removed. You can run the
synchronous client in a thread, or call /api/v2/memory/* with your own async HTTP
client.FAQ
Does my API key change?
Does my API key change?
No. The key you used for v1 authenticates v2.
What happened to my v1 data?
What happened to my v1 data?
Requests to
/api/v1/* stopped being served at 02:00 UTC on November 2. Your memories
were not lost: we migrated them into v2, under the same API key.My code still calls v1. What now?
My code still calls v1. What now?
Those calls fail with
403 VERSION_NOT_ALLOWED until you move them to v2. Follow
Migrating your code, and contact us if anything blocks you.Is there a tool that does this for me?
Is there a tool that does this for me?
Yes. See Option 1: run the migration tool. Start
with
--scan: it reports what would change without editing anything, and the report is
safe to send to us.
