liqiang
b119135836
Build latest book artifacts / build (push) Canceled after 0s
dependency resolution / resolve (3.11) (push) Canceled after 0s
dependency resolution / resolve (3.13) (push) Canceled after 0s
deploy-pages / build (push) Canceled after 0s
deploy-pages / deploy (push) Canceled after 0s
i18n consistency check / check (push) Canceled after 0s
provider adoption tests / test (chapter2/context-compression) (push) Canceled after 0s
provider adoption tests / test (chapter2/prompt-injection) (push) Canceled after 0s
provider adoption tests / test (chapter2/system-hint) (push) Canceled after 0s
provider adoption tests / test (chapter3/log-sanitization) (push) Canceled after 0s
web-search-agent tests / test (push) Canceled after 0s
web-search-agent tests / agentbook (push) Canceled after 0s
297 lines
9.1 KiB
Markdown
297 lines
9.1 KiB
Markdown
# Mem0 Agent with Kimi K3 for LOCOMO Benchmark / Mem0 Agent 与 LOCOMO 评测
|
||
|
||
> Companion material for *AI Agents in Depth*, Chapter 3 — Mem0 memory framework + Kimi for long-context multi-session memory (Experiment 3-2 comparison track).
|
||
> 配套《深入理解 AI Agent》第 3 章——Mem0 记忆框架 + Kimi，长上下文多会话记忆（实验 3-2 对照实现之一）。
|
||
|
||
← [Chapter 3 index / 返回第 3 章目录](../README.md)
|
||
|
||
---
|
||
|
||
## English
|
||
|
||
### Overview
|
||
|
||
An agent that combines the **Mem0** memory framework with the **Kimi** language model for LOCOMO-style long-context multi-agent / multi-session tasks:
|
||
|
||
- **Persistent memory** via Mem0 across sessions
|
||
- **Kimi** integration (experiment caps context budget below the model’s full window)
|
||
- **LOCOMO benchmark** scenarios
|
||
- Multi-session and multi-agent collaboration with shared memory
|
||
|
||
### Features
|
||
|
||
**Core:** Mem0 v3 ADD-only extraction and hybrid retrieval; context preservation; metrics (consistency, coherence, latency, memory use); local or cloud memory backend.
|
||
|
||
**LOCOMO scenarios:** collaborative planning; information sharing; multi-step problem solving; negotiation; teaching & learning.
|
||
|
||
### Installation
|
||
|
||
Prerequisites: Python 3.12 with the root `ch3` extra (including Mem0's NLP support for entity/BM25 signals), Kimi API key; optional Mem0 cloud key.
|
||
|
||
```bash
|
||
# From the repository root: use the shared Chapter 3 environment
|
||
uv sync --locked --python 3.12 --extra ch3
|
||
|
||
# Activate it before changing directories:
|
||
# macOS/Linux:
|
||
source .venv/bin/activate
|
||
# Windows PowerShell: .venv\Scripts\Activate.ps1
|
||
# Windows cmd: .venv\Scripts\activate.bat
|
||
|
||
# pip fallback when uv is not installed:
|
||
# python -m pip install -e ".[ch3]"
|
||
|
||
cd chapter3/mem0
|
||
|
||
# Single-project compatibility path, still supported during migration:
|
||
# python -m pip install -r requirements.txt
|
||
|
||
cp env.example .env
|
||
# Edit .env with API keys
|
||
```
|
||
|
||
Required env:
|
||
|
||
- `KIMI_API_KEY`
|
||
- `MODEL_NAME` (default `kimi-k3`) — **raw Moonshot model id** (e.g. `kimi-k3`, `kimi-k2.5`); do **not** use `provider/model` slash form; Mem0 uses OpenAI-compatible provider pointed at Moonshot `base_url` and forwards the string verbatim (`kimi/k3` → “Not found the model”)
|
||
- `MEMORY_BACKEND`: `local` / `cloud`
|
||
- `MAX_TOKENS` (default 128000)
|
||
|
||
### Quick start
|
||
|
||
```bash
|
||
python quickstart.py
|
||
```
|
||
|
||
Shows basic chat with memory, multi-session persistence, multi-agent collaboration.
|
||
|
||
#### Memory pipeline demo (ADD-only extraction + hybrid retrieval)
|
||
|
||
Demonstrates Mem0 v3's append-only history and cross-session recall:
|
||
|
||
```bash
|
||
python main.py --mode demo --user-id demo_user
|
||
```
|
||
|
||
Book example: a user lives in Beijing and later moves to Shanghai. Mem0 preserves both dated facts, while hybrid, time-aware retrieval ranks the current one. Same routine: `memory_pipeline_example()` in `quickstart.py`.
|
||
|
||
#### Direct memory operations CLI
|
||
|
||
```bash
|
||
python main.py --help # Chinese descriptions
|
||
|
||
python main.py --mode memory --op add --text "我住在北京，是一名后端工程师" --user-id u1
|
||
python main.py --mode memory --op search --query "这个用户住在哪里？" --user-id u1
|
||
python main.py --mode memory --op get-all --user-id u1 --output mem.json
|
||
python main.py --mode memory --op history --memory-id <id>
|
||
python main.py --mode memory --op delete --memory-id <id>
|
||
```
|
||
|
||
Flags: `--op {add,search,get-all,history,delete}`, `--text`, `--query`, `--memory-id`, `--user-id`, `--agent-id`, `--model`, `--output`. `--text` may be a raw string or path to a JSON message list.
|
||
|
||
> Demo, memory ops, and chat modes need a working LLM key (`KIMI_API_KEY`) and vector store. Without a key the CLI parses args then reports the missing key—no fabricated memory output.
|
||
|
||
#### Interactive / batch
|
||
|
||
```bash
|
||
python main.py --mode interactive
|
||
# commands: help, memories, metrics, save, load, new, exit
|
||
|
||
python main.py --mode batch --input conversations.json --output results.json
|
||
```
|
||
|
||
Batch input format:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"session_id": "session_001",
|
||
"user_id": "user_001",
|
||
"agent_id": "agent_001",
|
||
"turns": ["First user message", "Second user message"]
|
||
}
|
||
]
|
||
```
|
||
|
||
### LOCOMO benchmark
|
||
|
||
```bash
|
||
python experiment.py --scenarios 10 --output results/
|
||
```
|
||
|
||
Metrics: consistency, coherence, memory retention, response time, context utilization. Results JSON under `results/` with per-scenario and overall metrics.
|
||
|
||
### Architecture
|
||
|
||
- `agent.py`: `Mem0Agent`, `KimiK3Client`, `AgentContext`
|
||
- `config.py`: Kimi / Mem0 / LOCOMO config
|
||
- `experiment.py`: `LOCOMOBenchmark`
|
||
|
||
Mem0 provides append-only extraction, hybrid retrieval, and multi-level (user/agent/session) organization.
|
||
|
||
### Memory backends
|
||
|
||
```python
|
||
# Local Chroma
|
||
config.mem0.backend = "local"
|
||
config.mem0.vector_store_config = {
|
||
"provider": "chroma",
|
||
"config": {"collection_name": "my_collection", "path": "./data/chroma_db"}
|
||
}
|
||
|
||
# Cloud
|
||
config.mem0.backend = "cloud"
|
||
config.mem0.api_key = "your_mem0_api_key"
|
||
```
|
||
|
||
### Troubleshooting
|
||
|
||
1. API key: set valid `KIMI_API_KEY` in `.env`
|
||
2. Local backend: write permission under `./data/`
|
||
3. Cloud: valid `MEM0_API_KEY`
|
||
4. Debug: `export LOG_LEVEL=DEBUG`
|
||
|
||
### Project structure
|
||
|
||
```
|
||
mem0/
|
||
├── agent.py, config.py, experiment.py, main.py, quickstart.py
|
||
├── requirements.txt, env.example, README.md
|
||
```
|
||
|
||
### Limitations
|
||
|
||
Needs network for APIs; memory grows with use; context capped in experiment config; quality depends on model availability.
|
||
|
||
### License / acknowledgments
|
||
|
||
Part of AI Agent Book materials. Mem0 by Mem0 AI; Kimi by Moonshot AI.
|
||
|
||
---
|
||
|
||
## 中文
|
||
|
||
### 概述
|
||
|
||
将 **Mem0** 记忆框架与 **Kimi** 语言模型结合，面向 LOCOMO 风格长上下文、多会话 / 多 Agent 任务：
|
||
|
||
- 跨会话**持久记忆**
|
||
- Kimi 集成（实验中会限制上下文预算）
|
||
- LOCOMO 场景评测
|
||
- 多会话、多 Agent 共享记忆协作
|
||
|
||
### 功能
|
||
|
||
**核心：** Mem0 v3 的 ADD-only 抽取与混合检索；跨会话上下文保持；一致性、连贯性、时延、记忆利用率等指标；本地或云端记忆后端。
|
||
|
||
**LOCOMO 场景：** 协作规划、信息共享、多步解题、谈判、教与学。
|
||
|
||
### 安装
|
||
|
||
Python 3.12 与根目录 `ch3` extra（包含实体 / BM25 信号所需的 Mem0 NLP 支持）、Kimi API Key；可选 Mem0 云端 Key。
|
||
|
||
```bash
|
||
# 在仓库根目录使用统一的第 3 章环境
|
||
uv sync --locked --python 3.12 --extra ch3
|
||
|
||
# 切换目录前先激活环境：
|
||
# macOS/Linux：
|
||
source .venv/bin/activate
|
||
# Windows PowerShell：.venv\Scripts\Activate.ps1
|
||
# Windows cmd：.venv\Scripts\activate.bat
|
||
|
||
# 未安装 uv 时可用 pip 兜底：
|
||
# python -m pip install -e ".[ch3]"
|
||
|
||
cd chapter3/mem0
|
||
|
||
# 迁移期间仍支持单项目兼容路径：
|
||
# python -m pip install -r requirements.txt
|
||
|
||
cp env.example .env
|
||
# 编辑 .env 填入 API Key
|
||
```
|
||
|
||
环境变量：
|
||
|
||
- `KIMI_API_KEY`
|
||
- `MODEL_NAME`（默认 `kimi-k3`）——**原始 Moonshot 模型 id**，不要用 `provider/model` 斜杠形式
|
||
- `MEMORY_BACKEND`：`local` / `cloud`
|
||
- `MAX_TOKENS`（默认 128000）
|
||
|
||
### 快速开始
|
||
|
||
```bash
|
||
python quickstart.py
|
||
```
|
||
|
||
#### 记忆管线演示（仅追加提取 + 混合检索）
|
||
|
||
```bash
|
||
python main.py --mode demo --user-id demo_user
|
||
```
|
||
|
||
书中示例：先说住在北京，后来说搬到上海。Mem0 保留两条带时间的事实，由混合、时间感知检索优先返回当前事实。
|
||
|
||
#### 直接记忆操作 CLI
|
||
|
||
```bash
|
||
python main.py --help
|
||
|
||
python main.py --mode memory --op add --text "我住在北京，是一名后端工程师" --user-id u1
|
||
python main.py --mode memory --op search --query "这个用户住在哪里？" --user-id u1
|
||
python main.py --mode memory --op get-all --user-id u1 --output mem.json
|
||
python main.py --mode memory --op history --memory-id <id>
|
||
python main.py --mode memory --op delete --memory-id <id>
|
||
```
|
||
|
||
无 Key 时 CLI 会解析参数后明确报错，**不会伪造**记忆输出。
|
||
|
||
#### 交互 / 批处理
|
||
|
||
```bash
|
||
python main.py --mode interactive
|
||
python main.py --mode batch --input conversations.json --output results.json
|
||
```
|
||
|
||
### LOCOMO 基准
|
||
|
||
```bash
|
||
python experiment.py --scenarios 10 --output results/
|
||
```
|
||
|
||
指标：一致性、连贯性、记忆保持、响应时间、上下文利用等。
|
||
|
||
### 架构与后端
|
||
|
||
- `agent.py` / `config.py` / `experiment.py`
|
||
- 本地 Chroma 或 Mem0 Cloud（配置见 English 节代码块）
|
||
|
||
### 故障排查
|
||
|
||
检查 `KIMI_API_KEY`、`./data/` 写权限、`MEM0_API_KEY`；`LOG_LEVEL=DEBUG`。
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
mem0/
|
||
├── agent.py, config.py, experiment.py, main.py, quickstart.py
|
||
├── requirements.txt, env.example, README.md
|
||
```
|
||
|
||
### 局限与许可
|
||
|
||
需联网调用 API；记忆随使用增长；实验中上下文有上限。教学材料许可。
|
||
|
||
---
|
||
|
||
## Notes / 说明
|
||
|
||
### OpenRouter 通用回退 / Universal OpenRouter fallback
|
||
|
||
- Primary provider keys unchanged if set.
|
||
- Else `OPENROUTER_API_KEY` routes chat LLM via `https://openrouter.ai/api/v1` with automatic model id mapping; `OPENROUTER_MODEL` forces a specific id.
|
||
- **Note:** Mem0’s embedder still uses OpenAI embeddings (OpenRouter has no embeddings endpoint), so `OPENAI_API_KEY` is still required for store/retrieve. OpenRouter only covers the chat LLM (ADD-only fact extraction and answering).
|
||
|
||
Add `OPENROUTER_API_KEY=...` to `.env` (see `env.example`).
|