Skip to main content
Glama

Vayl

The reconciling memory layer for AI agents.

PyPI Python License OpenSSF Scorecard Docs

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. 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.

Related MCP server: agent-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

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

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

Apache-2.0

Available Tools

32 tools
attestAttest 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)B
Read-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 factA
Read-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)A
DestructiveIdempotent

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)A
DestructiveIdempotent

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)B
Read-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)A
Read-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 verificationA
Read-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 idA
Read-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 policyB
Read-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 checkA
Read-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 subjectB
Read-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 statusA
Read-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 memoriesA
Read-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 deploymentA
Read-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 approvalB
Read-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)A
DestructiveIdempotent

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 memoryA
Read-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 accessA
DestructiveIdempotent

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 onA
Read-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 & KPIsA
Read-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 untamperedA
Read-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 / attestationA
Read-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

    A3.7/5.0

    Scored across 32 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      5
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to maintain long-term, cross-session memory by extracting facts, reconciling state conflicts, and retrieving relevant memories via vector search.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      A
      quality
      B
      maintenance
      Memory 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.
      16
      76 PyPI
      4
      Apache 2.0