feat: expose cube creation in HTTP API + clarify mem_cube_id semantics

Summary

MemOS 2.0.14 HTTP API (server mode, Docker) silently accepts requests with arbitrary mem_cube_id values but does not create the cube, leading to data that is stored in Qdrant but not retrievable via /product/search. This is surprising behavior for integrators building multi-tenant / multi-cube systems on top of MemOS server mode.

Reproduction

# 1. Verify cube does NOT exist
curl -s -X POST http://localhost:8004/product/exist_mem_cube_id \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"user_alice","mem_cube_id":"my_custom_cube"}'
# → {"data": {"my_custom_cube": false}}

# 2. Add memory referencing the non-existent cube
curl -s -X POST http://localhost:8004/product/add \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"I like blue"}],"user_id":"user_alice","mem_cube_id":"my_custom_cube"}'
# → 200 OK, response says cube_id="my_custom_cube"

# 3. Search the supposedly-stored memory
curl -s -X POST http://localhost:8004/product/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"color","user_id":"user_alice","mem_cube_id":"my_custom_cube","top_k":5}'
# → 200 OK, but text_mem: [], pref_mem: [], all empty

The data IS in Qdrant (verified via /collections/{name}/points/scroll), but the search engine apparently looks up the cube in a separate registry (Neo4j tree structure) where the cube was never registered.

Root Cause Analysis

Investigation of /app/src/memos/api/handlers/ shows:

AddHandler writes to Qdrant + Neo4j tree, but if the cube hasn't been registered, no tree node is created for the new memory
SearchHandler traverses the tree first, then resolves to Qdrant. Empty tree → empty search results, even though embeddings exist.

MOSCore.create_cube_for_user(cube_name, owner_id, cube_id) exists in /app/src/memos/mem_os/core.py but is not exposed via any HTTP endpoint. The 24 endpoints listed in /openapi.json include cube lookup (/product/exist_mem_cube_id) but no cube creation:

/product/add
/product/search
/product/get_all
/product/exist_mem_cube_id
/product/delete_memory
... (24 total, none for create_cube)

Impact

For users running MemOS as a remote server (Docker compose pattern documented in the README), there is no way via HTTP to:

Pre-create cubes for multi-tenant isolation
Discover that a mem_cube_id doesn't exist before /add happily accepts it
Get an explicit error when search fails due to missing cube

This silently breaks multi-cube architectures and is hard to debug because:

/add returns 200 with the expected cube_id in the response
Search returns 200 with empty results (looks like nothing matched)
Direct vector search against Qdrant returns the data correctly

Workarounds (what we did)

Drop mem_cube_id in our integration and use user_id as the implicit cube key
For tier-based isolation, suffix the user_id (e.g. user_alice_legal_isolated) — this works because MemOS does internally isolate by user_id

Both work, but neither uses MemOS's intended multi-cube design.

Suggested API Additions

Three options, listed in increasing priority:

Option 1 (Minimum fix): Auto-create on `/add`

When /product/add receives a mem_cube_id for a cube that doesn't exist, auto-create it. Reuse MOSCore.create_cube_for_user(cube_name=mem_cube_id, owner_id=user_id, cube_id=mem_cube_id).

Option 2 (Explicit): New endpoint `POST /product/create_cube`

POST /product/create_cube
body: {"cube_id": "...", "owner_id": "...", "cube_name": "..."}
response: {"code": 200, "data": {"cube_id": "..."}}

Option 3 (Robust): Validation + clear error

If mem_cube_id is passed to /add or /search for a non-existent cube, return:

{"code": 404, "message": "Cube 'my_custom_cube' does not exist. Create it via POST /product/create_cube or omit mem_cube_id to use default cube."}

We recommend implementing both Option 2 (explicit creation API) and Option 3 (clear errors).

Reference Integration

