vayl-mcp
Provides a CrewAI memory backend via VaylMemory, enabling agents to store and recall reconciled facts.
Provides a Google ADK memory backend via VaylMemoryService, allowing ADK agents to store and recall reconciled facts.
Provides Vayl memory tools for LangChain agents through the LangGraph/LangChain integration.
Provides VaylMemory tools for LangGraph agents, enabling storage and recall of reconciled facts.
Provides VaylMemory tools for the OpenAI Agents SDK, enabling agents to store and recall reconciled facts.
Integrates with Pydantic AI via MCPToolset over MCP, exposing Vayl memory tools without a custom adapter.
Provides Vercel AI SDK tools via @vayl.dev/client/vercel, enabling AI SDK agents to store and recall reconciled facts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vayl-mcp Acme paid their invoice — is their account still suspended?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Vayl
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 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.
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. 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.
Related MCP server: agent-memory
Install
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.
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 |
|
|
LlamaIndex |
|
|
AutoGen |
|
|
LangGraph / LangChain |
|
|
OpenAI Agents SDK |
|
|
CrewAI |
|
|
Pydantic AI |
|
|
Agno |
|
|
Vercel AI SDK |
|
|
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
Install and connect a client | |
Extraction, reconciliation and retrieval | |
Clinical preset, critical facts and approval | |
Account state and safety checks | |
What applies by itself, what waits, and how to approve | |
All 30+ tools | |
Team server, auth, Docker, Postgres | |
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. 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.
License
Available Tools
32 toolsattestAttest the current value of a subject (signed proof)A
Issue a signed, third-party-verifiable attestation of what memory currently holds for
subject — 'as of now, the active value is X', anchored to the tamper-evident audit-log head.
Use it to prove what was known at a point in time. Verify later with verify_receipt, or
independently with export_public_key.
Inputs: subject (required), run_id, user_id, agent_id. Returns: result
audit_logAudit log (accountability trail)BRead-only
The accountability trail (GDPR Art. 5(2)) — recent data operations: who / what / when. Optionally filter by user_id. Not affected by memory erasure.
Inputs: limit, user_id. Returns: result
check_before_actSafety check before acting on a factARead-only
Ask whether it's SAFE to take an autonomous action based on what memory knows about subject.
Returns SAFE, or BLOCKED with explicit reasons — an unresolved conflict, confidence below the bar,
a value that's gone stale, or one that just changed. Call this before any irreversible action
(a payment, an email, a config change) so the agent never silently acts on bad memory. Tune the
policy via the params (e.g. min_confidence=0.9, max_staleness_days=90 for high-stakes actions).
Inputs: subject (required), run_id, user_id, agent_id, +5 more. Returns: result
confirm_changeApprove a pending changeA
Approve a proposed change to a confirm-required slot, applying it together with any changes
linked to it. Needs the approve capability (admin and member roles; agents lack it, so an agent
can't approve its own proposal). The approver recorded is the authenticated caller; decided_by
is an optional note. If approving would break a declared constraint (e.g. two anticoagulants
current) it is refused; pass override=true when the overlap is intended, such as bridging.
Inputs: memory_id (required), run_id, user_id, agent_id, +2 more. Returns: result
create_principalCreate a principal (user/agent) + API keyA
Admin only. Create a principal (a human user, agent, or service) and issue its API key. Roles: admin, member, agent, viewer, auditor. The key is shown ONCE — store it securely; it can't be recovered (reissue by creating a new principal).
scopes is a comma-separated list of user_ids this principal may access, e.g.
"cust_5521,cust_7788". Leave empty for unrestricted (the default, and correct for a
single-tenant deployment). Set it for any multi-tenant deployment: without it, a valid
key can read any space by passing that space's user_id. An admin role is unrestricted
regardless, since org control implies reaching every space.
tenant is the org partition this key belongs to (default: the caller's own tenant). It is a
HARD boundary: every store query is filtered by it, so a key for one tenant cannot reach another
tenant's memory even under the same user_id. Set it per org in a shared multi-tenant deployment.
Only the deployment operator (an admin of the "default" tenant) may name a different tenant.
Inputs: name (required), kind, role, scopes, +1 more. Returns: result
deleteErase a subject permanently (GDPR erasure)ADestructiveIdempotent
PERMANENTLY erase every record of a subject — including history and tombstones — for a user.
Unlike forget (which retires but retains for audit), this is a hard delete for
right-to-be-forgotten / GDPR erasure. The subject is the key shown by list_memories.
Inputs: subject (required), run_id, user_id, agent_id. Returns: result
delete_allErase ALL memory for a user permanently (GDPR erasure)ADestructiveIdempotent
PERMANENTLY erase memory (history included). With no agent_id/run_id, erases ALL of the
user's memory across every space (account deletion / GDPR); pass them to erase just one space.
Irreversible — not the same as forget, which retains history for audit.
Inputs: run_id, user_id, agent_id. Returns: result
explain_decisionExplain a past decision (why the agent acted)BRead-only
Reconstruct why an agent acted: the recorded action and the exact beliefs it held at that moment — even if those facts have since been superseded, retracted, or erased. Also verifies the decision's signed receipt so you know the record itself wasn't altered.
Inputs: decision_id (required), user_id. Returns: result
export_memoryExport all memory as JSON (GDPR access/portability)ARead-only
Export everything held about a user/space as machine-readable JSON — data-subject access & portability (GDPR Art. 15/20). A complete DSAR answer: statements (active + full history), PLUS what the append-only records hold about them — decision snapshots, audit entries, and receipts.
Inputs: run_id, user_id, agent_id. Returns: result
export_public_keyExport the public key for third-party verificationARead-only
Return Vayl's Ed25519 public key (hex). Anyone can use it to verify erasure receipts, attestations, and the signed audit chain WITHOUT the secret key or access to the database.
Inputs: no named parameters. Returns: result
forgetForget / retract (kept in history for audit)A
Retract a fact — a removal with no replacement. Unlike additive stores, this actually retires it so it stops being returned as current (kept in history for audit). Examples: 'We dropped Sentry', 'Alice left the Platform team', 'we no longer support IE11'.
Inputs: text (required), run_id, user_id, agent_id. Returns: result
get_memoryGet one memory by idARead-only
Fetch one memory by its id (the #id shown by list_memories) — its value, status, scope,
confidence, what it supersedes, and any metadata.
Inputs: memory_id (required), run_id, user_id, agent_id. Returns: result
get_reconcile_policyShow a shared space's reconciliation policyBRead-only
Show the source-aware reconciliation policy configured for a space (default RECENCY if unset).
Inputs: run_id, user_id, agent_id. Returns: result
healthHealth checkARead-only
Check that Vayl is configured and its dependencies are reachable — database, embedder, LLM, and graph (if enabled). Run this to diagnose setup before relying on memory; it makes one small LLM/embed call, so it costs a few tokens.
Inputs: no named parameters. Returns: result
historyChange history for a subjectBRead-only
The change-log for a subject — every value it has held, oldest → newest, with status.
The 'what did we use first vs now' view that additive stores can't give you. The subject
is the key shown by list_memories.
Inputs: subject (required), run_id, user_id, agent_id. Returns: result
license_statusShow the license / edition statusARead-only
Show the deployment's edition and entitlements — Community or a licensed edition, seats used vs allowed, expiry, and unlocked features. If a license was rejected (tampered/expired/wrong key), this says so and reports the Community fallback it's running under.
Inputs: no named parameters. Returns: result
list_memoriesList current memoriesARead-only
List the current active facts (the reconciled current beliefs) for a user, plus a history
block of what was superseded / retracted / archived. Active rows show the #id for get/update.
Inputs: run_id, user_id, agent_id. Returns: result
list_principalsList principals of this deploymentARead-only
Admin only. List your tenant's principals — id, name, roles, and whether disabled (the deployment operator sees every tenant's). Never shows API keys (only their hashes are stored).
Inputs: no named parameters. Returns: result
pending_changesList changes awaiting human approvalBRead-only
List proposed changes to confirm-required slots that have NOT been applied.
Slots declared with "confirm" in the slot schema do not auto-apply a replacement or removal — the current value stands until a person approves. This is the queue of what is waiting.
Inputs: run_id, user_id, agent_id. Returns: result
purge_expiredPurge records older than N days (retention)ADestructiveIdempotent
Retention / storage-limitation (GDPR Art. 5(1)(e)): permanently delete records written more
than older_than_days ago. Statements are scoped to the user/space. The optional flags extend
the same window to the append-only tables — NOTE these are not per-user: include_decisions and
include_receipts purge those tables for your whole tenant, and include_audit purges the audit
log from the head of the chain (a signed retention anchor keeps the remaining chain verifiable).
There is one chain per deployment, shared by every tenant, so include_audit is DEPLOYMENT-WIDE
and only the deployment operator may use it.
Inputs: older_than_days (required), run_id, user_id, agent_id, +3 more. Returns: result
recallRecall from current memoryARead-only
Answer a question from CURRENT memory — the active value ('what state library do we use?')
or a multi-hop question over current facts. Returns 'I don't know' rather than guessing, and
NEVER answers from a retired/retracted fact. For the timeline of a subject, use history.
Set include_history=True ONLY for questions explicitly about the past — 'what did we use
before?', 'when did we switch?' — where retired facts are the answer. It is off by default
because with it off, superseded values are never loaded at all, so a stale value cannot be
returned as current regardless of how the model behaves. Leaving it off is the guarantee;
turning it on trades that for reach into the timeline.
critical_categories (comma-separated) names fact categories that must ALWAYS reach the
answer regardless of ranking — 'allergy,active_medication' in a clinical deployment. Ordinary
recall is semantic top-k, so a fact that does not rank is invisible, not merely deprioritised;
for some categories that is a safety failure rather than a quality one. Leave empty to use the
deployment-wide VAYL_CRITICAL_CATEGORIES; an empty value never means 'none'.
Set explain=True to also get the PROVENANCE — the exact facts used to answer, each with who
asserted it, its confidence, and what it superseded. That's the truthful basis for an audit of
why the agent believes what it does (and it's what record_decision snapshots).
Inputs: question (required), run_id, explain, user_id, +3 more. Returns: result
record_decisionRecord a decision + the beliefs behind itA
Log a decision an agent is about to take, bound to the EXACT facts it consulted. Atomically
recalls question with provenance and snapshots those beliefs (value, source, confidence, what
they superseded) alongside action_summary. The snapshot is immutable and signed, so 'why did
the agent do X?' stays answerable even after the facts later change. Returns the decision id and
a verifiable receipt hash. Example: action_summary='Issued refund to order #91', question='what
is the refund policy and this customer's tier?'.
Inputs: question (required), action_summary (required), run_id, user_id, +1 more. Returns: result
reject_changeDiscard a pending changeA
Discard a proposed change. The current value stands. The proposal is kept as history —
that someone proposed it is itself worth being able to audit. Needs approve, like
confirm_change: an agent quietly discarding proposals would empty the review queue just as
surely as approving them. decided_by is an optional note beside the authenticated caller.
Inputs: memory_id (required), run_id, user_id, agent_id, +1 more. Returns: result
rememberRemember (extract & reconcile facts)A
Store fact(s) from a statement. Reconciles automatically: a new value SUPERSEDES the old
one (not appended), removals are RETRACTED, and multiple facts in one message are all captured.
Optional metadata tags the facts stored in this call. source records WHO/WHAT asserted the
fact (an agent id, a person, a connector) — belief provenance, and the basis for source-aware
reconciliation in a shared space (see set_reconcile_policy). Examples: 'We switched from Zustand
to Redux Toolkit', 'Alice is the new team lead'.
Inputs: text (required), run_id, source, user_id, +2 more. Returns: result
revoke_principalRevoke a principal's accessADestructiveIdempotent
Admin only. Disable a principal — its API key stops working immediately. Irreversible
(create a new principal to restore access). With erase=True, the principal row is HARD-deleted
(Art. 17 for team members) instead of retained as disabled. A tenant admin can only revoke its
own tenant's principals; another tenant's id reads as unknown.
Inputs: principal_id (required), erase. Returns: result
safe_recallGated recall — answers only if safe to act onARead-only
Like recall, but for when the agent will ACT on the answer. It answers only if every current
fact behind the answer passes the safety policy; otherwise it withholds the answer and returns the
reasons (disputed value, low confidence, stale, or nothing current). Use this instead of recall
on the path to an irreversible action.
critical_categories behaves as in recall, and matters more here: this gate can only judge
the facts it was handed, so a critical fact ranked out of context would be invisible to the
check as well — it would pass, on an answer it never knew was incomplete.
Inputs: question (required), run_id, user_id, agent_id, +6 more. Returns: result
set_reconcile_policyConfigure how a shared space reconciles conflicting sourcesA
Configure how a SHARED space resolves conflicts between DIFFERENT contributors (sources).
A shared space is any space (e.g. user_id='org:acme') that multiple agents/people write to with
a source on each remember. Modes:
• RECENCY — newer assertion wins (default; contributors equally trusted).
• AUTHORITY — a higher-ranked source wins; a lower-ranked source contradicting it is FLAGGED,
not overwritten. Pass authority as {source: rank} (higher = more authoritative).
• REVIEW — any cross-source conflict is FLAGGED for a human.
A source correcting its OWN earlier fact always supersedes, regardless of mode.
Inputs: mode, run_id, user_id, agent_id, +1 more. Returns: result
statsUsage stats & KPIsARead-only
Operational KPIs for this Vayl instance — on-device, nothing leaves the machine: per-tool call counts, average latency and error counts, plus the distribution of reconciliation actions the engine has taken (SUPERSEDE / RETRACT / FLAG / SKIP / ADD / …).
Inputs: no named parameters. Returns: result
update_memoryUpdate a memory (audit-preserving)A
Correct a memory by id (the #id from list_memories). Audit-preserving: the old value is
retired to history and the new value becomes active — so the change still shows up in history.
Inputs: memory_id (required), new_value (required), run_id, user_id, +1 more. Returns: result
verify_auditVerify the audit log is untamperedARead-only
Verify the tamper-evident audit chain end-to-end. Recomputes every row's hash and (if signed) signature; reports INTACT, or the exact row where the chain breaks — so you can prove the accountability log wasn't edited, reordered, or truncated.
Inputs: no named parameters. Returns: result
verify_receiptVerify a signed receipt / attestationARead-only
Verify a persisted erasure receipt or knowledge attestation: recompute its canonical body and check the Ed25519 signature. Confirms the artifact is authentic and unaltered — the same check a third party can run with only the public key.
Inputs: receipt_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Shared memory for your AI agents. Every fact shows its source, and stale facts get replaced.
Plug-and-play memory for any AI: approved facts, human review, audit trail
Long-term memory for AI agents: bitemporal fact ledger, contradiction detection, explainability.
Your team's shared, verified knowledge for AI agents: ask what's true, record what you learn.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to record, recall, correct, and forget evidence-backed factual claims with temporal history, while explaining whether remembered information is current, historical, or contested.5Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to maintain long-term, cross-session memory by extracting facts, reconciling state conflicts, and retrieving relevant memories via vector search.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to store and retrieve typed facts with bi-temporal validity, supersede outdated information, and query what was true as of any past date.MIT

Particlesofficial
AlicenseAqualityBmaintenanceMemory for AI agents that keeps every claim with the source it came from, the date it was asserted, and a confidence you can re-weight per source, so your agent can say where a fact came from. Updates supersede or retract instead of overwriting, so you can replay what the store believed on any past date and review contradictions as lint findings.1676 PyPI4Apache 2.0