remembermemory 0.1.1

RememberMe — 让 AI 拥有持久记忆

RememberMe Python SDK

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

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

安装

pip install remembermemory

# 如需异步支持
pip install remembermemory[async]

快速开始

1. 获取 API Key

登录 RememberMe Dashboard，进入「API Keys」页面创建密钥。

2. 三行代码接入

from rememberme import RememberMe

client = RememberMe(api_key="rm_sk_你的密钥")
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 参考

初始化

from rememberme import RememberMe

client = RememberMe(
    api_key="rm_sk_xxx",           # 必填：API Key
    base_url="https://www.rememberme.tech",  # 默认值，可省略
    timeout=30,                     # 请求超时秒数（默认 30）
)

client.add() — 写入记忆

# 方式一：纯文本
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() — 语义搜索

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() — 列出记忆

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

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

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

client.update() — 更新记忆

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

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

client.delete("memory_id_xxx")

client.delete_all() — 批量删除

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

client.history() — 变更历史

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

---

异步客户端

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

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 remembermemory[async]

---

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

from openai import OpenAI
from rememberme import RememberMe

memory = RememberMe(api_key="rm_sk_xxx")
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 提供了细粒度的异常类：

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：

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

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

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

# 删除单条
curl -X DELETE https://www.rememberme.tech/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