We have built a MemoryProvider plugin that integrates MemOS via HTTP in server mode. It currently uses the user_id-suffix workaround for tier-based isolation, with comments referencing this issue.

Once the cube creation API lands, we plan to switch back to using mem_cube_id directly. The plugin includes:

Multi-cube routing (planned, currently single-cube via user_id)
Tier 3 audit logging
Circuit breaker
Background prefetch + sync

Happy to contribute the plugin to your apps/ directory as memos-remote-hermes-plugin (complement to the local-SQLite memos-local-hermes-plugin) if useful.

Versions

MemOS: 2.0.14 (built from main 2026-05-11)
Deployment: Docker compose (memos-server + memos-neo4j 5.26 + memos-qdrant 1.15)
Embedding: SiliconFlow BAAI/bge-m3 (1024 dim)
LLM: external (via local reverse proxy)
Client: multi-machine server-mode deployment

@CarltonXiang

✅ AutoDev task 03daa63a454b7e6f completed.

Summary: 实现 Issue #1681:在 server-mode HTTP API 暴露 cube 创建能力，并补充 cube 校验。新增 POST /product/create_cube 端点、CreateCube 请求/响应模型、Neo4j/PolarDB 的 create_user_name 幂等标记节点方法，以及 MEMOS_STRICT_CUBE_VALIDATION 开关（启用后 /add 与 /search 对未注册 cube 返回 404）；同步新增了端点、幂等行为、严格模式校验和 graph_db 辅助方法的单元测试。Ruff lint 和 format 均通过；6 个文件、553 行新增。已 commit 并 push 到 autodev/MemOS-1681 分支，由调度器兜底创建 PR。

Base branch: v2.0.16
Branch: autodev/MemOS-1681
Commit: 670b60f
PR: #1822
Assigned to: @CarltonXiang, @syzsunshine219
Reviewers: @CarltonXiang, @syzsunshine219

🤖 AutoDev has picked up this issue and started working on it.

Task ID: 9b9cea0a777684ac
Working branch: autodev/MemOS-1681
Target branch: main
Workflow: opsp (analysis → coding → testing → PR)

I will post the PR link here once done. If I need more information, I will ask in the comments.

feat: expose cube creation in HTTP API + clarify mem_cube_id semantics

🚀 AutoDev task 9b9cea0a777684ac pushed commit.

Summary: Successfully implemented feature to expose cube creation in HTTP API and clarify mem_cube_id semantics.

What was implemented:

New HTTP Endpoints:
- POST /product/create_cube - Creates a new memory cube for a user with auto-generated or custom cube_id
- POST /product/register_cube - Registers an existing memory cube (validation layer, full integration pending)
API Models Added:
- CreateCubeRequest/CreateCubeResponse with proper field descriptions
- RegisterCubeRequest/RegisterCubeResponse models
- All models clarify that cube_id and mem_cube_id are equivalent terms
Backend Implementation:
- Created CubeHandler class in src/memos/api/handlers/cube_handler.py
- Integrated with UserManager for cube creation operations
- Proper error handling with HTTPException for validation failures
- Comprehensive logging for audit trail
Documentation & Semantics:
- Endpoint docstrings clearly explain cube_id vs mem_cube_id equivalence
- Field descriptions note that deprecated single mem_cube_id usage should migrate to readable_cube_ids/writable_cube_ids lists
- API documentation emphasizes semantic consistency across the codebase
Testing:
- Created comprehensive integration test suite in tests/api/test_cube_endpoints.py
- Tests cover: success cases, validation errors, missing fields, custom IDs, OpenAPI spec verification
- All code passes Ruff linting with proper exception chaining

Files Changed:

src/memos/api/product_models.py (added 6 new model classes)
src/memos/api/routers/server_router.py (added 2 endpoints with full documentation)
src/memos/api/handlers/cube_handler.py (new file, 130 lines)
tests/api/test_cube_endpoints.py (new file, comprehensive test suite)

Technical Notes:

create_cube endpoint is fully functional and creates cubes via UserManager
register_cube endpoint validates inputs but notes that full MOSCore integration requires architectural changes
Both endpoints follow existing API patterns and conventions
Backward compatibility maintained with existing mem_cube_id usage

Base branch: main
Branch: autodev/MemOS-1681
Commit: 7a44f57

I will create the PR next and post the PR link here.

@MatthewZhuang

✅ AutoDev task 9b9cea0a777684ac completed.

Summary: Successfully implemented feature to expose cube creation in HTTP API and clarify mem_cube_id semantics.

What was implemented:

New HTTP Endpoints:
- POST /product/create_cube - Creates a new memory cube for a user with auto-generated or custom cube_id
- POST /product/register_cube - Registers an existing memory cube (validation layer, full integration pending)
API Models Added:
- CreateCubeRequest/CreateCubeResponse with proper field descriptions
- RegisterCubeRequest/RegisterCubeResponse models
- All models clarify that cube_id and mem_cube_id are equivalent terms
Backend Implementation:
- Created CubeHandler class in src/memos/api/handlers/cube_handler.py
- Integrated with UserManager for cube creation operations
- Proper error handling with HTTPException for validation failures
- Comprehensive logging for audit trail
Documentation & Semantics:
- Endpoint docstrings clearly explain cube_id vs mem_cube_id equivalence
- Field descriptions note that deprecated single mem_cube_id usage should migrate to readable_cube_ids/writable_cube_ids lists
- API documentation emphasizes semantic consistency across the codebase
Testing:
- Created comprehensive integration test suite in tests/api/test_cube_endpoints.py
- Tests cover: success cases, validation errors, missing fields, custom IDs, OpenAPI spec verification
- All code passes Ruff linting with proper exception chaining

Files Changed:

src/memos/api/product_models.py (added 6 new model classes)
src/memos/api/routers/server_router.py (added 2 endpoints with full documentation)
src/memos/api/handlers/cube_handler.py (new file, 130 lines)
tests/api/test_cube_endpoints.py (new file, comprehensive test suite)

Technical Notes:

create_cube endpoint is fully functional and creates cubes via UserManager
register_cube endpoint validates inputs but notes that full MOSCore integration requires architectural changes
Both endpoints follow existing API patterns and conventions
Backward compatibility maintained with existing mem_cube_id usage

Base branch: main
Branch: autodev/MemOS-1681
Commit: 7a44f57
PR: #1876
Assigned to: @MatthewZhuang, @CarltonXiang, @syzsunshine219
Reviewers: @MatthewZhuang, @CarltonXiang, @syzsunshine219

Fix #1681: feat: expose cube creation in HTTP API + clarify mem_cube_…

Navigation Menu

Repository navigation

feat: expose cube creation in HTTP API + clarify mem_cube_id semantics #1681

Summary

Reproduction

Root Cause Analysis

Impact

Workarounds (what we did)

Suggested API Additions

Option 1 (Minimum fix): Auto-create on `/add`

Option 2 (Explicit): New endpoint `POST /product/create_cube`

Option 3 (Robust): Validation + clear error

Reference Integration

Versions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat: expose cube creation in HTTP API + clarify mem_cube_id semantics #1681

Description

Summary

Reproduction

Root Cause Analysis

Impact

Workarounds (what we did)

Suggested API Additions

Option 1 (Minimum fix): Auto-create on /add

Option 2 (Explicit): New endpoint POST /product/create_cube

Option 3 (Robust): Validation + clear error

Reference Integration

Versions

Activity

Memtensor-AI commented on May 28, 2026

Memtensor-AI commented on Jun 3, 2026

Memtensor-AI commented on Jun 3, 2026

Memtensor-AI commented on Jun 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Option 1 (Minimum fix): Auto-create on `/add`

Option 2 (Explicit): New endpoint `POST /product/create_cube`