SDK_README.md•6.59 kB
# MemOS Memory Ops SDK
轻量级记忆操作SDK，提供简单易用的一行代码接口，基于MVP管理器封装，便于其他脚本集成记忆功能。
## 🚀 快速开始
### 安装依赖
```bash
# 确保在MemOS项目目录中
cd /path/to/MemOS
./venv/bin/pip install -r requirements.txt
```
### 基础使用
```python
from memory_ops_sdk import MemoryOps
# 初始化SDK
mem = MemoryOps(data_dir="./my_memories", verbose=True)
# 添加记忆
mem.add("今天学习了Python编程", tags=["学习", "Python"])
# 查询记忆
results = mem.query("Python编程")
# 提供反馈
if results:
mem.feedback(results[0]['id'], "👍")
# 关闭SDK
mem.close()
```
## 📚 API 参考
### MemoryOps 类
#### 初始化
```python
MemoryOps(data_dir=None, use_enhanced=True, auto_init=True, verbose=False)
```
**参数:**
- `data_dir` (str, 可选): 数据目录路径，默认为 `./memos_data`
- `use_enhanced` (bool): 是否使用增强版MemOS（Qwen模型），默认 `True`
- `auto_init` (bool): 是否自动初始化，默认 `True`
- `verbose` (bool): 是否显示详细日志，默认 `False`
#### 核心方法
##### `add(text, tags=None, metadata=None) -> bool`
添加记忆（一行代码接口）
```python
# 基础用法
mem.add("学习内容")
# 带标签
mem.add("学习内容", tags=["学习", "Python"])
# 带元数据
metadata = {"source": "课程", "difficulty": "medium"}
mem.add("学习内容", tags=["学习"], metadata=metadata)
```
##### `query(q, limit=5, use_reranker=True, use_time_decay=True, use_topic_drift=True) -> List[Dict]`
查询记忆（一行代码接口）
```python
# 基础查询
results = mem.query("Python编程")
# 高级查询
results = mem.query(
"Python编程",
limit=10,
use_reranker=True,
use_time_decay=True,
use_topic_drift=False
)
```
##### `feedback(memory_id, feedback_type) -> bool`
提供记忆反馈
```python
# 支持的反馈类型
mem.feedback(memory_id, "👍") # 好评
mem.feedback(memory_id, "👎") # 差评
mem.feedback(memory_id, "thumbs_up") # 好评
mem.feedback(memory_id, "thumbs_down") # 差评
```
##### `stats() -> Dict`
获取记忆统计信息
```python
stats = mem.stats()
print(f"系统状态: {stats['status']}")
print(f"反馈统计: {stats['feedback']}")
print(f"容量信息: {stats['capacity']}")
```
##### `dump(output_file=None) -> List[Dict]`
导出所有记忆
```python
# 返回记忆列表
memories = mem.dump()
# 同时保存到文件
memories = mem.dump("backup.json")
```
##### `optimize() -> bool`
触发系统优化
```python
success = mem.optimize()
```
##### `health() -> bool`
健康检查
```python
is_healthy = mem.health()
```
## 🛠️ 使用模式
### 1. 基础模式
```python
from memory_ops_sdk import MemoryOps
mem = MemoryOps()
mem.add("记忆内容")
results = mem.query("查询内容")
mem.close()
```
### 2. 上下文管理器模式（推荐）
```python
from memory_ops_sdk import MemoryOps
with MemoryOps(data_dir="./memories") as mem:
mem.add("记忆内容")
results = mem.query("查询内容")
# 自动清理资源
```
### 3. 便捷函数模式
```python
from memory_ops_sdk import create_memory_ops
mem = create_memory_ops("./memories", verbose=True)
mem.add("记忆内容")
mem.close()
```
### 4. 全局单例模式
```python
from memory_ops_sdk import get_global_memory_ops
mem = get_global_memory_ops(data_dir="./memories")
mem.add("记忆内容")
# 全局实例，无需手动关闭
```
## 🎯 实际应用示例
### 智能笔记应用
```python
class SmartNoteTaker:
def __init__(self):
self.mem = MemoryOps(data_dir="./notes")
def add_note(self, content, category="general"):
metadata = {"category": category, "app": "notes"}
return self.mem.add(content, tags=[category], metadata=metadata)
def search_notes(self, query):
return self.mem.query(query)
```
### 学习助手
```python
class LearningAssistant:
def __init__(self):
self.mem = MemoryOps(data_dir="./learning")
def record_learning(self, topic, content):
tags = ["learning", topic]
metadata = {"topic": topic, "date": datetime.now().isoformat()}
return self.mem.add(content, tags=tags, metadata=metadata)
def review_topic(self, topic):
return self.mem.query(topic, limit=10)
```
### 问答系统
```python
class QASystem:
def __init__(self):
self.mem = MemoryOps(data_dir="./qa")
def add_qa(self, question, answer):
content = f"Q: {question}\nA: {answer}"
return self.mem.add(content, tags=["qa"])
def answer_question(self, question):
results = self.mem.query(question, limit=3)
return [r['content'] for r in results]
```
## ⚡ 性能优化建议
### 1. 批量操作
```python
# 推荐：批量添加
with MemoryOps() as mem:
for item in large_dataset:
mem.add(item['content'], tags=item['tags'])
```
### 2. 查询优化
```python
# 根据需要调整参数
results = mem.query(
"查询内容",
limit=5, # 限制结果数量
use_reranker=True, # 高质量排序
use_time_decay=True, # 时间感知
use_topic_drift=False # 如不需要可禁用
)
```
### 3. 资源管理
```python
# 推荐：使用上下文管理器
with MemoryOps() as mem:
# 操作
pass # 自动清理
# 或手动管理
mem = MemoryOps()
try:
# 操作
pass
finally:
mem.close()
```
## 🔧 配置选项
### 数据目录结构
```
data_dir/
├── memories.db # 记忆数据库
├── embeddings/ # 向量嵌入
├── config.json # 配置文件
└── logs/ # 日志文件
```
### 环境变量
```bash
# 可选环境变量
export MEMOS_DATA_DIR="./custom_memories"
export MEMOS_VERBOSE="true"
export MEMOS_USE_ENHANCED="true"
```
## 🐛 错误处理
### 常见错误
```python
from memory_ops_sdk import MemoryOps
try:
mem = MemoryOps()
mem.add("内容")
except RuntimeError as e:
print(f"SDK未初始化: {e}")
except Exception as e:
print(f"其他错误: {e}")
```
### 调试模式
```python
# 启用详细日志
mem = MemoryOps(verbose=True)
# 检查系统健康
if not mem.health():
print("系统异常，请检查配置")
```
## 📋 完整示例
查看 `examples/` 目录中的完整示例：
- `basic_usage.py` - 基础使用示例
- `integration_example.py` - 集成应用示例
## 🤝 贡献
欢迎提交Issue和Pull Request来改进SDK！
## 📄 许可证
本项目采用MIT许可证。