Skip to content

feat(smartcomment): add optional execution graph tracing - #2629

Draft
consultantQ wants to merge 32 commits into
MemTensor:dev-v2.0.37from
consultantQ:feat/smartcomment-integration
Draft

consultantQ wants to merge 32 commits into
MemTensor:dev-v2.0.37from
consultantQ:feat/smartcomment-integration

Conversation

@consultantQ

Copy link
Copy Markdown

Description

Depends on #2623. Please merge #2623 first.

This PR adds an optional SmartComment plugin for tracing MemOS memory operations as execution graphs. The graphs help investigate missing memories and unexpected search results by showing the recorded extraction, storage, background processing, and retrieval steps.

The plugin lives in apps/memtrace-memos-integration and uses the hooks introduced in #2623. It is disabled by default and requires explicit activation through MEMOS_ENABLED_PLUGINS=smartcomment.

The integration includes:

  • Traces for memory extraction and writes, scheduler operations, and search stages such as filtering, deduplication, and reranking.
  • Asynchronous graph persistence with a per-user request index.
  • Optional links from final search results to their recorded memory creation history.
  • English and Chinese setup guides, visualization examples, and regression tests.

The plugin requires Python 3.12+ and smartcomment>=0.1.2.

The current diff includes the prerequisite hook changes from #2623. Review the SmartComment-only changes for the scope of this PR.

Related issue: None linked. The prerequisite PR is #2623.

Type of change

  • New feature
  • Documentation update

How has this been tested?

  • Full test suite (make test): 1155 passed, 9 skipped, 39 warnings in 138.01s.
  • Plugin and SmartComment tests (poetry run pytest tests/plugins apps/memtrace-memos-integration/tests -q): 169 passed in 1.50s.

The focused tests cover concurrent request isolation, search result preservation, persistence across restarts, history linking, write failures, and shutdown behavior.

  • Unit and integration tests passed; results recorded
  • Full test suite passed
  • Formatting and lint checks passed

Checklist

  • I have performed a self-review of my code.
  • I have commented code where the behavior needs explanation.
  • I have added regression tests for the integration.
  • I have added setup and usage documentation.
  • I have created a related documentation issue/PR in MemOS-Docs, if applicable.
  • I have linked a related issue, if applicable.
  • I have mentioned the intended reviewer.

Reviewer checklist

qzs and others added 30 commits September 4, 2026 23:00
Simplify internal tracing helpers while preserving graph identity, lineage, snapshots, lifecycle and hook boundaries. Refine integration-owned hook tests, preserve upstream tests, and document the changes and validation limits.
Clarify node, event, and link descriptions and group related handlers.
Remove unused TraceValue.name and legacy snapshot migration while
preserving current-format recovery and existing lineage rules.

Validation: plugin and Hook/Reader suite 82 passed; related MemOS
suite 266 passed, 1 skipped. Full make test was blocked by an Ollama
model-list network request. Scoped pre-commit checks passed.
…ce graph; Add memory type and memory cube node in search trace graph; Change search memory nodes into a search memory list; Convert each stage of search to a dynamic import.
Port the reviewed Hook-only tests from smartcomment-integration.
Keep upstream Search tests intact apart from required hook_context
assertions, and isolate new behavior tests with an opt-in fixture.
Cover Reader grouping/order and all five MemRead operation sites.

Validation on feat/add-more-plugin-hooks: 49 targeted tests passed;
related regression: 266 passed, 1 skipped. Individual test files,
Ruff, staged pre-commit, and diff checks passed. Full make test
stopped after 180 seconds at the existing Ollama network request.
- Normalize scheduler context to dictionaries and remove target parameter
- Include reader and deletion arguments in operation inputs
- Remove archive observations and redundant search context initialization
- Update hook documentation and regression tests
… add, removed the node for nodes filtered out during the search phase, and aligned some handler changes with the corresponding hook changes.
- Defer search event assembly and stage comparisons to the writer
- Reduce redundant snapshot copies and serialization
- Batch user index updates while checkpointing graphs per event
- Preserve write retries and flush guarantees with regression tests
Keep deferred Search assembly and persistence retries while isolating request state and graph identities. Recover empty reservation directories, validate numeric settings, align lineage defaults, and close the writer after application components.

Add focused regression coverage for concurrent requests, snapshot preservation, storage recovery and application shutdown. Verified with 133 related tests, scoped make format and pre-commit checks.
- Add tests for Add/Search handlers, lineage, recording, and serialization
- Cover queue limits and trace recovery after restart
- Update ignore rules to track integration tests
- Consolidate bilingual user guides and remove superseded documentation
- Introduce plugin features before explaining the MemTrace relationship
- Simplify wording and remove redundant guidance
…ization

docs(smartcomment): fix visualization examples
@Memtensor-AI Memtensor-AI added area:api 云服务 / FastAPI / OpenAPI / MCP area:memcube GeneralMemCube / cube 生命周期 / cube 配置 area:memory 记忆存储、检索、更新、召回逻辑 area:plugin OpenClaw & Hermes area:scheduler 调度模块 status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 labels Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:api 云服务 / FastAPI / OpenAPI / MCP area:memcube GeneralMemCube / cube 生命周期 / cube 配置 area:memory 记忆存储、检索、更新、召回逻辑 area:plugin OpenClaw & Hermes area:scheduler 调度模块 status:in-progress Someone or AI is working on it | 人工或 AI 正在处理

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants