内容
# 多智能体记忆与状态波
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://statewave.ai)
三个分析智能体同时读取冲突的源文档。观察状态波如何检测矛盾，取代过时的事实，并自动提供正确答案，无需您编写任何合并逻辑。
---
## 目录
- [多智能体记忆与状态波](#多智能体记忆与状态波)
- [目录](#目录)
- [什么是状态波](#什么是状态波)
- [本演示解决的问题](#本演示解决的问题)
- [运行演示时会发生什么](#运行演示时会发生什么)
- [工作原理](#工作原理)
- [关键概念](#关键概念)
- [架构](#架构)
- [先决条件](#先决条件)
- [本地设置和运行](#本地设置和运行)
- [选项 A：Docker Compose（推荐）](#选项-a-docker-compose推荐)
- [选项 B：直接运行 Python](#选项-b直接运行-python)
- [用法](#用法)
- [源文档](#源文档)
- [环境变量](#环境变量)
- [使用的状态波 API 端点](#使用的状态波-api端点)
- [审计检查](#审计检查)
- [开发者参考](#开发者参考)
- [项目结构](#项目结构)
- [SSE 事件类型](#sse事件类型)
- [许可证](#许可证)
---
## 什么是状态波
状态波是一个开源的 AI 智能体内存运行时。您为它提供原始事件（集），它将它们编译成类型化的、冲突解决的内存；您的智能体查询它以获取排名的、 token-bounded 的上下文，直接用于提示。无需 GPU，无需向量数据库，无需应用级合并逻辑。
循环：**摄入 → 编译 → 使用**
完整文档请访问 [statewave.ai](https://statewave.ai)。
---
## 本演示解决的问题
在典型的多智能体管道中，两个智能体可以读取不同新鲜度的源并提交相互矛盾的事实到同一个共享存储。通常的选项是：扩大上下文窗口，将所有内容发送到 LLM 并希望它能解决，或者编写自定义合并逻辑，这很脆弱且难以审计。
状态波是第三个选项。当关于同一个实体的两个记忆超过单词重叠相似性阈值时，编译器会自动取代旧的记忆，并记录具有完整溯源的决策。您的智能体查询上下文，只会看到获胜者。
---
## 运行演示时会发生什么
您点击 **运行管道**。三个智能体：彭博社、技术观察和盈利报告，同时开始。每个智能体读取其源文档，提取结构化发现，并向共享的状态波主题 `market-intel` 提交一个集。随着每个智能体编译，其记忆实时出现在浏览器面板中。
然后技术观察的编译完成。彭博社 Stripe 条目变为红色并被划掉。状态栏显示 **"1 个冲突已解决"**。您没有编写任何代码来实现这一点。
> **关键时刻：** 彭博社提交了 Stripe 旧费率 3.5% + 35¢。技术观察提交了逆转后的费率 2.9% + 30¢。状态波的编译器测量了两个记忆之间的 Jaccard 单词重叠 ≥ 0.6，将彭博社标记为技术观察所取代，并记录了审计轨迹。当您询问 _"Stripe 当前的处理费是多少？"_ 时，合成智能体查询上下文并得到 2.9%，它永远不会看到过时的数字。
---
## 工作原理
每个智能体都遵循相同的三个步骤循环：
1. **摄入。** 智能体读取其源文档，使用 LLM 提取结构化发现，并调用 `POST /v1/episodes` 将原始的、内容哈希的集附加到共享主题。集是仅追加的；不会覆盖任何内容。
2. **编译。** 智能体调用 `POST /v1/memories/compile`。状态波的启发式编译器从集日志中提取类型化的记忆并运行冲突检测。如果关于同一事实的两个记忆共享足够的单词重叠（Jaccard ≥ 0.6），则较旧的记忆被标记为已被更新的记忆取代，并带有到两个源集的溯源链接。
3. **使用。** 合成智能体调用 `POST /v1/context`，并带有主题 ID 和用户问题。状态波返回一个排名的、token-bounded 的 `assembled_context`，其中只包含活跃的（非被取代的）记忆。智能体将此包直接传递给 LLM，并将答案流式传输回浏览器。
### 关键概念
| 概念 | 含义 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **集** | 仅追加的原始事件：主题 ID + 源 + 类型 + 有效载荷。不可变的事实来源。 |
| **记忆** | 提取的、类型化的、编译的摘要。可以追溯到源集，带有置信度和溯源。 |
| **编译** | 集 → 记忆的幂等转换。启发式（本地）或 LLM 编译器。无需 GPU。 |
| **冲突解决** | 当关于同一事实的两个记忆超过相似性阈值时，较旧的记忆自动被更新的记忆取代。确定性。 |
| **上下文 API** | `POST /v1/context`：用于提示的排名、token-bounded 的上下文包。相同的查询，相同的字节。 |
| **主题** | 您跟踪的任何实体：用户、智能体、账户、仓库。这里：每个管道运行一个主题（`market-intel`）。 |
---
## 架构
三个并发智能体共享一个状态波主题。FastAPI 服务器协调智能体并通过 SSE 将实时更新推送到浏览器。状态波作为单独的本地服务运行。
<picture>
<img alt="多智能体记忆架构" src="docs/images/architecture.jpeg">
</picture>
完整多智能体运行期间的演示界面：
---
## 先决条件
- **Docker** 和 **Docker Compose**：选项 A（推荐）所需
- **LLM API 密钥**：来自您的 Groq 账户（默认）或任何受 LiteLLM 支持的提供商（请相应地设置 `LLM_MODEL`）
- **Python 3.11+**：仅选项 B（不使用 Docker）需要
- **Node.js 20+**：可选，仅用于审计检查
---
## 本地设置和运行
### 选项 A：Docker Compose（推荐）
一条命令即可启动状态波后端、其数据库和演示应用程序。
**1. 克隆此仓库**
```bash
git clone https://github.com/smaramwbc/statewave-multi-agent-memory
cd statewave-multi-agent-memory
```
**2. 配置环境**
```bash
cp .env.example .env
```
打开 `.env` 并设置 `LLM_API_KEY` 为您的 LLM 提供商 API 密钥。
**3. 启动所有内容**
```bash
docker compose up
```
打开 [http://localhost:8000](http://localhost:8000) 并点击 **运行管道**。
---
### 选项 B：直接运行 Python
如果您更喜欢在容器外运行演示服务器，但仍通过 Docker 运行状态波，请使用此选项。
**1. 克隆此仓库**
```bash
git clone https://github.com/smaramwbc/statewave-multi-agent-memory
cd statewave-multi-agent-memory
```
**2. 安装 Python 依赖项**
```bash
pip install -r requirements.txt
```
**3. 配置环境**
```bash
cp .env.example .env
```
打开 `.env` 并设置 `LLM_API_KEY`。如果您的状态波实例不在默认的 `http://localhost:8100`，请设置 `STATEWAVE_URL`。
**4. 启动状态波后端**
```bash
docker compose up -d api db
```
**5. 启动此演示**
```bash
python server.py
```
打开 [http://localhost:8000](http://localhost:8000) 并点击 **运行管道**。
---
## 用法
1. 点击 **运行管道**。三个智能体面板出现并开始实时记录。
2. 在每个智能体提交其发现时，观察记忆面板。当 TechCrunch 的记忆出现时，彭博社的 Stripe 条目立即被红色划掉。
3. 编译完成后，状态栏更新为 **"1 个冲突已解决"**。
4. 在聊天输入中输入一个问题，例如 _"Stripe 当前的处理费是多少？"_，合成智能体使用仅活跃的记忆回答。
5. 点击 **重置** 以清除主题并再次运行。
---
## 源文档
| 文件 | Stripe 事实 | 角色 |
| ------------------------- | ----------------------------------- | ------------------------------------------------ |
| `sources/bloomberg.json` | 3.5% + 35¢（过时，逆转前） | 首先提交；将被取代的事实 |
| `sources/techcrunch.json` | 2.9% + 30¢（正确，逆转后） | 与彭博社矛盾；触发取代 |
| `sources/earnings.json` | 2.9% + 30¢ + Square 亏损 | 证实技术观察；贡献 Square 数据 |
彭博社文档故意包含逆转前的数字。冲突是合成的，但在现实管道中，当智能体从不同新鲜度的源拉取时，结构与之相同。
---
## 环境变量
| 变量 | 必需 | 默认 | 描述 |
| ------------------- | -------- | ----------------------- | ----------------------------------------------------------------------------------------- |
| `LLM_API_KEY` | 是 | — | 您的 LLM 提供商的 API 密钥 |
| `LLM_MODEL` | 否 | `groq/llama-3.3-70b-versatile` | LiteLLM 模型字符串 — 更改为使用不同的提供商（例如 `openai/gpt-4o`） |
| `STATEWAVE_URL` | 否 | `http://localhost:8100` | 状态波服务器基准 URL |
| `STATEWAVE_API_KEY` | 否 | — | 如果您的状态波实例启用了身份验证，请设置 |
| `APP_SECRET` | 否 | — | 设置后，所有演示 API 端点都需要 `X-API-Key: <value>`。本地开发时请保持未设置。 |
---
## 使用的状态波 API 端点
| 端点 | 目的 |
| --------------------------- | ------------------------------------------------------ |
| `POST /v1/episodes` | 从智能体摄入原始集 |
| `POST /v1/memories/compile` | 触发冲突检测和记忆提取 |
| `POST /v1/context` | 为查询检索排名、token-bounded 的上下文 |
| `GET /v1/timeline` | 为检查器获取完整的集 + 记忆时间线 |
| `DELETE /v1/subjects/{id}` | 重置主题之间的管道运行 |
---
## 审计检查
`inspector/` 目录包含一个 TypeScript 工具，用于打印任何主题的完整审计轨迹：按时间顺序排列的集、派生的记忆和具有源引用和 Jaccard 相似性分数的取代记录。
```bash
cd inspector
npm install
npx tsx src/index.ts --subject-id market-intel
```
---
## 开发者参考
### 项目结构
```
statewave-multi-agent-memory/
├── agents/
│ ├── analyst.py # 智能体逻辑：摄入 → 编译 → 差异
│ └── base.py # AsyncStatewaveClient 包装器
├── sources/
│ ├── bloomberg.json # 过时的 Stripe 定价（3.5%）— 将被取代
│ ├── techcrunch.json # 更正的 Stripe 定价（2.9%）— 取代彭博社
│ └── earnings.json # 证实 TechCrunch，增加 Square 数据
├── inspector/
│ └── src/index.ts # 审计轨迹：集、记忆、取代
├── static/
│ └── index.html # 浏览器 UI（SSE 驱动，零构建步骤）
├── server.py # FastAPI 应用程序：/run /ask /events /memories
├── Dockerfile # 将演示服务器构建为容器镜像
├── docker-compose.yml # 一键启动 db + 状态波 API + 演示
├── requirements.txt
└── .env.example
```
### SSE 事件类型
浏览器接收单个 `/events` 流。事件类型：
| 事件 | 有效载荷 | 目的 |
| ----------------- | ------------------- | --------------------------------------------- |
| `agent_log` | `{ agent, msg }` | 将日志行追加到命名智能体面板 |
| `memory_update` | `{ agent, diff }` | 将 DOM 差异应用于记忆面板 |
| `agents_done` | `{ supersessions }` | 启用聊天输入；更新状态栏计数 |
| `synthesis_token` | `{ token }` | 将一个 token 流式传输到活动聊天气泡 |
| `synthesis_done` | — | 完成聊天气泡 |
---
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器