ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter3/memobase/README.md

@@ -0,0 +1,249 @@
+# 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`.