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
250 lines
9.4 KiB
Markdown
250 lines
9.4 KiB
Markdown
# Memobase Agent / Memobase Agent（Profile + Event 与手写记忆对照）
|
||
|
||
> Companion material for *AI Agents in Depth*, Chapter 3 — real Memobase SDK demo **and** a Memobase-inspired hand-rolled memory agent (Experiment 3-2 track).
|
||
> 配套《深入理解 AI Agent》第 3 章——真实 Memobase SDK 演示 **与** Memobase 风格自研记忆 Agent（实验 3-2 对照）。
|
||
|
||
← [Chapter 3 index / 返回第 3 章目录](../README.md)
|
||
|
||
---
|
||
|
||
## English
|
||
|
||
### Two tracks in this folder — don’t confuse them
|
||
|
||
1. **Real Memobase framework demo** (`profile_demo.py`) — uses the actual open-source Memobase SDK (`pip install memobase`, package `memobase>=0.0.27`) against a **running Memobase server**. Canonical demo of Memobase’s *Profile* (structured user attributes) + *Event Memory* (timeline). See [Memobase Profile + Event Demo](#memobase-profile--event-demo-real-sdk).
|
||
2. **Hand-rolled memory agent** (`agent.py` / `main.py`) — self-contained *Memobase-inspired* `MemoryStore` (episodic / semantic / procedural / working, pickle-persisted) calling Kimi directly. **No Memobase server**—only `KIMI_API_KEY`. The `--mode` commands (interactive / benchmark / demo / task) drive this agent.
|
||
|
||
### Features (hand-rolled agent)
|
||
|
||
**Memory types:** episodic (task experiences), semantic (facts), procedural (patterns), working (short-term context).
|
||
|
||
**Operations:** compression when over threshold; consolidation; importance-based decay; clustering; relevance/recency retrieval.
|
||
|
||
**Model:** Kimi K3 integration (tool use, multi-step reasoning, long context).
|
||
|
||
**LOCOMO-style categories:** multi-turn reasoning, long-context Q&A, task planning, knowledge integration, tool usage.
|
||
|
||
### Installation
|
||
|
||
```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/memobase
|
||
|
||
# Single-project compatibility path, still supported during migration:
|
||
# python -m pip install -r requirements.txt
|
||
|
||
cp env.example .env
|
||
# Set KIMI_API_KEY, or use LLM_PROVIDER=dashscope/qwen/bailian with DASHSCOPE_API_KEY
|
||
```
|
||
|
||
Edit `config.py` for model, memory thresholds, benchmark, logging.
|
||
|
||
### Usage (hand-rolled agent)
|
||
|
||
#### Interactive
|
||
|
||
```bash
|
||
python main.py --mode interactive
|
||
```
|
||
|
||
Commands: `/help`, `/memory`, `/clear`, `/reset`, `/learn`, `/exit`.
|
||
|
||
#### Benchmark
|
||
|
||
```bash
|
||
python main.py --mode benchmark
|
||
python main.py --mode benchmark --category multi_turn_reasoning
|
||
python main.py --mode benchmark --num-tasks 5
|
||
```
|
||
|
||
#### Demo / single task
|
||
|
||
```bash
|
||
python main.py --mode demo
|
||
python main.py --mode task --task "Plan a 7-day trip to Japan with a $3000 budget"
|
||
```
|
||
|
||
Extra: `--api-key KEY`, `--no-memory`, `--verbose`.
|
||
|
||
### Memobase Profile + Event Demo (real SDK)
|
||
|
||
`profile_demo.py` uses the **real** Memobase SDK: **Profile** (topic → sub-topic → content, e.g. `basic_info→城市`, `work→职位`) and **Event Memory** (timeline for “when did we discuss budget?”). Pipeline: `insert` → `flush` → `profile` / `event` / `context`.
|
||
|
||
#### Prerequisites
|
||
|
||
Memobase extracts **server-side**; you need a reachable service:
|
||
|
||
- **Self-hosted**: [memodb-io/memobase](https://github.com/memodb-io/memobase) (docker compose). Default `http://localhost:8019`, token `secret`. Extraction model is in the **server’s** `.env` / `config.yaml` (`--model` on the client is informational only).
|
||
- **Cloud**: `project_url` + `api_key` from https://www.memobase.ai
|
||
|
||
Client: `--project-url` / `--api-key` or `MEMOBASE_PROJECT_URL` / `MEMOBASE_API_KEY` (see `env.example`).
|
||
|
||
#### Running
|
||
|
||
```bash
|
||
# From the repository root, after installing and activating the shared `ch3` environment above:
|
||
cd chapter3/memobase
|
||
|
||
# Single-project compatibility path, still supported during migration:
|
||
# python -m pip install -r requirements.txt
|
||
|
||
python profile_demo.py
|
||
python profile_demo.py --dry-run
|
||
python profile_demo.py --op profile
|
||
python profile_demo.py --op event
|
||
python profile_demo.py --op context
|
||
python profile_demo.py --input chat.json --output result.json
|
||
```
|
||
|
||
If no server is reachable, the demo exits with an actionable message (try `--dry-run` or set `--project-url`)—it does **not** invent memory output.
|
||
|
||
### Architecture (hand-rolled)
|
||
|
||
- **MemoryStore** (`agent.py`): pickle persistence, compression, clustering, decay, retrieval
|
||
- **MemobaseAgent** (`agent.py`): message processing with memory context, learning, metrics
|
||
- **LOCOMOBenchmark** (`locomo_benchmark.py`): tasks, scoring, persistence
|
||
|
||
### Memory strategies
|
||
|
||
**Compression:** sort by importance/recency; keep important; cluster low-importance into summaries.
|
||
**Consolidation:** decay; drop very low importance; extract patterns → procedural.
|
||
**Retrieval:** content search + recent episodic + procedural → format into context.
|
||
|
||
### Results / development
|
||
|
||
Benchmark outputs under `benchmark_results/`. Extend tools / memory types in `config.py` / `locomo_benchmark.py` as needed.
|
||
|
||
### Troubleshooting
|
||
|
||
1. API key: `KIMI_API_KEY` in `.env`, or `DASHSCOPE_API_KEY` with `LLM_PROVIDER=dashscope`
|
||
2. Memory overflow: lower `MAX_MEMORY_ENTRIES`, more aggressive compression, manual consolidation
|
||
3. Slow: reduce `MODEL_MAX_TOKENS`, enable cache, category-specific benchmarks
|
||
|
||
### License / acknowledgments
|
||
|
||
MIT-style educational use. Kimi by Moonshot AI; Memobase concepts; LOCOMO-inspired design.
|
||
|
||
---
|
||
|
||
## 中文
|
||
|
||
### 本目录两条线——不要搞混
|
||
|
||
1. **真实 Memobase 框架演示**（`profile_demo.py`）——官方开源 SDK（`memobase>=0.0.27`）对接**正在运行的 Memobase 服务**，展示书中的 *Profile*（结构化用户属性）+ *Event Memory*（时间线）。见下文 Profile + Event 演示。
|
||
2. **手写记忆 Agent**（`agent.py` / `main.py`）——自包含、受 Memobase 启发的 `MemoryStore`（情景 / 语义 / 程序 / 工作记忆，pickle 持久化），直接调 Kimi。**不需要 Memobase 服务**，只要 `KIMI_API_KEY`。`--mode`（interactive / benchmark / demo / task）驱动的是这条线。
|
||
|
||
### 手写 Agent 功能
|
||
|
||
**记忆类型：** 情景、语义、程序、工作记忆。
|
||
**操作：** 超阈值压缩、巩固、重要性衰减、聚类、相关度/近因检索。
|
||
**模型：** Kimi K3。
|
||
**评测类别：** 多轮推理、长上下文问答、任务规划、知识整合、工具使用。
|
||
|
||
### 安装
|
||
|
||
```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/memobase
|
||
|
||
# 迁移期间仍支持单项目兼容路径：
|
||
# python -m pip install -r requirements.txt
|
||
|
||
cp env.example .env
|
||
# 手写 Agent 可填写 KIMI_API_KEY；也可用 LLM_PROVIDER=dashscope 与 DASHSCOPE_API_KEY
|
||
```
|
||
|
||
在 `config.py` 中调整模型、记忆阈值、基准与日志。
|
||
|
||
### 用法（手写 Agent）
|
||
|
||
```bash
|
||
python main.py --mode interactive
|
||
# /help /memory /clear /reset /learn /exit
|
||
|
||
python main.py --mode benchmark
|
||
python main.py --mode benchmark --category multi_turn_reasoning
|
||
python main.py --mode benchmark --num-tasks 5
|
||
|
||
python main.py --mode demo
|
||
python main.py --mode task --task "Plan a 7-day trip to Japan with a $3000 budget"
|
||
```
|
||
|
||
额外：`--api-key`、`--no-memory`、`--verbose`。
|
||
|
||
### Memobase Profile + Event 演示（真实 SDK）
|
||
|
||
`profile_demo.py` 展示 **Profile**（topic → sub-topic → content）与 **Event Memory**（时间线）。流水线：`insert` → `flush` → `profile` / `event` / `context`。
|
||
|
||
#### 前置
|
||
|
||
抽取在**服务端**完成，需要可访问的 Memobase：
|
||
|
||
- **自托管**：[memodb-io/memobase](https://github.com/memodb-io/memobase)（docker compose）。默认 `http://localhost:8019`，token `secret`。抽取模型在**服务端**配置。
|
||
- **云端**：https://www.memobase.ai 的 `project_url` + `api_key`
|
||
|
||
客户端：`--project-url` / `--api-key` 或 `MEMOBASE_PROJECT_URL` / `MEMOBASE_API_KEY`。
|
||
|
||
#### 运行
|
||
|
||
```bash
|
||
# 在上方安装并激活统一 `ch3` 环境后，从仓库根目录进入本项目：
|
||
cd chapter3/memobase
|
||
|
||
# 迁移期间仍支持单项目兼容路径：
|
||
# python -m pip install -r requirements.txt
|
||
|
||
python profile_demo.py
|
||
python profile_demo.py --dry-run
|
||
python profile_demo.py --op profile
|
||
python profile_demo.py --op event
|
||
python profile_demo.py --op context
|
||
python profile_demo.py --input chat.json --output result.json
|
||
```
|
||
|
||
连不上服务时会给出可操作提示（`--dry-run` 或配置 URL），**不会捏造**记忆结果。
|
||
|
||
### 架构（手写）
|
||
|
||
- **MemoryStore** / **MemobaseAgent**（`agent.py`）
|
||
- **LOCOMOBenchmark**（`locomo_benchmark.py`）
|
||
|
||
压缩 / 巩固 / 检索策略与 English 节相同。
|
||
|
||
### 结果与排错
|
||
|
||
结果目录 `benchmark_results/`。常见问题：API Key、记忆溢出（调阈值/压缩）、性能（降 `MODEL_MAX_TOKENS`）。
|
||
|
||
### 许可
|
||
|
||
教学用途；致谢 Moonshot / Memobase / LOCOMO 相关设计。
|
||
|
||
---
|
||
|
||
## Notes / 说明
|
||
|
||
### OpenRouter 通用回退 / Universal OpenRouter fallback
|
||
|
||
If primary keys are absent and `OPENROUTER_API_KEY` is set, chat LLM routes through OpenRouter with automatic model mapping; `OPENROUTER_MODEL` forces an id. See `env.example`.
|