TiMem API 接入全攻略：5分钟给 AI 应用加上长期记忆（附完整代码）

TiMem 是目前长对话记忆准确率最高的开源框架（LoCoMo 75.30%，LongMemEval-S 76.88%），本文从注册到第一个请求，完整接入教程。

一、前置准备

注册并获取 API Key

1. 访问 console.timem.cloud 注册账号
2. 2. 创建项目，生成 API Key

安装 SDK

pip install timem

二、核心概念：三个 ID

每次新对话都生成一个新 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"  [L{r['layer']}] {r['content']}")
    # ③ 复杂查询（自动从高层召回用户画像）
        results = await memory.search(
                query="这个用户的技术背景和正在做什么",
                        user_id=user_id,
                                limit=3,
                                    )
                                        print("\n复杂查询结果:")
                                            for r in results:
                                                    print(f"  [L{r['layer']}] {r['content']}")
    await memory.aclose()
asyncio.run(main())

四、API 速查表

写入记忆

await memory.add(
    messages=[{"role": "user", "content": "..."}],
        user_id="user_001",
            session_id="session_xxx",    # 每次对话唯一
                character_id="assistant",    # 可选
                )
                ```
### 检索记忆

```python
results = await memory.search(
    query="查询内容",
        user_id="user_001",
            limit=5,
            )
            # 返回: [{"content": "...", "layer": 1, "score": 0.95}, ...]
            # layer: 1=原始片段, 2=会话摘要, 3=每日总结, 4=每周总结, 5=人物画像
            ```
### 删除记忆

```python
await memory.delete_all(user_id="user_001")
await memory.delete_session(user_id="user_001", session_id="session_xxx")

五、集成到对话系统

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（伪代码）
        assistant_reply = call_llm(system_prompt, user_message)
    # 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
                                                                        ```
---

## 六、性能数据

| 基准 | TiMem | 最强对手(MemOS) | 优势 |
|------|-------|----------------|------|
| LoCoMo | **75.30%** | 69.24% | +6.06% |
| LongMemEval-S | **76.88%** | 68.68% | +8.20% |
| Token 召回量 | 减少 **52.20%** | — | 更省钱 |

在单跳问答、时序推理、多跳推理所有子任务中均达到 SOTA。

---

如果你对 AI 记忆技术感兴趣，欢迎访问 TiMem 的 GitHub 仓库：
https://github.com/timem-ai/tiimem

给我们一个 Star，你的支持是我们持续开源的最大动力！

在线体验：https://playground.timem.cloud
技术文档：https://docs.timem.cloud