Skip to content

fix(retrieval): defer candidate construction until after ranking - #2613

Merged
endxxxx merged 3 commits into
MemTensor:dev-v2.0.37from
yiwang-one:fix/defer-candidate-construction
Nov 18, 2026
Merged

endxxxx merged 3 commits into
MemTensor:dev-v2.0.37from
yiwang-one:fix/defer-candidate-construction

Conversation

@yiwang-one

Copy link
Copy Markdown

Description

What & Why

Vector and fulltext recall constructed a fully validated
TextualMemoryItem (pydantic validation of the full metadata, including
the embedding list and sources) for every recalled candidate — but
ranking and trimming then keep only the top-k. Validation for discarded
candidates is pure overhead on the retrieval path.

Approach

  • Recall branches now wrap candidate node dicts in a lightweight,
    validation-free view (DeferredTextualMemoryItem) exposing the
    passthrough attributes consumed before trimming (id, memory,
    metadata field lookups). Merge / rerank / dedup decisions read the
    same values as before, unchanged.
  • Survivors are materialized in _sort_and_trim (all memory-type
    branches) via the same from_dict validation as today — only for
    the top-k instead of for every candidate.
  • The full_recall=True exit materializes all results, since its
    callers treat them as fully constructed items.
  • retrieve_from_cube materializes eagerly: it mutates metadata
    in place and must keep returning real items.

Note on failure semantics: a malformed candidate payload previously
failed at recall time and took down the whole branch; it now fails at
materialization time (after trimming), and only if it survives ranking.
Valid data is unaffected; returned items pass through identical
validation either way.

Composes with #2600 (in-place relativity write): both touch the textual
loop of _sort_and_trim; resolution keeps both lines (materialize first,
then the in-place write).

No new dependencies.

中文说明

向量/全文召回此前对每条候选都做全量 pydantic 校验构造
TextualMemoryItem,而排序截断后仅保留 top-k,被淘汰候选的校验
构造属于纯开销。本 PR 改为:召回阶段返回零校验的轻量视图(直通
id/memory/metadata 字段,排序与去重决策读取的值与原先完全一致),
仅对截断后的幸存者通过与原先相同的 from_dict 校验构造正式对象;
full_recall 出口全量物化以保护既有调用方;retrieve_from_cube
因需就地改写 metadata 保持立即构造。输出与原实现逐字段等价,
无新增依赖。与 #2600(就地写 relativity)组合时保留两行即可。

Equivalence: unit tests compare view-backed and item-backed inputs
through rerank / dedup / sort-and-trim and deep-compare the resulting
to_dict() outputs; build() is asserted equivalent to eager
from_dict() on a battery of payload shapes.

Related Issue (Required): N/A — performance fix with no functional change

Type of change

  • Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

  • Unit Test
  • Test Script Or Steps (please provide)

11 new tests in tests/memories/textual/test_deferred_candidate.py
(view passthrough incl. missing-metadata edge, build equivalence,
rerank/dedup/sort-trim equivalence with mixed views and items, tool-branch
materialization, plugin zero-score skips construction, deepcopy safety).
One existing test updated to the new _vector_recall contract.

Reproduce (repo root):

PYTHONPATH=src python -m pytest tests/memories/textual/test_deferred_candidate.py -q
# => 11 passed

PYTHONPATH=src python -m pytest tests/memories/textual/ tests/api/ -q
# => 245 passed

ruff format --check src/memos/memories/textual/item.py src/memos/memories/textual/tree_text_memory/retrieve/recall.py src/memos/memories/textual/tree_text_memory/retrieve/searcher.py
# => already formatted

Checklist

  • I have performed a self-review of my own code | 我已自行检查了自己的代码
  • I have commented my code in hard-to-understand areas | 我已在难以理解的地方对代码进行了注释
  • I have added tests that prove my fix is effective or that my feature works | 我已添加测试以证明我的修复有效或功能正常
  • MemOS-Docs not applicable — internal performance fix, no public API change | 不适用——内部性能修复,无公共 API 变化
  • I have linked the issue to this PR (if applicable) | N/A
  • I have mentioned the person who will review this PR | 我已提及将审查此 PR 的人

Reviewer Checklist

  • Made sure Checks passed
  • Tests have been provided

Targeting main following the post-v2.0.36 release flow; happy to retarget if
a dedicated dev branch is introduced.

