# Agent Memory 集成示例

本目录包含 3 个典型集成场景，展示如何将 Agent Memory 作为内部模块使用。

## 场景概览

| 场景 | 文件 | 核心功能 |
|------|------|----------|
| ChatBot 记忆对话 | `01_chatbot_memory.py` | `remember()` + `recall()` + `build_context()` |
| 多 Agent 共享记忆池 | `02_multi_agent.py` | `agent_id` / `team_id` 隔离 + 跨 Agent 读取 |
| 时序知识工作者 | `03_temporal_knowledge.py` | 双时间线 + 快照 + 时间旅行 |

## 快速开始

```bash
# 确保已安装 agent_memory
pip install -e .

# 运行示例（使用临时数据库，不会污染系统）
python -m agent_memory.examples.01_chatbot_memory
python -m agent_memory.examples.02_multi_agent
python -m agent_memory.examples.03_temporal_knowledge
```

## 场景 1：ChatBot with Memory（最简集成）

**核心思路**：在对话循环中，先 `recall` 相关上下文，再 `remember` 对话内容。

```python
from agent_memory import AgentMemory

memory = AgentMemory(db_path=":memory:")

# 用户发消息前，检索相关记忆
results = memory.recall(query="用户偏好")
context = memory.build_context(query="用户偏好")

# 生成回复后，记住对话
memory.remember("用户偏好使用 Python 进行开发", importance="high")
```

**关键 API**：
- `remember(content, importance, topics, nature)` — 写入记忆
- `recall(query, limit)` — 检索记忆（TEMPR 五路并行 + RRF 融合）
- `build_context(query, max_tokens, style)` — 组装上下文文本，直接拼入 prompt
- `feedback(memory_id, useful)` — 反馈优化质量评分

**会话隔离**：通过 `session_id` 参数区分不同对话会话的记忆。

## 场景 2：多 Agent 共享记忆池

**核心思路**：多个 Agent 共享同一个 `AgentMemory` 实例，通过 `agent_id` / `team_id` 实现隔离与共享。

```python
from agent_memory import AgentMemory

# 共享实例，不同 agent_id
memory = AgentMemory(db_path="shared.db", agent_id="researcher", team_id="team_a")

# Agent A 写入
memory.remember("项目使用 React 18 + TypeScript", importance="high")

# Agent B 读取（通过 query_agent_id 控制可见性）
results = memory.recall(query="项目技术栈", query_agent_id="developer")
```

**关键 API**：
- `AgentMemory(agent_id=..., team_id=...)` — 初始化时指定身份
- `recall(query_agent_id=..., team_id=...)` — 带权限过滤的检索
- `store.register_agent(agent_id, agent_name, team_id)` — 注册 Agent
- `store.grant_permission(memory_id, agent_id, granted_by)` — 精细权限控制

**隔离模型**：
- `owner_agent_id` — 记忆所有者
- `visibility` — 可见性（`private` / `team` / `public`）
- `team_id` — 团队隔离

## 场景 3：时序知识工作者

**核心思路**：利用双时间线（valid_from / valid_until）管理随时间变化的事实，用快照实现时间旅行。

```python
from agent_memory import AgentMemory
import time

memory = AgentMemory(db_path=":memory:")

# 记住一个有时效性的事实
memory.remember(
    "项目部署在 AWS us-east-1",
    importance="high",
)

# 创建快照
memory.take_snapshot(label="v1 部署状态")

# 事实变更后更新
# ... 记忆版本化自动保留历史

# 查看差异
diff = memory.diff_memories(from_snapshot=snapshot_id)
```

**关键 API**：
- `take_snapshot(label, description)` — 创建快照
- `list_snapshots()` — 列出所有快照
- `diff_memories(from_ts, to_ts, from_snapshot, to_snapshot)` — 对比差异
- `diff_natural(...)` — 自然语言差异描述
- `blame_memory(memory_id)` — 追溯记忆来源
- `store.update_memory(memory_id, new_content, change_reason)` — 版本化更新
- `store.get_memory_versions(memory_id)` — 获取版本历史

## 依赖说明

| 组件 | 必需依赖 | 说明 |
|------|----------|------|
| 基础写入/检索 | 无 | SQLite FTS5 全文搜索 |
| 语义搜索 | `sentence-transformers`, `sqlite-vec` | 向量检索，缺失时降级为关键词搜索 |
| 中文分词 | `jieba` | FTS5 中文分词，缺失时使用字符级分词 |
| 重排序 | `FlagEmbedding` | 交叉编码器，缺失时降级为分数排序 |

所有示例均可在无可选依赖的情况下运行（功能降级但不会报错）。
