Memory mode, evolve and the nightly schedule v1
Status: Core + CLI implemented (PR B of the SDK-surface batch). The App controls are built separately against this contract.
All routes need the Runtime bearer token. Unknown query parameters and body
fields answer 422 {"detail": "request_validation_failed"}, like every
memory route. user_id is optional (default local) and must match
^[A-Za-z0-9._-]{1,64}$. The App never sends it.
1. What the modes are
| Mode | SDK client | What happens to a conversation | What search reads |
|---|---|---|---|
lite |
mode="lite" |
Stored as one raw turn with one embedding. No model call; no generation model needs to be configured. | Raw turns only (the SDK forces L1_RAW). |
pro (default) |
mode="pro" |
Stored as raw, then a model extracts memories (System 1). The raw becomes SHADOW once extraction succeeds. | Extracted memories (facts, profile, intentions). |
ultra |
mode="ultra" |
Same as pro, and new facts are also projected into the knowledge graph. Every night, evolve runs System 2 for every user. | Same as pro, plus the graph-backed lanes below. |
The product difference between pro and ultra is the nightly evolve. MemHub ultra
uses SDK mode="ultra" because client.evolve refuses any other mode. Compared
with pro, SDK ultra (hy-memory 2.0.9) also turns on the following, so the owner
can judge their cost:
- The graph store. Kuzu is always opened in ultra. Client init fails if the
graph cannot open, so
PUT ultraanswers409 graph_store_unavailablewhenkuzuis missing. In pro it opens only whenMEMORY_ENABLE_GRAPHis set, and MemHub does not set it. Writes project new L2 facts into the graph. - The schema lane (L6_SCHEMA). The search's schema channel runs only when
a graph store exists, so in MemHub only in ultra. It returns the schemas that
evolve wrote (
schema_limit,schema_min_score). - Graph-aware ranking on the normal lane. With a graph store, search adds
graph-entity (MENTIONS) boosts when the query names known entities and no
source filter is set. The heavier graph stages need the graph and their
own env flag, and every flag defaults off, so none of them run in MemHub:
graph rerank and episode expansion (
MEMORY_GRAPH_RERANK_ENABLED), topic graph entry, same-series bundle, hierarchy bundle. - The profile.
get_user_profileappends the balanced catalog and the specific supplement from the graph, when the SDK's balanced-catalog flag is on.
ONE_MEMORY_GRAPH_STORE (development only) still forces ultra whatever the
setting says. Any value other than empty or none does this. The API reports
it as forced_by_env: true, with configured_mode showing the saved choice.
Raw is never deleted. In every mode MemHub keeps every raw turn the SDK stored, and the SDK never deletes raw itself. There is no retention window.
2. Switching mode: what changes and what does not
The SDK migrates nothing when the mode changes. MemHub applies these rules, and they are the owner's:
- The mode is read when a queued job runs, not when it was queued.
- A job that already completed, in any mode, stays completed. It is never reclaimed or reprocessed.
- Jobs still waiting (pending, assembling, waiting) and new input run in the new mode.
- A batch in flight finishes in the mode it started in. Its SDK client is retired only when its last use ends (the #218 use count). The next claim uses the new mode.
- Search follows the new mode at once. The read client is rebuilt on the next request (the active-profile read handle is keyed by profile and mode); the client it replaces closes once no request still uses it.
- lite → pro/ultra:
- what lite stored stays raw and is not extracted;
- lite's raw-only search stops at once;
- nothing is re-ingested or backfilled.
- pro/ultra → lite: memories made by the higher mode stay on disk, but lite search does not serve them. Nothing is deleted.
- ultra → pro/lite: the nightly evolve stops.
- → ultra:
- every known user's existing facts are added to the graph once
(
build_memory_graph(user_id, limit=10000, clear_first=False)); - this runs in the background, one user at a time, never beside that user's write;
- progress is reported in
graph_build.
- every known user's existing facts are added to the graph once
(
- Vector collection names never depend on the mode. The mode is a separate client parameter, not part of the embedding-space identity.
3. GET /api/v1/settings/memory-mode
No parameters. 200 response:
{
"mode": "pro",
"configured_mode": "pro",
"forced_by_env": false,
"modes": ["lite", "pro", "ultra"],
"graph_build": {
"state": "idle",
"started_at": null,
"finished_at": null,
"users": {}
}
}
modeis what SDK clients are built with now;configured_modeis the saved setting.graph_build.stateisidle | running | succeeded | failed. Each entry ingraph_build.users[<user_id>]is{state: pending|running|succeeded|failed, memories_scanned, nodes, error_code}.
4. PUT /api/v1/settings/memory-mode
Body: {"mode": "lite" | "pro" | "ultra"}. 200 response: the GET shape,
plus these fields:
{
"previous_mode": "pro",
"effects": ["existing_memories_added_to_graph"]
}
effects is empty when the effective mode did not change. That happens when
the mode was already set, or when ONE_MEMORY_GRAPH_STORE forces ultra; the
saved setting still changes in that case. Otherwise effects lists these, in
this order:
| Effect | When | Meaning |
|---|---|---|
earlier_raw_not_extracted |
from lite | What lite stored stays raw; it is not extracted. |
lite_search_stops |
from lite | lite's raw-only search ends now; search reads memories. |
higher_mode_memories_hidden |
to a lower mode | Memories of the higher mode stay stored but are not shown. |
evolve_stopped |
from ultra | The nightly evolve stops. |
existing_memories_added_to_graph |
to ultra | The one-time graph backfill started (see graph_build). |
graph_backfill_already_running |
to ultra | A backfill from an earlier switch is still running; no second one started. |
Errors:
409 {"detail": "graph_store_unavailable"}:ultrawas asked for, but the graph store package is not installed. Nothing changed.422 request_validation_failed: an unknown mode or an extra field.
Show the planned effects before calling PUT. Clients can compute them with the
table above: the CLI (memhub settings mode <m> without --yes) and Core
(memory_mode_effects) use the same rule.
5. Evolve
POST /api/v2/evolve → 202
Body (every field optional):
{"user_id": "local", "agent_id": "all-apps", "max_batches": 3}
agent_idis 1..128 characters. The default isall-apps, the agent MemHub writes every memory under.max_batchesis 1..1000. The default is the SDK's own.
The response is the run receipt below, with state: "running". The run goes
on in the background.
- One run per user. Asking while that user's run is going answers the same
receipt, again
202. - Never beside that user's writes. The run waits for the user's write in flight. While it runs, that user's queued jobs wait: they are returned to pending before any SDK call. Other users are not held.
- Loops while the SDK answers
should_continue: true, up to 20 rounds. A run stopped by that cap hascapped: true; start it again to continue.
Errors:
409 {"detail": "memory_mode_not_ultra"}: the effective mode is not ultra.422: a malformeduser_id,max_batchesoutside its range, or an extra field.
Run receipt
{
"run_id": "uuid",
"user_id": "local",
"agent_id": "all-apps",
"max_batches": null,
"trigger": "manual",
"state": "succeeded",
"started_at": "2026-11-01T03:00:00Z",
"finished_at": "2026-11-01T03:00:42Z",
"rounds": 2,
"tasks_processed": 5,
"batch_failures": 0,
"cycle_status": "complete",
"should_continue": false,
"continuation_reason": null,
"remaining_clusters": 0,
"remaining_actionable_clusters": 0,
"remaining_fresh_facts": 0,
"capped": false,
"elapsed_ms": 41873.2,
"error_code": null,
"failure_kind": null,
"request_id": "sdk-request-id",
"results": {},
"cross_domain_sweeper": {}
}
triggerismanualorscheduled.stateisrunning,succeededorfailed.cycle_statusis the SDK'spartialorcomplete.error_codeandfailure_kindare stable codes on failure. Examples:memory_evolve_cancelled(the Runtime stopped mid-run),hy_memory_evolve_rejected(the SDK answeredsuccess: falsewithout a code), or the SDK's ownerror_code. Provider messages never appear.resultsandcross_domain_sweeperare the last round's SDK bodies. They live in memory only and are never written to disk or diagnostics.
GET /api/v2/evolve/{run_id}?user_id= → receipt
Returns 404 {"detail": "evolve_run_not_found"} in two cases:
- the run belongs to another user (answered exactly like a missing run);
- the Runtime restarted since the run. Receipts live in memory, and the last 64 are kept.
GET /api/v2/evolve?user_id= → overview
{
"mode": "ultra",
"schedule": {"enabled": true, "time": "03:00"},
"users": {
"local": {
"last_run_at": "2026-11-01T03:00:00Z",
"last_result": {"state": "succeeded", "rounds": 2, "...": "receipt without results"},
"last_error": null
}
},
"running": []
}
- Without
user_idthe overview covers every user; with it, that one user. userssurvives restarts. It is kept in<data_dir>/evolve-state.json, counts and codes only.
6. Nightly schedule
GET /api/v1/settings/evolve-schedule
Returns {"enabled": true, "time": "03:00"}. time is HH:MM, 24-hour, in
the machine's local time.
PUT /api/v1/settings/evolve-schedule
Body: {"enabled"?: bool, "time"?: "HH:MM"}. An absent field keeps its
value. The response is the saved schedule. A bad time answers 422.
How the schedule runs:
It runs only in ultra.
It checks every 5 minutes. A user's run is due when either holds:
- today's slot has passed, and the user's last run is older than that slot;
- the user's last run is more than 24 hours old.
The second rule is how a machine that slept through 03:00 catches up when it wakes.
A user who never ran is measured from the first time the schedule ran in ultra, not from the epoch. So switching to ultra at noon does not evolve everyone at once; their first run is at the next slot.
Users run one after another.
The schedule runs every user that has memories. The SDK cannot list users, so Core takes them from its own records:
local;- every user holding a source grant (a Hermes profile);
- every user whose turns or notes passed the write queue.
A user is kept when memory_stats reports any memory or fact for them.
7. Status fields (R10)
GET /api/v1/memory-processing has a new optional field, pipeline:
{
"pipeline": {
"mode": "ultra",
"configured_mode": "ultra",
"forced_by_env": false,
"evolve": {"...": "the overview of section 5"},
"last_evolve_at": "2026-11-01T03:00:00Z",
"graph_build": {"...": "as in section 3"},
"features": {}
}
}
features lists the SDK features whose value differs from the default (empty
while every feature is at its default); see memory-features-v1.md.
memhub status --json adds a top-level projection of it:
{
"pipeline": {
"mode": "ultra",
"configured_mode": "ultra",
"forced_by_env": false,
"last_evolve_at": "...",
"evolve_schedule": {"enabled": true, "time": "03:00"},
"evolve_running": 0,
"evolve_users": {
"local": {"last_run_at": "...", "last_error": null, "state": "succeeded"}
},
"graph_build": "succeeded",
"features": {}
}
}
memhub progress --json carries the same pipeline. Both are null against
an older Core.
8. CLI
memhub settings mode # show the current mode
memhub settings mode lite # print the plan, change nothing
memhub settings mode lite --yes # switch
memhub evolve [--user-id <id>] [--agent-id <id>] [--max-batches <n>] [--wait] [--json]
memhub settings features [set <name>=<true|false> ... [--yes] | reset [<name> ...]]
The SDK's optional retrieval and extraction features (graph rerank, episode
recall, the episode write side, …) are a second global setting beside the
mode. A change rebuilds the SDK handles the same way. Contract:
memory-features-v1.md.
9. Copy the UI can reuse
| Key | zh-CN | en | es |
|---|---|---|---|
| title | 记忆模式 | Memory mode | Modo de memoria |
| lite | lite:不调用模型,保留全部原始对话,只在原始对话里检索。 | lite: no model calls. Every original conversation is kept, and search reads only those conversations. | lite: sin llamadas al modelo. Se conservan todas las conversaciones originales y la búsqueda solo las consulta a ellas. |
| pro | pro:由模型从对话中提取记忆(System 1)。 | pro: a model extracts memories from your conversations (System 1). | pro: un modelo extrae memorias de tus conversaciones (System 1). |
| ultra | ultra:在 pro 之上每晚自动整合记忆(System 2,evolve),并使用知识图谱。 | ultra: pro plus nightly memory consolidation (System 2, evolve), using a knowledge graph. | ultra: pro más una consolidación nocturna de las memorias (System 2, evolve), con un grafo de conocimiento. |
| confirm | 切换到 {mode} 前请确认: | Before switching to {mode}, please confirm: | Antes de cambiar a {mode}, confirma lo siguiente: |
| earlier_raw_not_extracted | lite 下已处理完的对话不会再被提取;只有尚未处理的和之后的新对话会由模型整理成记忆。 | Conversations already handled in lite are not extracted again; only conversations still waiting, and new ones, become memories. | Las conversaciones ya procesadas en lite no se vuelven a extraer; solo las pendientes y las nuevas se convierten en memorias. |
| lite_search_stops | 只在原始对话里的检索会立即停止,改为检索记忆。 | Search over original conversations stops now; search reads memories instead. | La búsqueda en las conversaciones originales se detiene ahora; se buscará en las memorias. |
| higher_mode_memories_hidden | 更高模式生成的记忆仍然保存,但在这个模式下不会显示。 | Memories created by a higher mode stay stored but are not shown in this mode. | Las memorias creadas por un modo superior se conservan, pero no se muestran en este modo. |
| evolve_stopped | 每晚的自动整合(System 2)会停止。 | Nightly consolidation (System 2) stops. | La consolidación nocturna (System 2) se detiene. |
| existing_memories_added_to_graph | 已有记忆会在后台加入知识图谱。 | Your existing memories are added to the knowledge graph in the background. | Tus memorias actuales se añaden al grafo de conocimiento en segundo plano. |
| graph_backfill_already_running | 知识图谱正在补建中。 | The knowledge graph is still being built. | El grafo de conocimiento todavía se está construyendo. |
| raw_kept | 原始对话全部保留,任何模式都不删除。 | Every original conversation is kept, in every mode. | Se conservan todas las conversaciones originales, en cualquier modo. |
| graph_build_running | 正在把已有记忆加入知识图谱… | Adding existing memories to the knowledge graph… | Añadiendo las memorias actuales al grafo de conocimiento… |
| forced_by_env | 开发环境变量 ONE_MEMORY_GRAPH_STORE 正在强制使用 ultra。 | The development variable ONE_MEMORY_GRAPH_STORE is forcing ultra. | La variable de desarrollo ONE_MEMORY_GRAPH_STORE está forzando ultra. |
| graph_store_unavailable | 这个安装缺少知识图谱组件,无法切换到 ultra。 | This installation lacks the knowledge-graph component, so it cannot switch to ultra. | A esta instalación le falta el componente del grafo de conocimiento; no puede cambiar a ultra. |
| schedule | 每天 {time} 自动整合 | Consolidates daily at {time} | Consolida cada día a las {time} |
| last_evolve | 上次整合:{time} | Last consolidation: {time} | Última consolidación: {time} |
| never_evolved | 尚未整合 | Not consolidated yet | Aún no consolidado |
| evolve_not_ultra | 记忆整合只在 ultra 模式下可用。 | Consolidation is available in ultra mode only. | La consolidación solo está disponible en el modo ultra. |