Vayl

本地服务

vayl.gitbook.io记忆与知识21 周前更新

代码仓库访问官网

关于 Vayl

Vayl 是供 AI Agent 使用的记忆层，会协调变化中的事实，而非将所有旧值都视为当前信息。它保留审计历史，并可要求人工批准敏感变更；默认使用本地 SQLite。

主要功能

01协调事实更新与撤回
02通过审计链保留历史
03为指定变更设置审批队列
04行动前检查争议或过时事实
05默认使用 SQLite；团队可用 Postgres

适用场景

01维护最新的客户账户状态
02要求确认药物信息变更
03在 Agent 执行动作前核查事实

MCP 相关

Vayl 作为 MCP 服务运行，MCP 客户端可连接并调用记忆工具。团队共享记忆可通过 MCP 或 REST 调用 vayl-server。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "ac12644-vayl": {
      "command": "uvx",
      "args": [
        "vayl-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VAYL_DB": "<VAYL_DB>"
      }
    }
  }
}

启动命令uvx vayl-mcp

需要配置的环境变量

OPENAI_API_KEY密钥OpenAI key for extraction and embeddings. Leave unset to use a local Ollama model.

VAYL_DBAbsolute path of the SQLite memory database.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypivayl-mcp0.10.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填
text	string	是
run_id	string	否
source	string	否
user_id	string	否
agent_id	string	否
metadata	any	否

详细介绍

Vayl

面向 AI Agent 的事实调和记忆层。

当事实发生变化时，大多数 Agent 记忆会保留两个版本，让模型猜哪个才是当前版本。Vayl 会替换旧值并将其保留在历史记录中，还能暂存高风险变更，等待人员审批。它在本地通过 SQLite 运行，并兼容任何 MCP 客户端：Claude Code、Cursor、Claude Desktop 或你自己的 Agent。

一个虚构患者的真实运行示例：记录华法林后将其替换为阿哌沙班。变更会暂存在 pending_changes 中，直到临床医生确认。随后查询会回答当前使用阿哌沙班、之前使用华法林，并因记录了青霉素过敏而拒绝使用阿莫西林。

_{使用 gpt-6-luna 和临床预设进行的真实运行。患者为虚构人物。脚本：assets/demo/clinical_demo.py}

功能

调和变更。 新值会取代旧值，“我们已停用 X”会撤销 X。已退役的事实不会再作为当前事实返回。
保留历史记录。 查询当前或过去成立的事实。每次变更都会写入经过签名、防篡改的审计链。
在关键情形下需要人工审批。 将药物等槽位标记为必须确认，变更就会进入队列。check_before_act 会阻止依赖存在争议、已过时或刚变更事实的操作。
轻量且本地运行。 默认使用 SQLite，团队可使用 Postgres。存储事实时调用一次模型，回答时调用一次。支持任何兼容 OpenAI 的模型、Anthropic、Groq 或本地 Ollama 模型。
内置预设，适用于临床、支持、金融、销售、编码和助手记忆。

安装

pip install vayl-mcp

将其添加到 Claude Code：

claude mcp add vayl -e LLM_PROVIDER=openai -e OPENAI_API_KEY=sk-... -e VAYL_DB=$HOME/.vayl/vayl.db -- vayl-mcp

关于 Cursor、Claude Desktop 和其他客户端，请参阅快速入门。运行 vayl-demo，无需 API 密钥即可试用调和功能。

在代码中使用

from vayl import Vayl

with Vayl(user_id="cust_5521") as m:
    m.remember("Acme's invoice bounced. Account suspended until payment clears.")
    print(m.recall("Is Acme's account in good standing?"))
    # No. Acme's account is suspended until payment clears.

集成

Agent 框架。 后端会接入框架自身的记忆系统，因此每轮对话都会存储和召回事实。工具适配器为 Agent 提供可调用的记忆工具。

框架	安装	使用
Google ADK	`pip install 'vayl-mcp[adk]'`	`from vayl.integrations.adk import VaylMemoryService`（记忆后端）
LlamaIndex	`pip install 'vayl-mcp[llamaindex]'`	`from vayl.integrations.llamaindex import VaylMemory`（记忆块）
AutoGen	`pip install 'vayl-mcp[autogen]'`	`from vayl.integrations.autogen import VaylMemory`（记忆后端）
LangGraph / LangChain	`pip install 'vayl-mcp[langgraph]'`	`from vayl.integrations.langgraph import VaylMemory`（工具）
OpenAI Agents SDK	`pip install 'vayl-mcp[openai-agents]'`	`from vayl.integrations.openai_agents import VaylMemory`（工具）
CrewAI	`pip install 'vayl-mcp[crewai]'`	`from vayl.integrations.crewai import VaylMemory`（工具）
Pydantic AI	`pip install vayl-mcp 'pydantic-ai-slim[openai,mcp]'`	通过 MCP 使用 `MCPToolset`，无需适配器
Agno	`pip install vayl-mcp agno openai`	通过 MCP 使用 `MCPTools`，无需适配器
Vercel AI SDK	`npm i @vayl.dev/client ai zod`	`import { vaylTools } from "@vayl.dev/client/vercel"`
Mastra	`npm i @vayl.dev/client @mastra/core zod`	`import { vaylTools } from "@vayl.dev/client/mastra"`

每个框架的示例见Agent 框架。

MCP 客户端。 安装 vayl-mcp，然后将其添加到客户端中：Claude Code · Cursor · VS Code · Windsurf · Zed · Cline · Continue · Codex CLI · Gemini CLI。如需共享的团队记忆，可运行 vayl-server，并通过 MCP 或 REST 调用。

文档


快速入门	安装并连接客户端
Vayl 的工作原理	提取、协调与检索
教程：医院用药助手	临床预设、关键事实与审批
教程：客户支持助手	账户状态与安全检查
MCP 工具	全部 30 多种工具
部署 vayl-server	团队服务、身份验证、Docker、Postgres
基准测试	与 Mem0 和 Graphiti 对比的过时值及撤回结果