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 is built for agents where a wrong stored fact causes harm: a medication list, a portfolio, an account's status. 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, with every change set to wait for approval. The patient is fictional. Script: assets/demo/clinical_demo.py
- 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.
- Automatic, and careful about it. On gated slots such as medications, a clear change applies by itself. An uncertain one (hedged, negated, or one that would leave two anticoagulants active) is checked by a second model that reads the message without seeing the proposed change, and it applies only if the two agree. Otherwise the old value stands and the change waits in
pending_changes. SetVAYL_CONFIRM_MODE=reviewto have a person approve every change. - Fails towards the old value. Pasted or retrieved text can only propose a change to a declared slot, never apply one. If the checking model can't be reached, nothing is applied unchecked.
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; with a preset, up to three calls to store (extract, verify, and the second-model check). Any OpenAI-compatible model, Anthropic, Groq or a local Ollama model.
- Built-in presets for clinical, support, finance, sales, coding and assistant memory.
pip install vayl-mcpAdd 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-mcpFor Cursor, Claude Desktop and other clients, see the quickstart. Run vayl-demo to try reconciliation with no API key.
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 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.
| 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 |
| Safety gates and human approval | What applies by itself, what waits, and how to approve |
| MCP tools | All 30+ tools |
| Deploying vayl-server | Team server, auth, Docker, Postgres |
| Benchmarks | Stale-value and retraction results against Mem0 and Graphiti |
See CONTRIBUTING.md. The unit tests run offline, with no API key. Good starting points are labeled good first issue.
Data is encrypted at rest by default, and Vayl sends nothing anywhere except to the model endpoints you configure. When ANTHROPIC_API_KEY is set and a preset is in use, the second-model check is on by default and sends the message text to Anthropic; set VAYL_ESCALATE_MODEL=off to turn it off. Vayl is not certified for clinical use and has not been audited by a third party. Report vulnerabilities as described in SECURITY.md.