About Vayl
Vayl is a memory layer for AI agents that reconciles changing facts instead of treating every stored value as current. It keeps an audit history and can require human approval for sensitive changes, with local SQLite storage by default.
Key features
- 01Reconciles updated and retracted facts
- 02Retains history with an audit chain
- 03Approval queue for designated changes
- 04Action checks for disputed or stale facts
- 05SQLite by default; Postgres for teams
Use cases
- 01Keep customer account status current
- 02Require confirmation for medication changes
- 03Check facts before an agent takes action
MCP support
Vayl runs as an MCP server that MCP clients can connect to for memory tools. For shared team memory, vayl-server can be called over MCP or REST.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx vayl-mcpOPENAI_API_KEYSecretOpenAI key for extraction and embeddings. Leave unset to use a local Ollama model.VAYL_DBAbsolute path of the SQLite memory database.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
32Saved tool list · updated 1w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | |
| run_id | string | No | |
| source | string | No | |
| user_id | string | No | |
| agent_id | string | No | |
| metadata | any | No |
Details
From the project READMEVayl
The reconciling memory layer for AI agents.
When a fact changes, most agent memory keeps both versions and lets the model guess which is current. Vayl replaces the old value, keeps it in history, and can hold high-stakes changes until a person approves them. It runs locally on SQLite and works with any MCP client: Claude Code, Cursor, Claude Desktop, or your own agent.
A real run with gpt-6-luna and the clinical preset. The patient is fictional. Script: assets/demo/clinical_demo.py
Features
- Reconciles changes. A new value supersedes the old one, and "we stopped X" retracts X. A retired fact is never returned as current.
- Keeps history. Ask what is true now or what was true before. Every change goes on a signed, tamper-evident audit chain.
- Human approval where it matters. Mark slots such as medications as confirm-required, and changes wait in a queue.
check_before_actblocks an action that depends on a disputed, stale or just-changed fact. - Small and local. SQLite by default, Postgres for teams. One model call to store a fact and one to answer. Any OpenAI-compatible model, Anthropic, Groq or a local Ollama model.
- Built-in presets for clinical, support, finance, sales, coding and assistant memory.
Install
pip install vayl-mcp
Add it to Claude Code:
claude mcp add vayl -e LLM_PROVIDER=openai -e OPENAI_API_KEY=sk-... -e VAYL_DB=$HOME/.vayl/vayl.db -- vayl-mcp
For Cursor, Claude Desktop and other clients, see the quickstart. Run vayl-demo to try reconciliation with no API key.
Use it from code
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.
Integrations
Agent frameworks. Backends plug into the framework's own memory, so facts are stored and recalled on every turn. Tool adapters give the agent memory tools to call.
| Framework | Install | Use |
|---|---|---|
| Google ADK | pip install 'vayl-mcp[adk]' | from vayl.integrations.adk import VaylMemoryService (memory backend) |
| LlamaIndex | pip install 'vayl-mcp[llamaindex]' | from vayl.integrations.llamaindex import VaylMemory (memory block) |
| AutoGen | pip install 'vayl-mcp[autogen]' | from vayl.integrations.autogen import VaylMemory (memory backend) |
| LangGraph / LangChain | pip install 'vayl-mcp[langgraph]' | from vayl.integrations.langgraph import VaylMemory (tools) |
| OpenAI Agents SDK | pip install 'vayl-mcp[openai-agents]' | from vayl.integrations.openai_agents import VaylMemory (tools) |
| CrewAI | pip install 'vayl-mcp[crewai]' | from vayl.integrations.crewai import VaylMemory (tools) |
| Pydantic AI | pip install vayl-mcp 'pydantic-ai-slim[openai,mcp]' | MCPToolset over MCP, no adapter |
| Agno | pip install vayl-mcp agno openai | MCPTools over MCP, no adapter |
| 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" |
Examples for each are in Agent frameworks.
MCP clients. Install vayl-mcp, then add it to your client: Claude Code · Cursor · VS Code · Windsurf · Zed · Cline · Continue · Codex CLI · Gemini CLI. For a shared team memory, run vayl-server and call it over MCP or REST.
Documentation
| Quickstart | Install and connect a client |
| How Vayl works | Extraction, reconciliation and retrieval |
| Tutorial: a hospital medication assistant | Clinical preset, critical facts and approval |
| Tutorial: a customer-support assistant | Account state and safety checks |
| MCP tools | All 30+ tools |
| Deploying vayl-server | Team server, auth, Docker, Postgres |
| Benchmarks | Stale-value and retraction results against Mem0 and Graphiti |
Contributing
See CONTRIBUTING.md. The unit tests run offline, with no API key. Good starting points are labeled good first issue.
Security
Data is encrypted at rest by default, and Vayl sends nothing anywhere except to the model endpoints you configure. Vayl is not certified for clinical use and has not been audited by a third party. Report vulnerabilities as described in SECURITY.md.
License
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.