@Memtensor-AI Memtensor-AI added area:memory 记忆存储、检索、更新、召回逻辑 status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 labels Nov 10, 2026
@Memtensor-AI

Memtensor-AI commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

🤖 Open Code Review

Target: PR #2613
Task: fe723a60bdda0c53
Base: main
Head: fix/defer-candidate-construction
Head SHA: 70d80aa25834d97eb564aeff7f03ffed17cdf52d

🔍 OpenCodeReview found 2 issue(s) in this PR.


1. src/memos/memories/textual/tree_text_memory/retrieve/recall.py (L524)

Renaming _memory_item_from_vector_hit to _node_from_vector_hit leaves an existing caller broken: tests/graph_dbs/test_search_return_fields.py:327 still calls GraphMemoryRetriever._memory_item_from_vector_hit(hits[0]) and asserts memory.metadata.user_id on the returned object. After this change that test raises AttributeError, and even after renaming the call it would still fail because the method now returns a dict, not a TextualMemoryItem. Please update that test (e.g. wrap the returned dict with TextualMemoryItem.from_dict(...) before asserting on metadata), or keep a thin compatibility wrapper if other out-of-tree users rely on the old name.


2. src/memos/memories/textual/tree_text_memory/retrieve/searcher.py (L1116)

Searcher now depends on the private GraphMemoryRetriever._vector_recall_nodes instead of the previous public retrieve_from_mixed entry point. This couples two modules through an underscore-prefixed API and silently bypasses any future normalization/dedup logic added to retrieve_from_mixed (which is now unused in production code, only exercised by tests). Consider exposing a public node-level method on GraphMemoryRetriever (e.g. vector_recall_nodes) and calling that here.

Generated by cloud-assistant via Open Code Review.

@Memtensor-AI

Copy link
Copy Markdown
Collaborator

✅ Automated Test Results: PASSED

Required tests passed (17/17 executed, 0 skipped). Duration: 17s

Branch: fix/defer-candidate-construction

Tested source: 1dbd799a642cf78f14ca5903b993ae378dbaf934
Tested base: 3a16e5fe3048a209f722806f4123fa2e533588fd
Tested commit: 1dbd799a642cf78f14ca5903b993ae378dbaf934
These results apply only to this immutable source/base snapshot.

@Memtensor-AI Memtensor-AI added status:ready Ready for implementation; waiting for assignee or AI dispatch | 可进入实现,等待认领或派发 and removed status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 labels Nov 10, 2026
Recall previously constructed a fully validated TextualMemoryItem for
every recalled candidate, including the ones later discarded by ranking
and trimming. Vector and fulltext recall now wrap candidate node dicts
in a validation-free view (DeferredTextualMemoryItem), and real items
are built only for survivors, via the same from_dict validation as
before.

- The view exposes passthrough attributes (id, memory, metadata field
  lookups), so merge / rerank / dedup decisions are unchanged.
- _sort_and_trim materializes survivors in every branch loop; the
  full_recall exit materializes everything for callers that treat
  results as fully constructed items.
- retrieve_from_cube materializes eagerly: it mutates metadata in
  place and must keep returning real items.
@yiwang-one
yiwang-one force-pushed the fix/defer-candidate-construction branch from 1dbd799 to 1ee1727 Compare November 14, 2026 07:32
@Memtensor-AI Memtensor-AI added status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 status:ready Ready for implementation; waiting for assignee or AI dispatch | 可进入实现,等待认领或派发 and removed status:ready Ready for implementation; waiting for assignee or AI dispatch | 可进入实现,等待认领或派发 status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 labels Nov 14, 2026
@Memtensor-AI Memtensor-AI added status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 and removed status:ready Ready for implementation; waiting for assignee or AI dispatch | 可进入实现,等待认领或派发 labels Nov 18, 2026
@Memtensor-AI Memtensor-AI added the area:database graph_db + vector_db | 图数据库与向量数据库 label Nov 18, 2026
@endxxxx
endxxxx changed the base branch from main to dev-v2.0.37 November 18, 2026 07:05
@endxxxx
endxxxx merged commit 97b3930 into MemTensor:dev-v2.0.37 Nov 18, 2026
12 of 16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:database graph_db + vector_db | 图数据库与向量数据库 area:memory 记忆存储、检索、更新、召回逻辑 status:in-progress Someone or AI is working on it | 人工或 AI 正在处理

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants