MemoryOS 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

memos/api/routers/__init__.py

@@ -0,0 +1 @@
+# API routers module

memos/api/routers/product_router.py

@@ -0,0 +1,358 @@
+import json
+import logging
+import traceback
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from memos.api.config import APIConfig
+from memos.api.product_models import (
+    BaseResponse,
+    ChatRequest,
+    GetMemoryRequest,
+    MemoryCreateRequest,
+    MemoryResponse,
+    SearchRequest,
+    SearchResponse,
+    SimpleResponse,
+    SuggestionRequest,
+    SuggestionResponse,
+    UserRegisterRequest,
+    UserRegisterResponse,
+)
+from memos.configs.mem_os import MOSConfig
+from memos.mem_os.product import MOSProduct
+
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/product", tags=["Product API"])
+
+# Initialize MOSProduct instance with lazy initialization
+MOS_PRODUCT_INSTANCE = None
+
+
+def get_mos_product_instance():
+    """Get or create MOSProduct instance."""
+    global MOS_PRODUCT_INSTANCE
+    if MOS_PRODUCT_INSTANCE is None:
+        default_config = APIConfig.get_product_default_config()
+        print(default_config)
+        from memos.configs.mem_os import MOSConfig
+
+        mos_config = MOSConfig(**default_config)
+
+        # Get default cube config from APIConfig (may be None if disabled)
+        default_cube_config = APIConfig.get_default_cube_config()
+        print("*********default_cube_config*********", default_cube_config)
+        MOS_PRODUCT_INSTANCE = MOSProduct(
+            default_config=mos_config, default_cube_config=default_cube_config
+        )
+        logger.info("MOSProduct instance created successfully with inheritance architecture")
+    return MOS_PRODUCT_INSTANCE
+
+
+get_mos_product_instance()
+
+
+@router.post("/configure", summary="Configure MOSProduct", response_model=SimpleResponse)
+async def set_config(config):
+    """Set MOSProduct configuration."""
+    global MOS_PRODUCT_INSTANCE
+    MOS_PRODUCT_INSTANCE = MOSProduct(default_config=config)
+    return SimpleResponse(message="Configuration set successfully")
+
+
+@router.post("/users/register", summary="Register a new user", response_model=UserRegisterResponse)
+async def register_user(user_req: UserRegisterRequest):
+    """Register a new user with configuration and default cube."""
+    try:
+        # Get configuration for the user
+        user_config, default_mem_cube = APIConfig.create_user_config(
+            user_name=user_req.user_id, user_id=user_req.user_id
+        )
+        logger.info(f"user_config: {user_config.model_dump(mode='json')}")
+        logger.info(f"default_mem_cube: {default_mem_cube.config.model_dump(mode='json')}")
+        mos_product = get_mos_product_instance()
+
+        # Register user with default config and mem cube
+        result = mos_product.user_register(
+            user_id=user_req.user_id,
+            user_name=user_req.user_name,
+            interests=user_req.interests,
+            config=user_config,
+            default_mem_cube=default_mem_cube,
+        )
+
+        if result["status"] == "success":
+            return UserRegisterResponse(
+                message="User registered successfully",
+                data={"user_id": result["user_id"], "mem_cube_id": result["default_cube_id"]},
+            )
+        else:
+            raise HTTPException(status_code=400, detail=result["message"])
+
+    except Exception as err:
+        logger.error(f"Failed to register user: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get(
+    "/suggestions/{user_id}", summary="Get suggestion queries", response_model=SuggestionResponse
+)
+async def get_suggestion_queries(user_id: str):
+    """Get suggestion queries for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        suggestions = mos_product.get_suggestion_query(user_id)
+        return SuggestionResponse(
+            message="Suggestions retrieved successfully", data={"query": suggestions}
+        )
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get suggestions: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post(
+    "/suggestions",
+    summary="Get suggestion queries with language",
+    response_model=SuggestionResponse,
+)
+async def get_suggestion_queries_post(suggestion_req: SuggestionRequest):
+    """Get suggestion queries for a specific user with language preference."""
+    try:
+        mos_product = get_mos_product_instance()
+        suggestions = mos_product.get_suggestion_query(
+            user_id=suggestion_req.user_id, language=suggestion_req.language
+        )
+        return SuggestionResponse(
+            message="Suggestions retrieved successfully", data={"query": suggestions}
+        )
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get suggestions: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/get_all", summary="Get all memories for user", response_model=MemoryResponse)
+async def get_all_memories(memory_req: GetMemoryRequest):
+    """Get all memories for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        if memory_req.search_query:
+            result = mos_product.get_subgraph(
+                user_id=memory_req.user_id,
+                query=memory_req.search_query,
+                mem_cube_ids=memory_req.mem_cube_ids,
+            )
+            return MemoryResponse(message="Memories retrieved successfully", data=result)
+        else:
+            result = mos_product.get_all(
+                user_id=memory_req.user_id,
+                memory_type=memory_req.memory_type,
+                mem_cube_ids=memory_req.mem_cube_ids,
+            )
+            return MemoryResponse(message="Memories retrieved successfully", data=result)
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get memories: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/add", summary="add a new memory", response_model=SimpleResponse)
+async def create_memory(memory_req: MemoryCreateRequest):
+    """Create a new memory for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        mos_product.add(
+            user_id=memory_req.user_id,
+            memory_content=memory_req.memory_content,
+            messages=memory_req.messages,
+            doc_path=memory_req.doc_path,
+            mem_cube_id=memory_req.mem_cube_id,
+        )
+        return SimpleResponse(message="Memory created successfully")
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to create memory: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/search", summary="Search memories", response_model=SearchResponse)
+async def search_memories(search_req: SearchRequest):
+    """Search memories for a specific user."""
+    try:
+        mos_product = get_mos_product_instance()
+        result = mos_product.search(
+            query=search_req.query,
+            user_id=search_req.user_id,
+            install_cube_ids=[search_req.mem_cube_id] if search_req.mem_cube_id else None,
+        )
+        return SearchResponse(message="Search completed successfully", data=result)
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to search memories: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.post("/chat", summary="Chat with MemOS")
+async def chat(chat_req: ChatRequest):
+    """Chat with MemOS for a specific user. Returns SSE stream."""
+    try:
+        mos_product = get_mos_product_instance()
+
+        async def generate_chat_response():
+            """Generate chat response as SSE stream."""
+            try:
+                import asyncio
+
+                for chunk in mos_product.chat_with_references(
+                    query=chat_req.query,
+                    user_id=chat_req.user_id,
+                    cube_id=chat_req.mem_cube_id,
+                    history=chat_req.history,
+                ):
+                    yield chunk
+                    await asyncio.sleep(0.00001)  # 50ms delay between chunks
+            except Exception as e:
+                logger.error(f"Error in chat stream: {e}")
+                error_data = f"data: {json.dumps({'type': 'error', 'content': str(traceback.format_exc())})}\n\n"
+                yield error_data
+
+        return StreamingResponse(
+            generate_chat_response(),
+            media_type="text/plain",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Content-Type": "text/event-stream",
+            },
+        )
+
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to start chat: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get("/users", summary="List all users", response_model=BaseResponse[list])
+async def list_users():
+    """List all registered users."""
+    try:
+        mos_product = get_mos_product_instance()
+        users = mos_product.list_users()
+        return BaseResponse(message="Users retrieved successfully", data=users)
+    except Exception as err:
+        logger.error(f"Failed to list users: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get("/users/{user_id}", summary="Get user info", response_model=BaseResponse[dict])
+async def get_user_info(user_id: str):
+    """Get user information including accessible cubes."""
+    try:
+        mos_product = get_mos_product_instance()
+        user_info = mos_product.get_user_info(user_id)
+        return BaseResponse(message="User info retrieved successfully", data=user_info)
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get user info: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get(
+    "/configure/{user_id}", summary="Get MOSProduct configuration", response_model=SimpleResponse
+)
+async def get_config(user_id: str):
+    """Get MOSProduct configuration."""
+    global MOS_PRODUCT_INSTANCE
+    config = MOS_PRODUCT_INSTANCE.default_config
+    return SimpleResponse(message="Configuration retrieved successfully", data=config)
+
+
+@router.get(
+    "/users/{user_id}/config", summary="Get user configuration", response_model=BaseResponse[dict]
+)
+async def get_user_config(user_id: str):
+    """Get user-specific configuration."""
+    try:
+        mos_product = get_mos_product_instance()
+        config = mos_product.get_user_config(user_id)
+        if config:
+            return BaseResponse(
+                message="User configuration retrieved successfully",
+                data=config.model_dump(mode="json"),
+            )
+        else:
+            raise HTTPException(
+                status_code=404, detail=f"Configuration not found for user {user_id}"
+            )
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to get user config: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.put(
+    "/users/{user_id}/config", summary="Update user configuration", response_model=SimpleResponse
+)
+async def update_user_config(user_id: str, config_data: dict):
+    """Update user-specific configuration."""
+    try:
+        mos_product = get_mos_product_instance()
+
+        # Create MOSConfig from the provided data
+        config = MOSConfig(**config_data)
+
+        # Update the configuration
+        success = mos_product.update_user_config(user_id, config)
+        if success:
+            return SimpleResponse(message="User configuration updated successfully")
+        else:
+            raise HTTPException(status_code=500, detail="Failed to update user configuration")
+
+    except ValueError as err:
+        raise HTTPException(status_code=400, detail=str(traceback.format_exc())) from err
+    except Exception as err:
+        logger.error(f"Failed to update user config: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get(
+    "/instances/status", summary="Get user configuration status", response_model=BaseResponse[dict]
+)
+async def get_instance_status():
+    """Get information about active user configurations in memory."""
+    try:
+        mos_product = get_mos_product_instance()
+        status_info = mos_product.get_user_instance_info()
+        return BaseResponse(
+            message="User configuration status retrieved successfully", data=status_info
+        )
+    except Exception as err:
+        logger.error(f"Failed to get user configuration status: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err
+
+
+@router.get("/instances/count", summary="Get active user count", response_model=BaseResponse[int])
+async def get_active_user_count():
+    """Get the number of active user configurations in memory."""
+    try:
+        mos_product = get_mos_product_instance()
+        count = mos_product.get_active_user_count()
+        return BaseResponse(message="Active user count retrieved successfully", data=count)
+    except Exception as err:
+        logger.error(f"Failed to get active user count: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(traceback.format_exc())) from err

memos/chunkers/sentence_chunker.py

@@ -1,6 +1,5 @@
-from chonkie import SentenceChunker as ChonkieSentenceChunker
-
 from memos.configs.chunker import SentenceChunkerConfig
+from memos.dependency import require_python_package
 from memos.log import get_logger
 
 from .base import BaseChunker, Chunk
@@ -12,7 +11,14 @@ logger = get_logger(__name__)
 class SentenceChunker(BaseChunker):
     """Sentence-based text chunker."""
 
+    @require_python_package(
+        import_name="chonkie",
+        install_command="pip install chonkie",
+        install_link="https://docs.chonkie.ai/python-sdk/getting-started/installation",
+    )
     def __init__(self, config: SentenceChunkerConfig):
+        from chonkie import SentenceChunker as ChonkieSentenceChunker
+
         self.config = config
         self.chunker = ChonkieSentenceChunker(
             tokenizer_or_token_counter=config.tokenizer_or_token_counter,

memos/cli.py

@@ -0,0 +1,113 @@
+"""
+MemOS CLI Tool
+This script provides command-line interface for MemOS operations.
+"""
+
+import argparse
+import json
+import os
+import zipfile
+
+from io import BytesIO
+
+
+def export_openapi(output: str) -> bool:
+    """Export OpenAPI schema to JSON file."""
+    from memos.api.start_api import app
+
+    # Create directory if it doesn't exist
+    if os.path.dirname(output):
+        os.makedirs(os.path.dirname(output), exist_ok=True)
+
+    with open(output, "w") as f:
+        json.dump(app.openapi(), f, indent=2)
+        f.write("\n")
+
+    print(f"✅ OpenAPI schema exported to: {output}")
+    return True
+
+
+def download_examples(dest: str) -> bool:
+    import requests
+
+    """Download examples from the MemOS repository."""
+    zip_url = "https://github.com/MemTensor/MemOS/archive/refs/heads/main.zip"
+    print(f"📥 Downloading examples from {zip_url}...")
+
+    try:
+        response = requests.get(zip_url)
+        response.raise_for_status()
+
+        with zipfile.ZipFile(BytesIO(response.content)) as z:
+            extracted_files = []
+            for file in z.namelist():
+                if "MemOS-main/examples/" in file and not file.endswith("/"):
+                    # Remove the prefix and extract to dest
+                    relative_path = file.replace("MemOS-main/examples/", "")
+                    extract_path = os.path.join(dest, relative_path)
+
+                    # Create directory if it doesn't exist
+                    os.makedirs(os.path.dirname(extract_path), exist_ok=True)
+
+                    # Extract the file
+                    with z.open(file) as source, open(extract_path, "wb") as target:
+                        target.write(source.read())
+                    extracted_files.append(extract_path)
+
+        print(f"✅ Examples downloaded to: {dest}")
+        print(f"📁 {len(extracted_files)} files extracted")
+
+    except requests.RequestException as e:
+        print(f"❌ Error downloading examples: {e}")
+        return False
+    except Exception as e:
+        print(f"❌ Error extracting examples: {e}")
+        return False
+
+    return True
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="memos",
+        description="MemOS Command Line Interface",
+    )
+
+    # Create subparsers for different commands
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Download examples command
+    examples_parser = subparsers.add_parser("download_examples", help="Download example files")
+    examples_parser.add_argument(
+        "--dest",
+        type=str,
+        default="./examples",
+        help="Destination directory for examples (default: ./examples)",
+    )
+
+    # Export API command
+    api_parser = subparsers.add_parser("export_openapi", help="Export OpenAPI schema to JSON file")
+    api_parser.add_argument(
+        "--output",
+        type=str,
+        default="openapi.json",
+        help="Output path for OpenAPI schema (default: openapi.json)",
+    )
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    # Handle commands
+    if args.command == "download_examples":
+        success = download_examples(args.dest)
+        exit(0 if success else 1)
+    elif args.command == "export_openapi":
+        success = export_openapi(args.output)
+        exit(0 if success else 1)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

memos/configs/embedder.py

@@ -18,6 +18,18 @@ class OllamaEmbedderConfig(BaseEmbedderConfig):
     api_base: str = Field(default="http://localhost:11434", description="Base URL for Ollama API")
 
 
+class ArkEmbedderConfig(BaseEmbedderConfig):
+    api_key: str = Field(..., description="Ark API key")
+    api_base: str = Field(
+        default="https://ark.cn-beijing.volces.com/api/v3/", description="Base URL for Ark API"
+    )
+    chunk_size: int = Field(default=1, description="Chunk size for Ark API")
+    multi_modal: bool = Field(
+        default=False,
+        description="Whether to use multi-modal embedding (text + image) with Ark",
+    )
+
+
 class SenTranEmbedderConfig(BaseEmbedderConfig):
     """Configuration class for Sentence Transformer embeddings."""
 
@@ -27,6 +39,19 @@ class SenTranEmbedderConfig(BaseEmbedderConfig):
     )
 
 
+class UniversalAPIEmbedderConfig(BaseEmbedderConfig):
+    """
+    Configuration class for universal API embedding providers, e.g.,
+    OpenAI, etc.
+    """
+
+    provider: str = Field(..., description="Provider name, e.g., 'openai'")
+    api_key: str = Field(..., description="API key for the embedding provider")
+    base_url: str | None = Field(
+        default=None, description="Optional base URL for custom or proxied endpoint"
+    )
+
+
 class EmbedderConfigFactory(BaseConfig):
     """Factory class for creating embedder configurations."""
 
@@ -36,6 +61,8 @@ class EmbedderConfigFactory(BaseConfig):
     backend_to_class: ClassVar[dict[str, Any]] = {
         "ollama": OllamaEmbedderConfig,
         "sentence_transformer": SenTranEmbedderConfig,
+        "ark": ArkEmbedderConfig,
+        "universal_api": UniversalAPIEmbedderConfig,
     }
 
     @field_validator("backend")

memos/configs/graph_db.py

@@ -3,6 +3,7 @@ from typing import Any, ClassVar
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 from memos.configs.base import BaseConfig
+from memos.configs.vec_db import VectorDBConfigFactory
 
 
 class BaseGraphDBConfig(BaseConfig):
@@ -14,14 +15,93 @@ class BaseGraphDBConfig(BaseConfig):
 
 
 class Neo4jGraphDBConfig(BaseGraphDBConfig):
-    """Neo4j-specific configuration."""
+    """
+    Neo4j-specific configuration.
+
+    This config supports:
+    1) Physical isolation (multi-db) — each user gets a dedicated Neo4j database.
+    2) Logical isolation (single-db) — all users share one or more databases, but each node is tagged with `user_name`.
+
+    How to use:
+    - If `use_multi_db=True`, then `db_name` should usually be the same as `user_name`.
+      Each user gets a separate database for physical isolation.
+      Example: db_name = "alice", user_name = None or "alice".
+
+    - If `use_multi_db=False`, then `db_name` is your shared database (e.g., "neo4j" or "shared_db").
+      You must provide `user_name` to logically isolate each user's data.
+      All nodes and queries must respect this tag.
+
+    Example configs:
+    ---
+    # Physical isolation:
+    db_name = "alice"
+    use_multi_db = True
+    user_name = None
+
+    # Logical isolation:
+    db_name = "shared_db_student_group"
+    use_multi_db = False
+    user_name = "alice"
+    """
 
     db_name: str = Field(..., description="The name of the target Neo4j database")
     auto_create: bool = Field(
-        default=False, description="Whether to create the DB if it doesn't exist"
+        default=False,
+        description="If True, automatically create the target db_name in multi-db mode if it does not exist.",
     )
+
+    use_multi_db: bool = Field(
+        default=True,
+        description=(
+            "If True: use Neo4j's multi-database feature for physical isolation; "
+            "each user typically gets a separate database. "
+            "If False: use a single shared database with logical isolation by user_name."
+        ),
+    )
+
+    user_name: str | None = Field(
+        default=None,
+        description=(
+            "Logical user or tenant ID for data isolation. "
+            "Required if use_multi_db is False. "
+            "All nodes must be tagged with this and all queries must filter by this."
+        ),
+    )
+
     embedding_dimension: int = Field(default=768, description="Dimension of vector embedding")
 
+    @model_validator(mode="after")
+    def validate_config(self):
+        """Validate logical constraints to avoid misconfiguration."""
+        if not self.use_multi_db and not self.user_name:
+            raise ValueError(
+                "In single-database mode (use_multi_db=False), `user_name` must be provided for logical isolation."
+            )
+        return self
+
+
+class Neo4jCommunityGraphDBConfig(Neo4jGraphDBConfig):
+    """
+    Community edition config for Neo4j.
+
+    Notes:
+    - Must set `use_multi_db = False`
+    - Must provide `user_name` for logical isolation
+    - Embedding vector DB config is required
+    """
+
+    vec_config: VectorDBConfigFactory = Field(
+        ..., description="Vector DB config for embedding search"
+    )
+
+    @model_validator(mode="after")
+    def validate_community(self):
+        if self.use_multi_db:
+            raise ValueError("Neo4j Community Edition does not support use_multi_db=True.")
+        if not self.user_name:
+            raise ValueError("Neo4j Community config requires user_name for logical isolation.")
+        return self
+
 
 class GraphDBConfigFactory(BaseModel):
     backend: str = Field(..., description="Backend for graph database")
@@ -29,6 +109,7 @@ class GraphDBConfigFactory(BaseModel):
 
     backend_to_class: ClassVar[dict[str, Any]] = {
         "neo4j": Neo4jGraphDBConfig,
+        "neo4j-community": Neo4jCommunityGraphDBConfig,
     }
 
     @field_validator("backend")