# Agent-Memory-Runtime

**Repository Path**: bai_entj_a/agent-memory-runtime

## Basic Information

- **Project Name**: Agent-Memory-Runtime
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Memory Runtime

本项目是一个**多引擎 AI Agent 记忆平台**，将四个主流开源记忆引擎——**Graphiti**、**M-Flow**、**LightRAG**、**Mem0**——统一封装在一套 FastAPI 服务和命令行工具（CLI）之后，对外提供一致的记忆写入、检索、图谱检查接口。

> **什么是"记忆引擎"？**
> AI Agent 在多轮对话中需要记住用户说过的话、发生过的事。不同引擎用不同方式存储这些信息（知识图谱、向量库、混合索引等），各有优劣。本项目让你可以用同一套 API 切换和对比它们。

---

## 项目结构

```
Agent-Memory-Runtime/
├── memory_runtime/          ← 核心代码，全部业务逻辑在这里
│   ├── core/                ← 公共基础：LLM配置、数据模型、错误类型
│   ├── engines/             ← 四个引擎各自的目录（adapter + router + config）
│   │   ├── graphiti/
│   │   ├── mflow/
│   │   ├── lightrag/
│   │   └── mem0/
│   ├── api/                 ← FastAPI 应用入口，把所有引擎的路由注册进来
│   └── cli/                 ← 命令行工具，可以不启动服务器直接调用引擎
├── benchmarks/              ← 评测套件（LoCoMo、LongMemEval 两个基准）
├── deploy/                  ← docker-compose.yml，一键启动所需数据库
├── tests/
│   ├── unit/                ← 单元测试（不需要真实数据库，全部用 mock）
│   └── integration/         ← 集成测试（需要真实 Neo4j + Qdrant）
├── .env.example             ← 环境变量模板，复制后填写自己的 key
└── pyproject.toml           ← 项目依赖声明（uv/pip 读取这个文件安装包）
```

所有引擎的 HTTP 接口都挂载在 `/v1/engines/{引擎名}/...` 下，例如：

- Graphiti：`/v1/engines/graphiti/graphs/...`
- Mem0：`/v1/engines/mem0/memories/...`

完整接口表见 `任务说明.md`，或启动服务后访问 Swagger 文档（见下方）。

---

## 快速开始

### 第一步：启动依赖数据库

本项目需要两个数据库服务在本地运行：

| 服务             | 用途                                  | 默认地址                  |
| ---------------- | ------------------------------------- | ------------------------- |
| **Neo4j**  | 存储知识图谱（Graphiti、M-Flow 使用） | `bolt://localhost:7687` |
| **Qdrant** | 存储向量索引（LightRAG、Mem0 使用）   | `http://localhost:6333` |

最简单的方式是用项目自带的 Docker Compose 一键启动：

```bash
# 需要先安装 Docker Desktop，然后运行：
docker compose -f deploy/docker-compose.yml up -d
```

M-Flow 会在启动时显式选择 Neo4j graph provider，并复用 `NEO4J_URI`、
`NEO4J_USER`、`NEO4J_PASSWORD`。其 Neo4j 写入依赖 APOC，项目自带的
Compose 已启用该插件。原 Kùzu 文件不会自动迁移到 Neo4j。

