Merge 'feat/fix_readme' into 'master'

fix  readme

See merge request: !13

Author: yangxinxin-7

README.md

@@ -4,9 +4,10 @@ This package provides an idiomatic Python interface to the VikingDB v2 data-plan
 
 ### Key Features
 - Simple client configuration with AK/SK signing (Volcano Engine V4) or API-key authentication.
-- Request envelope handling with typed request/response models covering collection, index, and embedding workflows.
+- **Vector Database**: Request envelope handling with typed request/response models covering collection, index, and embedding workflows.
+- **Memory Management**: Conversational memory APIs for managing user profiles, events, and session messages with semantic search capabilities.
 - Pluggable retry strategy (exponential backoff with jitter) and per-request overrides (`RequestOptions`).
-- Executable example guides (`pytest` integration tests) that demonstrate connectivity, CRUD, search, analytics, and embedding scenarios against a real VikingDB environment.
+- Executable example guides (`pytest` integration tests and standalone scripts) that demonstrate connectivity, CRUD, search, analytics, embedding, and memory management scenarios against a real VikingDB environment.
 
 ### Installation
 
@@ -20,6 +21,8 @@ pip install -e .
 
 ### Quickstart
 
+#### Vector Database
+
 ```python
 from vikingdb import IAM
 from vikingdb.vector import UpsertDataRequest, VikingVector
@@ -51,7 +54,51 @@ search_response = index.search_by_random({"limit": 1})
 print("search hits:", len(search_response.result.data) if search_response.result else 0)
 ```
 
-### Example Guides (Pytest)
+#### Memory Management
+
+```python
+from vikingdb import IAM
+from vikingdb.memory import VikingMem
+
+auth = IAM(ak="<AK>", sk="<SK>")
+client = VikingMem(
+    host="api-knowledgebase.mlp.cn-beijing.volces.com",
+    region="cn-beijing",
+    auth=auth,
+    scheme="http",
+)
+
+# Get collection
+collection = client.get_collection(
+    collection_name="demo_collection",
+    project_name="default"
+)
+
+# Add session messages
+collection.add_session(
+    session_id="session_001",
+    messages=[
+        {"role": "user", "content": "Hello, how is the weather today?"},
+        {"role": "assistant", "content": "Today is sunny, perfect for going out."}
+    ],
+    metadata={
+        "default_user_id": "user_001",
+        "default_assistant_id": "assistant_001",
+    }
+)
+
+# Search memories
+result = collection.search_memory(
+    query="weather today",
+    filter={"user_id": "user_001", "memory_type": ["event_v1"]},
+    limit=10
+)
+print("search results:", result)
+```
+
+### Example Guides
+
+#### Vector Examples (Pytest)
 
 The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`E1`–`E5`). Each test connects to a live VikingDB environment and exercises a specific workflow.
 
@@ -86,21 +133,46 @@ The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`
 
 Each scenario writes temporary documents using unique session tags and cleans them up afterwards.
 
+#### Memory Examples
+
+The memory examples under `examples/memory` demonstrate the core workflows for managing conversational memories:
+
+1. **01_init_client_and_collection.py**: Initialize the VikingMem client and get collection instances using either collection name + project name or resource ID.
+
+2. **02_add_session.py**: Add session messages (user-assistant conversations) to the memory collection with metadata such as user ID, assistant ID, and timestamps.
+
+3. **03_search_memory.py**: Search memories with various filters including:
+   - User profile search
+   - Event search by semantic query
+   - Time range filtering for recent events
+
+To run the memory examples:
+
+```bash
+# Set environment variables
+export VIKINGDB_AK=your-access-key
+export VIKINGDB_SK=your-secret-key
+
+# Run individual examples
+python examples/memory/01_init_client_and_collection.py
+python examples/memory/02_add_session.py
+python examples/memory/03_search_memory.py
+```
+
 ### Architecture Overview
 
 - `vikingdb._client`, `vikingdb.auth`, `vikingdb.request_options`, and `vikingdb.vector.exceptions` form the shared runtime used by all present and future SDK domains (vector, memory, knowledge).
-- Domain-specific features live under dedicated namespaces such as `vikingdb.vector`, where the high-level `VikingVector` client composes the shared auth stack atop the shared client.
+- Domain-specific features live under dedicated namespaces such as `vikingdb.vector` and `vikingdb.memory`, where the high-level clients (`VikingVector`, `VikingMem`) compose the shared auth stack atop the shared client.
 - Vector request/response models now surface directly from `vikingdb.vector` (backed internally by `vikingdb/vector/models`).
-- Imports from the root package now focus on cross-cutting utilities (auth, config, request options), while application code should pull vector functionality from `vikingdb.vector` explicitly.
+- Memory APIs return plain dictionaries without object encapsulation, providing a lightweight interface for conversational memory management (session, profile, event operations).
+- Imports from the root package now focus on cross-cutting utilities (auth, config, request options), while application code should pull domain-specific functionality from `vikingdb.vector` or `vikingdb.memory` explicitly.
 
 ### Project Structure
 
 ```
 vikingdb/
 ├── _client.py          # Shared base client built on volcengine Service
-├── config.py            # Shared client / retry configuration
 ├── auth.py              # Shared auth providers (IAM, API key)
-├── exceptions.py        # Error hierarchy reused across domains
 ├── request_options.py   # Per-request overrides shared by all services
 ├── version.py           # Package metadata
 ├── vector/              # Vector-specific clients and models
@@ -110,10 +182,25 @@ vikingdb/
 │   ├── embedding.py     # Embedding operations
 │   ├── index.py         # Index/search operations
 │   ├── client.py        # Vector service wrapper and high-level client
+│   ├── exceptions.py    # Vector-specific exceptions
 │   └── models/          # Vector request/response models (pydantic)
-
-examples/vector/         # Integration guides (pytest)
-docs/python_sdk_design.md# Design notes and parity checklist
+├── memory/              # Memory-specific clients and models
+│   ├── __init__.py      # High-level memory client and namespace exports
+│   ├── client.py        # VikingMem service client
+│   ├── collection.py    # Memory collection operations
+│   ├── types.py         # Type definitions for memory operations
+│   └── exceptions.py    # Memory-specific exceptions
+
+examples/
+├── vector/              # Vector integration guides (pytest)
+│   ├── E1_connectivity_test.py
+│   ├── E2_collection_lifecycle_test.py
+│   ├── E3_*_test.py     # Search and indexing examples
+│   └── ...
+└── memory/              # Memory usage examples
+    ├── 01_init_client_and_collection.py
+    ├── 02_add_session.py
+    └── 03_search_memory.py
 ```
 
 ### Contributing