TiMem API 接入全攻略：5分钟给你的 AI 应用加上长期记忆
TiMem 是目前长对话记忆准确率最高的开源框架（LoCoMo 75.30%，LongMemEval-S 76.88%），本文从注册到第一个请求，手把手带你接入。
前置准备
1. 注册并获取 API Key
- 访问 console.timem.cloud 注册账号
-
- 创建项目，生成 API Key
-
- 记下
api_key，后续所有请求都需要
- 记下
2. 安装 SDK
pip install timem
核心概念：三个 ID
TiMem 的记忆系统围绕三个 ID 组织：
| ID | 含义 | 示例 |
|---|---|---|
user_id | 用户唯一标识 | "user_001" |
character_id | AI 角色标识（可选） | "assistant" |
session_id | 单次对话唯一标识 | str(uuid.uuid4()) |
每次新对话都生成一个新 session_id，TiMem 会以此为单位做会话摘要，再逐层归纳到每日总结 → 每周总结 → 人物画像。
快速上手：完整示例
import asyncio
import uuid
from timem import AsyncMemory
API_KEY = "你的 API Key"
BASE_URL = "https://api.timem.cloud"
async def main():
memory = AsyncMemory(api_key=API_KEY, base_url=BASE_URL)
user_id = "user_001"
session_id = str(uuid.uuid4()) # 每次新对话生成新 ID
# ① 写入对话记忆
await memory.add(
messages=[
{"role": "user", "content": "我是李明，后端工程师，主要用 Go 和 Python"},
{"role": "assistant", "content": "你好李明！你目前在做什么项目？"},
{"role": "user", "content": "在做一个 AI 客服系统，需要记住用户的历史问题"},
],
user_id=user_id,
session_id=session_id,
)
print("记忆写入完成")
# ② 简单查询（自动从底层精确召回）
results = await memory.search(
query="这个用户用什么编程语言",
user_id=user_id,
limit=3,
)
print("\n简单查询结果:")
for r in results:
print(f" [{r['layer']}层] {r['content']}")
# ③ 复杂查询（自动从高层召回用户画像）
results = await memory.search(
query="这个用户的技术背景和正在做什么",
user_id=user_id,
limit=3,
)
print("\n复杂查询结果:")
for r in results:
print(f" [{r['layer']}层] {r['content']}")
await memory.aclose()
asyncio.run(main())
```
---
## API 速查表
### 写入记忆
```python
await memory.add(
messages=[{"role": "user", "content": "..."}], # 对话消息列表
user_id="user_001", # 必填
session_id="session_xxx", # 必填，每次对话唯一
character_id="assistant", # 可选，AI 角色 ID
)
```
### 检索记忆
```python
results = await memory.search(
query="查询内容",
user_id="user_001",
limit=5, # 返回条数
)
# 返回: [{"content": "...", "layer": 1, "score": 0.95}, ...]
# layer: 1=原始片段, 2=会话摘要, 3=每日总结, 4=每周总结, 5=人物画像
```
### 获取用户画像（L5 层）
```python
results = await memory.search(
query="用户整体画像",
user_id="user_001",
limit=1,
)
# 自动召回 L5 层人物画像
```
### 删除记忆
```python
# 删除某用户所有记忆
await memory.delete_all(user_id="user_001")
# 删除某次会话记忆
await memory.delete_session(user_id="user_001", session_id="session_xxx")
```
---
## 在 AI 对话系统中集成
典型用法：每次对话前先召回记忆，拼入 system prompt。
```python
import asyncio
import uuid
from timem import AsyncMemory
memory = AsyncMemory(api_key="YOUR_KEY", base_url="https://api.timem.cloud")
async def chat(user_id: str, user_message: str, session_id: str) -> str:
# 1. 召回相关记忆
memories = await memory.search(
query=user_message,
user_id=user_id,
limit=5,
)
memory_context = "\n".join([m["content"] for m in memories])
# 2. 构建带记忆的 prompt
system_prompt = f"""你是一个个性化 AI 助手。
关于这个用户，你已知道：
{memory_context}
"""
# 3. 调用 LLM（以 OpenAI 为例）
# response = openai_client.chat(...)
assistant_reply = "这里是 LLM 的回复" # 替换为真实调用
# 4. 将本轮对话写入记忆
await memory.add(
messages=[
{"role": "user", "content": user_message},
{"role": "assistant", "content": assistant_reply},
],
user_id=user_id,
session_id=session_id,
)
return assistant_reply
```
---
## 关键参数建议
| 场景 | limit 建议 | 说明 |
|------|-----------|------|
| 日常对话上下文 | 5-8 | 精准召回，避免 prompt 过长 |
| 用户画像类查询 | 1-3 | 主要需要 L5 层 |
| 多跳推理任务 | 8-10 | 需要更多层级的信息 |
---
## 性能数据
| 基准 | TiMem | 最强对手(MemOS) | 优势 |
|------|-------|----------------|------|
| LoCoMo | **75.30%** | 69.24% | +6.06% |
| LongMemEval-S | **76.88%** | 68.68% | +8.20% |
| Token 召回量 | 减少 **52.20%** | — | 更省钱 |
---
如果你对 AI 记忆技术感兴趣，欢迎访问 TiMem 的 GitHub 仓库：
https://github.com/timem-ai/tiimem
给我们一个 Star，你的支持是我们持续开源的最大动力！
在线体验：https://playground.timem.cloud
技术文档：https://docs.timem.cloud
