vayl-mcp
<div align="center">
# Vayl
The reconciling memory layer for AI agents.
[](https://pypi.org/project/vayl-mcp/)


[](https://scorecard.dev/viewer/?uri=github.com/ac12644/vayl)
[](https://vayl.gitbook.io/vayl-docs)
</div>
<!-- mcp-name: io.github.ac12644/vayl -->
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.
<p align="center">
<img src="assets/vayl-demo.gif" alt="A real run with a fictional patient: warfarin is recorded, then replaced by apixaban. With approval required (VAYL_CONFIRM_MODE=review), the change waits in pending_changes until a clinician confirms it. Recall then answers apixaban now, warfarin before, and refuses amoxicillin because of the recorded penicillin allergy." width="860">
</p>
<p align="center"><sub>A real run with <code>gpt-6-luna</code> and the clinical preset, with every change set to wait for approval. The patient is fictional. Script: <a href="assets/demo/clinical_demo.py"><code>assets/demo/clinical_demo.py</code></a></sub></p>
## 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.
- **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`. Set `VAYL_CONFIRM_MODE=review` to 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_act` blocks 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.
## Install
```bash
pip install vayl-mcp
```
Add it to Claude Code:
```bash
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](https://vayl.gitbook.io/vayl-docs/documentation/getting-started/quickstart). Run `vayl-demo` to try reconciliation with no API key.
## Use it from code
```python
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](https://vayl.gitbook.io/vayl-docs/documentation/integrations/agent-frameworks).
**MCP clients.** Install `vayl-mcp`, then add it to your client: [Claude Code](https://vayl.gitbook.io/vayl-docs/documentation/integrations/claude-code) · [Cursor](https://vayl.gitbook.io/vayl-docs/documentation/integrations/cursor) · [VS Code](https://vayl.gitbook.io/vayl-docs/documentation/integrations/vs-code) · [Windsurf](https://vayl.gitbook.io/vayl-docs/documentation/integrations/windsurf) · [Zed](https://vayl.gitbook.io/vayl-docs/documentation/integrations/zed) · [Cline](https://vayl.gitbook.io/vayl-docs/documentation/integrations/cline) · [Continue](https://vayl.gitbook.io/vayl-docs/documentation/integrations/continue) · [Codex CLI](https://vayl.gitbook.io/vayl-docs/documentation/integrations/codex) · [Gemini CLI](https://vayl.gitbook.io/vayl-docs/documentation/integrations/gemini-cli). For a shared team memory, run [`vayl-server`](https://vayl.gitbook.io/vayl-docs/documentation/guides/deploying-vayl-server) and call it over MCP or [REST](https://vayl.gitbook.io/vayl-docs/api-reference).
## Documentation
| | |
|---|---|
| [Quickstart](https://vayl.gitbook.io/vayl-docs/documentation/getting-started/quickstart) | Install and connect a client |
| [How Vayl works](https://vayl.gitbook.io/vayl-docs/documentation/concepts/how-vayl-works) | Extraction, reconciliation and retrieval |
| [Tutorial: a hospital medication assistant](https://vayl.gitbook.io/vayl-docs/documentation/guides/tutorial-a-hospital-medication-assistant) | Clinical preset, critical facts and approval |
| [Tutorial: a customer-support assistant](https://vayl.gitbook.io/vayl-docs/documentation/guides/tutorial-a-customer-support-assistant) | Account state and safety checks |
| [Safety gates and human approval](https://vayl.gitbook.io/vayl-docs/documentation/guides/safety-gates-and-human-approval) | What applies by itself, what waits, and how to approve |
| [MCP tools](https://vayl.gitbook.io/vayl-docs/documentation/reference/mcp-tools) | All 30+ tools |
| [Deploying vayl-server](https://vayl.gitbook.io/vayl-docs/documentation/guides/deploying-vayl-server) | Team server, auth, Docker, Postgres |
| [Benchmarks](https://vayl.gitbook.io/vayl-docs/documentation/why-vayl/why-your-agents-memory-returns-stale-facts) | Stale-value and retraction results against Mem0 and Graphiti |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). The unit tests run offline, with no API key. Good starting points are labeled [good first issue](https://github.com/ac12644/vayl/labels/good%20first%20issue).
## Security
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](SECURITY.md).
## License
[Apache-2.0](LICENSE)
</content>
</invoke>
TDQS
Scored across 32 tools
Most tools have clearly distinct roles, especially across memory CRUD, reconciliation policy, audit, GDPR, decisions, and principals. There is some inherent overlap among recall/safe_recall/recall_related/check_before_act and among forget/delete/delete_all/purge_expired, but the descriptions draw usable boundaries.
Names consistently use snake_case and are generally readable. Most follow verb_noun patterns, but there are notable bare verbs and noun-only tools such as remember, recall, forget, attest, health, history, stats, and audit_log.
Thirty-two tools is heavy for an MCP surface and exceeds the comfortable range for routine agent use. The breadth is partly justified by the server covering memory, reconciliation, audit, GDPR, decisions, and principal administration, but partitioning admin/ops tools would improve usability.
The surface covers memory lifecycle operations, reconciliation, provenance, decisions, audit verification, GDPR export/erasure/retention, principals, licensing, and health/stats. There are no obvious dead ends for the stated domain.