SDK retrieval and extraction features v1
Status: Core + CLI implemented. Stacks on the memory-mode contract
(memory-mode-evolve-v1.md). The App keeps today's behaviour and has no
control for this yet; the copy in section 9 is there if it adds one.
MemHub hard-codes none of the SDK's optional features. A person can turn the ones below on or off through the CLI or the API. Nobody has to: an unset feature keeps the SDK default, and with nothing set the SDK config is byte for byte what MemHub built before this setting existed.
All routes need the Runtime bearer token. Unknown query parameters and body
fields answer 422 {"detail": "request_validation_failed"}, like every other
settings route. The setting is global, like the memory mode: it applies to
every user's SDK client and takes no user_id.
1. Inventory
These are the hy-memory flags (hy_memory/config.py and the modules that read
the environment directly) that change retrieval or extraction quality. Cost:
"none" means no extra call; "query" means one more local store query per
search; "LLM" means extra generation-model calls; "tokens" means a longer
prompt and no extra call.
Exposed
| Name | SDK field (env) | Default | Mode | Cost |
|---|---|---|---|---|
graph_rerank |
graph_store.graph_rerank_enabled (MEMORY_GRAPH_RERANK_ENABLED) |
off | ultra (graph store) | query (graph edges) |
same_series_timeline |
recall.same_series_timeline_enabled (MEMORY_SAME_SERIES_TIMELINE_ENABLED) |
off | ultra + graph_rerank |
none |
episode_recall |
recall.episode_recall_enabled (MEMORY_EPISODE_RECALL_ENABLED) |
off | pro or ultra; no graph | query (episode members) |
session_episodes |
recall.session_episode_enabled (MEMORY_SESSION_EPISODE_ENABLED) |
off | pro or ultra | none |
episode_summary |
recall.episode_summary_enabled (MEMORY_EPISODE_SUMMARY_ENABLED) |
off | pro or ultra | LLM: one call per closed episode of 3+ memories |
intention |
llm.enable_intention (MEMORY_ENABLE_INTENTION) |
on | pro or ultra | none (off shortens the prompt) |
few_shot |
llm.few_shot_enabled (MEMORY_FEW_SHOT_ENABLED) |
off | pro or ultra | tokens (extraction and reconcile) |
- Graph rerank (usage A). It propagates support over the graph edges
inside the recall pool (
reader_base._apply_graph_rerank). It needs a graph store, which MemHub opens only in ultra. In pro and lite it is reportedactive: false, reason: "requires_ultra". - Episode recall (usage B). It adds memories from the same episode as a
hit and scores them on three channels: tag-keyword overlap, content overlap
and temporal affinity. It needs no graph, so it works in pro (issue #121).
It helps only memories that carry an
episode_id.- Memories that System 1 adds through reconcile get an idle-gap
episode_idwhenever the SDK cache is available, which MemHub's SQLite cache is. A new episode starts after 30 minutes idle or 50 memories. session_episodesreplaces that with one stable episode per conversation.- Memories stored before the change keep the id they had.
- Raw turns from lite, and notes written before episodes existed, carry none.
- Memories that System 1 adds through reconcile get an idle-gap
- Episode write side.
session_episodesandepisode_summaryare the write half of episodes, and both are off by default. Usage B only helps once episodes are being written. The SDK's session narrative (L3,finalize_session) is a separate feature and is not exposed (section 2). intentionis the only feature that is on by default. Turning it off stops L7 intention memories from being extracted.
Left out, and why
| Flag(s) | Why it is not exposed |
|---|---|
recall.entity_store_enabled (MEMORY_ENTITY_STORE_ENABLED) |
Entity extraction needs spaCy and en_core_web_sm, which MemHub does not ship, so it would silently do nothing. It also writes a new {collection}_entities collection, and MemHub's collection identity has to stay fixed. |
llm.enable_query_rewrite (MEMORY_ENABLE_QUERY_REWRITE) |
It only affects default-mode searches that pass queries=[...], and MemHub never sends that. Per-request rewrite already exists as search_mode: "agentic" (#252). |
session_episode_context_enabled, dynamic_episode_enabled, series_episode_enabled, episode_capsule_context_enabled, episode_member_expansion_enabled |
They read or write the L3 session narrative that finalize_session builds, and MemHub never calls it. When dynamic or series finalize fails, the SDK fails the write with a non-retryable 409 partial result, which would leave MemHub jobs unknown. |
local_rerank_enabled (+ model / device) |
It downloads a cross-encoder model on first use. That is a network fetch MemHub's packaged, offline runtime and zero-collection rules do not allow. |
strength_enabled, access_tracking_enabled |
They write access counts back to memory rows on every search: a read that mutates. Internal. |
structure_metadata_enabled, retrieval_clauses_*, supplemental_propositions_enabled, hierarchy_bundle_*, multi_seed_bundle_*, tag_index_nominee_*, dynamic_entity_tag_embed_enabled |
Experimental retrieval lanes, each with many tuning parameters. The SDK marks them as still under gray validation, and some depend on System 2 output. Internal tuning, not a person's choice. |
graph_store.memory_graph_write, path_enabled (default on) |
Turning them off breaks graph rerank and evolve. Dangerous. |
hierarchy_topic_write, temporal_spine, topic_summary_enabled |
Experimental graph write lanes ("stage 5"); topic summary also costs LLM calls. Not validated for users. |
Schema lane and catalog / supplement (MEMORY_EVOLING_SCHEMA_DEDUP_ENABLED, MEMORY_EVOLING_SCHEMA_COMPACTION_ENABLED, MEMORY_EVOLING_BALANCED_CATALOG_ENABLED, MEMORY_EVOLING_SPECIFIC_SUPPLEMENT_ENABLED, MEMORY_USER_PROFILE_*, MEMORY_HYBRID_V2_*_L0_ENABLED) |
The SDK reads them from os.environ, not from MemoryConfig. Some are read once at import (system2_tools), others on each call for the whole process. They cannot be scoped to one client, and setting them in Core's environment would need a restart and would leak into every client. Section 3. |
The hybrid reader's env knobs (MEMORY_HYBRID_V2_*, MEMORY_TOPIC_*_ENABLED, MEMORY_*_BUNDLE_ENABLED, MEMORY_RERANK_*) |
Same reason: read from the process environment on each search. |
RECONCILE_ENABLED, SWEEPER_ENABLED, MEMORY_CROSS_DOMAIN_ENABLE |
Read at import time. Turning reconcile off stores every extraction without dedup. Dangerous. |
coding.chain_block_enabled, coding.verbatim_fallback_enabled |
Coding-scene options. The verbatim fallback stores assistant and tool traces as facts. |
MEMORY_ENABLE_GRAPH (graph in pro) |
That is the memory mode's job (settings mode). |
MEMORY_LOG_LLM_CONTENT, pipeline log, trace, memory operations, metrics / telemetry |
Diagnostics. MemHub controls them elsewhere (diagnostic-logging.md). |
2. The setting
config.json gains an optional memory_features object next to
memory_mode. It is written only once a person sets a feature, and then it
holds only the features they set:
{"memory_mode": "pro", "memory_features": {"episode_recall": true, "session_episodes": true}}
The values are strict booleans and unknown keys are refused, so a hand-edited
file with an unknown feature fails to load (config_invalid), like any other
malformed setting.
3. How a setting reaches the SDK
- Every exposed feature is a
MemoryConfigfield that the SDK reads from the config object when it is called. None of them is read fromos.environat call time. hy_sdk_runtime.build_sdk_config(..., features=...)sets those fields on each client's config afterMemoryConfig.from_dict. The result is deterministic per client.- The SDK's own env vars (the second column of the table) still decide the default of a feature nobody set. That is exactly what happened before the setting existed. A setting always wins over the env var.
- MemHub writes no env var. The flags the SDK reads straight from the environment are the ones left out above.
- Each client's features are fixed when it is built, like its mode. Both the
write handles (
SdkWriteCoordinator) and the read handle (ActiveProfileReadHandle) are keyed by (profile, revision, mode, features). - A change runs
retire_stale_handles, the #218 use count. An idle write handle closes at once, and a write in flight finishes with the features it started with. The next read builds a client with the new key. The old read client closes once no request still uses it. - Nothing stored is migrated. A feature never touches
vector_store, the embedder or any store path, so the collection identity is the same with any features (tested).
4. GET /api/v1/settings/memory-features
{
"mode": "pro",
"features": [
{
"name": "graph_rerank",
"enabled": true,
"configured": true,
"default": false,
"active": false,
"reason": "requires_ultra",
"side": "read",
"requires_mode": "ultra",
"requires_feature": null,
"cost": "extra_query",
"sdk_field": "graph_store.graph_rerank_enabled",
"env": "MEMORY_GRAPH_RERANK_ENABLED",
"description": "Usage A: propagate support over knowledge-graph edges ..."
}
],
"non_default": {"graph_rerank": true}
}
enabledis what clients are built with:configuredif set, elsedefault.configuredis null when unset.defaultis the SDK default: its code default, or its own env var when set.activeis false with areasonwhen the feature does nothing right now. The reason is one ofdisabled,requires_pro(lite),requires_ultra, orrequires_graph_rerank(forsame_series_timeline).costis one ofnone,extra_query,llm_call,prompt_tokens.featuresalways lists every feature, in the table's order.
5. PUT /api/v1/settings/memory-features
The body has any of the feature names as keys:
trueorfalsesets that feature.nullresets it to the default.- An absent key is left as it is.
- Anything else answers
422, including a non-boolean,"true",1, or an unknown name.
{"graph_rerank": true, "episode_recall": true, "few_shot": null}
The answer is the state of section 4, plus changed: the features whose
effective value changed, in the table's order. When the set of configured
features changes, the SDK clients are rebuilt (section 3). That includes a
reset to a value equal to the default, after which the client carries no
override at all.
6. Status
pipeline in GET /api/v1/memory-processing (memory-mode contract §7) gains
features, which lists the features whose effective value differs from the
default. It is {} while every feature is at its default:
{"pipeline": {"mode": "pro", "...": "...", "features": {"episode_recall": true, "intention": false}}}
memhub status --json and memhub progress --json carry it as
pipeline.features. The text status appends ;SDK 功能:episode_recall=开、…
to the memory-mode line.
7. CLI
memhub settings features # list them
memhub settings features set episode_recall=true session_episodes=true # plan only
memhub settings features set episode_recall=true session_episodes=true --yes
memhub settings features reset few_shot # back to the default
memhub settings features reset # every set feature
set prints its plan and needs --yes, like settings mode, because some
features spend model calls. reset only returns features to their defaults,
so it applies at once. Unknown names or values other than true / false are
a usage error (exit 2) before the Runtime is asked.
8. Rules kept
- Global management, as for the mode: no
user_id; reads stay scoped per user as before. - Strict parameters: unknown body fields and query parameters answer 422.
- The mode semantics of #253 are unchanged. A feature needing a higher mode is stored and reported inactive; it is not refused.
9. Copy the UI can reuse
| Key | zh-CN | en | es |
|---|---|---|---|
| title | 高级检索与提取 | Advanced retrieval and extraction | Recuperación y extracción avanzadas |
| graph_rerank | 图谱重排:沿知识图谱的关联提升相关记忆的排名(仅 ultra)。 | Graph rerank: ranks memories higher when the knowledge graph links them to strong matches (ultra only). | Reordenación por grafo: sube en la lista las memorias que el grafo de conocimiento relaciona con buenas coincidencias (solo ultra). |
| same_series_timeline | 同系列时间线:同一系列的记忆按时间放在一起(需图谱重排)。 | Same-series timeline: keeps memories of one series together in time order (needs graph rerank). | Línea temporal de la serie: mantiene juntas y en orden temporal las memorias de una misma serie (requiere la reordenación por grafo). |
| episode_recall | 片段召回:补入与命中记忆同一片段的记忆,并按标签、内容和时间打分。 | Episode recall: adds memories from the same episode as a match and scores them by tags, content and time. | Recuperación por episodio: añade memorias del mismo episodio que una coincidencia y las puntúa por etiquetas, contenido y tiempo. |
| session_episodes | 片段写入:同一会话中提取的记忆归入同一片段。 | Episodes per conversation: memories extracted from one conversation share one episode. | Episodios por conversación: las memorias extraídas de una conversación comparten un episodio. |
| episode_summary | 片段摘要:片段结束时总结一次(每个片段一次模型调用)。 | Episode summaries: each finished episode is summarized once (one model call per episode). | Resúmenes de episodio: cada episodio terminado se resume una vez (una llamada al modelo por episodio). |
| intention | 意图提取:随事实一起记住你提到的计划和意图。 | Intentions: remembers the plans and intentions you mention, along with facts. | Intenciones: recuerda los planes e intenciones que mencionas, junto con los hechos. |
| few_shot | 提取示例:在提取提示中加入示例,可帮助较弱的模型(输入更长)。 | Extraction examples: adds examples to the extraction prompt, which can help a weaker model (longer input). | Ejemplos de extracción: añade ejemplos a la instrucción de extracción, lo que puede ayudar a un modelo más débil (entrada más larga). |
| default | 默认 | Default | Predeterminado |
| requires_ultra | 当前模式下不生效,需要 ultra。 | Has no effect in this mode; needs ultra. | No tiene efecto en este modo; requiere ultra. |
| requires_pro | lite 模式下不生效。 | Has no effect in lite. | No tiene efecto en lite. |
| requires_graph_rerank | 需要先开启图谱重排。 | Turn on graph rerank first. | Activa primero la reordenación por grafo. |
| episodes_hint | 片段召回只对带片段的记忆有用;开启片段写入后,新提取的记忆才会按会话归入片段。 | Episode recall only helps memories that belong to an episode; with episodes per conversation on, new memories are grouped by conversation. | La recuperación por episodio solo ayuda a las memorias que pertenecen a un episodio; con los episodios por conversación activados, las memorias nuevas se agrupan por conversación. |
| cost_llm | 会增加模型调用 | Uses extra model calls | Usa llamadas adicionales al modelo |
| applied | 正在进行的写入按原设置完成,之后的写入和检索使用新设置。 | A write in progress finishes with the old settings; later writes and searches use the new ones. | Una escritura en curso termina con la configuración anterior; las siguientes escrituras y búsquedas usan la nueva. |