> 没有安装 Docker？可以去 [docker.com](https://www.docker.com/products/docker-desktop/) 下载 Docker Desktop，安装后重启电脑再试。

### 第二步：配置环境变量

```bash
# 把模板文件复制一份，重命名为 .env
cp .env.example .env
```

然后用任意文本编辑器打开 `.env`，至少填写：

- `OPENAI_API_KEY=sk-...`（调用 LLM 提取实体关系时需要）
- Neo4j 和 Qdrant 的地址（如果你用上面的 Docker Compose 启动，默认值无需修改）

### 第三步：安装依赖并启动服务

> 本项目使用 `uv` 作为包管理器（比 pip 快很多）。
> 如果没有安装 uv，先运行：`pip install uv`

```bash
# 安装所有依赖（读取 pyproject.toml）
uv sync

# 启动 API 服务器，--reload 表示修改代码后自动重启，开发时很方便
uv run uvicorn memory_runtime.api.app:app --port 8000 --reload
```

服务启动后，打开浏览器访问 **http://localhost:8000/docs**，可以看到所有接口的交互式文档（Swagger UI），直接在网页上发请求测试，不需要写代码。

---

## 冒烟测试（确认服务跑通）

> **什么是冒烟测试？** 就是最基本的"点火测试"——确认服务能正常响应，不深究细节。
> 下面用 `curl` 命令（终端里的 HTTP 客户端）来发请求。

### Graphiti 引擎

```bash
# 先把服务地址存成变量，方便后面复用
BASE=http://localhost:8000/v1/engines/graphiti

# 1. 创建一个名为 "demo" 的图谱
curl -sX POST $BASE/graphs -H 'Content-Type: application/json' -d '{"name":"demo"}'

# 2. 初始化索引（首次使用必须执行一次，幂等的，多次执行没问题）
curl -sX POST $BASE/graphs/demo/ready

# 3. 写入一条记忆（episode）
curl -sX POST $BASE/graphs/demo/episodes -H 'Content-Type: application/json' \
  -d '{"name":"t1","episode_body":"Alice prefers Rust","source_description":"test","reference_time":"2026-01-01T00:00:00Z"}'

# 4. 搜索（写入后引擎会异步提取实体，可能需要等几秒再搜）
curl -sX POST $BASE/graphs/demo/search -H 'Content-Type: application/json' \
  -d '{"query":"language preference"}'

# 5. 导出整个图谱
curl -s $BASE/graphs/demo/export
```

### Mem0 引擎

```bash
BASE=http://localhost:8000/v1/engines/mem0

# 写入一条记忆，指定用户 ID 为 "alice"
curl -sX POST $BASE/memories -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"I prefer Rust"}],"user_id":"alice"}'

# 搜索 alice 的记忆
curl -sX POST $BASE/memories/search -H 'Content-Type: application/json' \
  -d '{"query":"language preference","user_id":"alice"}'
```

---

## 运行测试

```bash
# 运行单元测试（不需要启动数据库，全部用 mock 模拟）
uv run pytest tests/unit/ -v

# 同时生成覆盖率报告（看哪些代码没被测试覆盖到）
uv run pytest tests/unit/ --cov=memory_runtime --cov-report=term-missing
```

> **单元测试 vs 集成测试**
>
> - 单元测试：用假数据模拟（mock）所有外部依赖，速度快，随时可跑。
> - 集成测试（`tests/integration/`）：需要真实的 Neo4j + Qdrant 在线，测试真实的读写流程。

---

## 可选扩展包

基础 `uv sync` 只安装核心依赖，部分引擎和工具需要额外安装：

```bash
uv sync --extra lightrag    # 安装 LightRAG 引擎所需的 lightrag-hku 包
uv sync --extra mem0        # 安装 Mem0 引擎所需的 mem0ai 包
uv sync --extra benchmark   # 安装评测所需的 rouge-score 和 nltk 包

# M-Flow 目前处于实验阶段，需要从源码安装（把 <org> 替换成实际仓库地址）：
uv pip install "git+https://github.com/<org>/m-flow.git@main"
```

---

## 运行基准评测

评测需要先安装 benchmark 扩展包（见上方），并准备好对应的数据集文件。

```bash
# LoCoMo 评测（用 Graphiti 引擎）
uv run python -m benchmarks.locomo.run_locomo \
  --engine graphiti \
  --base-url http://localhost:8000 \
  --data path/to/locomo.json \
  --output results_locomo.json

# LongMemEval 评测（用 Mem0 引擎，需要 OPENAI_API_KEY 用于 LLM 裁判）
uv run python -m benchmarks.longmemeval.run_longmemeval \
  --engine mem0 \
  --base-url http://localhost:8000 \
  --data path/to/longmemeval.json \
  --output results_lme.json
```

评测结果会保存为 JSON 文件，包含各类别的 F1 分数或准确率。详见 `benchmarks/README.md`。


neo4j：Entity、Episode、Facet、FacetPoint、EntityType、MemorySpace、ContentFragment、TextDocument

MATCH (n)
RETURN n
LIMIT 100;

MATCH (n:Episode)
RETURN n
ORDER BY n.created_at DESC;

MATCH (n)
UNWIND labels(n) AS label
RETURN label, count(*) AS count
ORDER BY count DESC;


MATCH p=(a)-[r]->(b)
RETURN p
LIMIT 100;


MATCH (n)
WHERE n.dataset_id = "你的 dataset_id"
RETURN n;