Metadata-Version: 2.4
Name: remembermemory
Version: 0.1.0
Summary: RememberMe SDK — 让 AI 拥有持久记忆
Project-URL: Homepage, https://github.com/rememberme/rememberme-python
Project-URL: Documentation, https://docs.rememberme.dev
Author: RememberMe Team
License-Expression: MIT
Keywords: ai,llm,memory,rememberme,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Provides-Extra: async
Requires-Dist: httpx>=0.24; extra == 'async'
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# RememberMe Python SDK

**让 AI 拥有持久记忆 —— 只需 3 行代码。**

RememberMe 是一个可插拔的通用记忆模块，为任何 AI 应用提供用户级别的长期记忆能力。SDK 封装了 RememberMe 服务端 API，支持同步和异步两种调用方式。

## 安装

```bash
pip install rememberme-sdk

# 如需异步支持
pip install rememberme-sdk[async]
```

## 快速开始

### 1. 获取 API Key

登录 [RememberMe Dashboard](https://your-server.com)，进入「API Keys」页面创建密钥。

### 2. 三行代码接入

```python
from rememberme import RememberMe

client = RememberMe(api_key="rm_sk_你的密钥", base_url="https://your-server.com")
client.add("用户喜欢简洁的回答风格", user_id="u_123")
```

就这么简单。你的 AI 现在拥有了记忆。

---

## 核心概念

| 概念 | 说明 |
|------|------|
| **API Key** | 在 Dashboard 中创建，用于 SDK 认证。以 `rm_sk_` 开头 |
| **user_id** | 终端用户标识。每个 user_id 拥有独立的记忆空间 |
| **agent_id** | Agent 标识（可选），用于区分不同 AI Agent 的记忆 |
| **run_id** | 会话标识（可选），用于按对话轮次组织记忆 |
| **infer** | 写入时是否让 LLM 自动提取关键事实（默认 `True`） |推荐开启

---

## API 参考

### 初始化

```python
from rememberme import RememberMe

client = RememberMe(
    api_key="rm_sk_xxx",           # 必填：API Key
    base_url="https://your-server.com",  # 你的 RememberMe 服务地址
    timeout=30,                     # 请求超时秒数（默认 30）
)
```

### `client.add()` — 写入记忆

```python
# 方式一：纯文本
result = client.add("用户是一名 Python 开发者", user_id="u_123")

# 方式二：对话消息列表（LLM 自动提取关键信息）
result = client.add(
    [
        {"role": "user", "content": "我在北京工作，做机器学习方向"},
        {"role": "assistant", "content": "了解！北京的 AI 圈很活跃"},
    ],
    user_id="u_123",
    metadata={"source": "chat"},  # 可选：附加元数据
)

# result.results -> [{"id": "xxx", "memory": "用户在北京工作...", "event": "ADD"}]
```

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `messages` | `str \| list[dict]` | 是 | 记忆内容或对话列表 |
| `user_id` | `str` | 否 | 终端用户 ID |
| `agent_id` | `str` | 否 | Agent ID |
| `run_id` | `str` | 否 | 会话 ID |
| `metadata` | `dict` | 否 | 附加元数据 |
| `infer` | `bool` | 否 | 是否 LLM 提取事实（默认 True） |

### `client.search()` — 语义搜索

```python
results = client.search(
    "用户的工作和技能",
    user_id="u_123",
    limit=5,
)

for mem in results.memories:
    print(f"[相关度 {mem.score:.2f}] {mem.memory}")
```

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | `str` | 是 | 自然语言搜索查询 |
| `user_id` | `str` | 否 | 按用户过滤 |
| `agent_id` | `str` | 否 | 按 Agent 过滤 |
| `run_id` | `str` | 否 | 按会话过滤 |
| `limit` | `int` | 否 | 最多返回条数（默认 10，上限 100） |
| `threshold` | `float` | 否 | 最低相似度阈值（0~1） |

### `client.get_all()` — 列出记忆

```python
memories = client.get_all(user_id="u_123", limit=50)
for mem in memories.memories:
    print(f"• {mem.memory}")
```

### `client.get()` — 获取单条记忆

```python
mem = client.get("memory_id_xxx")
print(mem.memory, mem.created_at)
```

### `client.update()` — 更新记忆

```python
client.update("memory_id_xxx", "更新后的记忆内容")
```

### `client.delete()` — 删除单条记忆

```python
client.delete("memory_id_xxx")
```

### `client.delete_all()` — 批量删除

```python
client.delete_all(user_id="u_123")  # 删除该用户所有记忆
```

### `client.history()` — 变更历史

```python
history = client.history("memory_id_xxx")
for entry in history:
    print(entry)
```

---

## 异步客户端

适用于 FastAPI、aiohttp 等异步框架：

```python
from rememberme import AsyncRememberMe

async with AsyncRememberMe(api_key="rm_sk_xxx") as client:
    await client.add("用户喜欢暗色主题", user_id="u_123")
    results = await client.search("界面偏好", user_id="u_123")
```

异步客户端的 API 与同步客户端完全一致，所有方法前加 `await` 即可。

> 异步客户端需安装 httpx：`pip install rememberme-sdk[async]`

---

## 实战：为聊天机器人添加记忆

```python
from openai import OpenAI
from rememberme import RememberMe

memory = RememberMe(api_key="rm_sk_xxx", base_url="https://your-server.com")
llm = OpenAI()


def chat(user_id: str, user_message: str) -> str:
    # 1. 检索相关记忆
    relevant = memory.search(user_message, user_id=user_id, limit=5)
    context = "\n".join(f"- {m.memory}" for m in relevant.memories)

    # 2. 注入到 system prompt
    system = "你是一个友好的助手。"
    if context:
        system += f"\n\n你对这位用户的了解：\n{context}"

    # 3. 调用 LLM
    resp = llm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": system},
            {"role": "user", "content": user_message},
        ],
    )
    reply = resp.choices[0].message.content

    # 4. 保存对话到记忆
    memory.add(
        [
            {"role": "user", "content": user_message},
            {"role": "assistant", "content": reply},
        ],
        user_id=user_id,
    )

    return reply
```

---

## 错误处理

SDK 提供了细粒度的异常类：

```python
from rememberme import RememberMe, AuthenticationError, NotFoundError

client = RememberMe(api_key="rm_sk_xxx")

try:
    client.add("test", user_id="u_1")
except AuthenticationError:
    print("API Key 无效，请检查密钥")
except NotFoundError:
    print("资源不存在")
```

| 异常类 | HTTP 状态码 | 说明 |
|--------|------------|------|
| `AuthenticationError` | 401 | API Key 无效或已过期 |
| `PermissionError` | 403 | 权限不足（如只读 Key 尝试写入） |
| `NotFoundError` | 404 | 记忆不存在 |
| `ValidationError` | 422 | 请求参数格式错误 |
| `RateLimitError` | 429 | 请求频率超限 |
| `ServerError` | 5xx | 服务端内部错误 |
| `RememberMeError` | * | 所有异常的基类 |

---

## REST API 直接调用

如果你不使用 Python，可以直接调用 HTTP API：

```bash
# 写入记忆
curl -X POST https://your-server.com/api/memories \
  -H "Authorization: Bearer rm_sk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"messages": "用户喜欢Python", "user_id": "u_123"}'

# 语义搜索
curl -X POST https://your-server.com/api/memories/search \
  -H "Authorization: Bearer rm_sk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"query": "用户偏好", "user_id": "u_123"}'

# 列出记忆
curl https://your-server.com/api/memories?user_id=u_123 \
  -H "Authorization: Bearer rm_sk_你的密钥"

# 删除单条
curl -X DELETE https://your-server.com/api/memories/{memory_id} \
  -H "Authorization: Bearer rm_sk_你的密钥"
```

### API 端点一览

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/memories` | 写入记忆 |
| `POST` | `/api/memories/search` | 语义搜索 |
| `GET` | `/api/memories` | 列出记忆 |
| `GET` | `/api/memories/{id}` | 获取单条记忆 |
| `PUT` | `/api/memories/{id}` | 更新记忆 |
| `DELETE` | `/api/memories/{id}` | 删除单条记忆 |
| `DELETE` | `/api/memories` | 批量删除 |
| `GET` | `/api/memories/{id}/history` | 变更历史 |

### 认证方式

所有 API 请求需要在 Header 中携带 API Key：

```
Authorization: Bearer rm_sk_你的密钥
```

---

## API Key 权限

创建 API Key 时可以选择权限级别：

| 权限 | 读取 | 写入 | 删除 |
|------|------|------|------|
| `full` | ✅ | ✅ | ✅ |
| `read-write` | ✅ | ✅ | ❌ |
| `read` | ✅ | ❌ | ❌ |

---

## License

MIT
