vayl-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| VAYL_DB | No | Path to the SQLite database file, e.g. $HOME/.vayl/vayl.db. | |
| LLM_PROVIDER | Yes | The model provider to use, for example "openai". | |
| OPENAI_API_KEY | Yes | API key for the OpenAI-compatible model provider. | |
| ANTHROPIC_API_KEY | No | When set and a preset is in use, enables the second-model check by default. | |
| VAYL_CONFIRM_MODE | No | Set to "review" to require a person to approve every change. | |
| VAYL_ESCALATE_MODEL | No | Set to "off" to disable the second-model check. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Vayl is persistent, reconciling memory. When the user asks you to remember, note or keep track of something, or states a fact or a change to one (a decision, a preference, a dose, an account setting, 'we switched to X'), call remember with one plain sentence: Vayl retires the old value instead of keeping both, which a notes file cannot do. Before answering from what you were told earlier (a project's stack, a customer's plan, a patient's current medication), call recall, with include_history=true for 'what was it before?'. Use forget when something is no longer true and has no replacement. If recall doesn't know, say so instead of guessing.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": false,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| rememberA | 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 |
| recallA | 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 Set
Set |
| recall_relatedA | Answer a DEEP / RELATIONAL / multi-hop question using the entity graph ('who owns the company Bob works for?', 'which services depend on the auth module?'). Uses the Neo4j graph projection when configured; otherwise falls back to slot recall. |
| forgetA | 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'. |
| get_memoryA | Fetch one memory by its id (the |
| update_memoryA | Correct a memory by id (the |
| historyB | 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 |
| record_decisionA | Log a decision an agent is about to take, bound to the EXACT facts it consulted. Atomically
recalls |
| explain_decisionB | 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. |
| check_before_actA | Ask whether it's SAFE to take an autonomous action based on what memory knows about |
| safe_recallA | Like
|
| deleteA | PERMANENTLY erase every record of a subject — including history and tombstones — for a user.
Unlike |
| delete_allA | 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 |
| attestA | Issue a signed, third-party-verifiable attestation of what memory currently holds for
|
| verify_receiptA | 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. |
| verify_auditA | 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. |
| export_public_keyA | 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. |
| set_reconcile_policyA | 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 |
| get_reconcile_policyB | Show the source-aware reconciliation policy configured for a space (default RECENCY if unset). |
| pending_changesB | 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. |
| confirm_changeA | Approve a proposed change to a confirm-required slot, applying it together with any changes
linked to it. Needs the |
| reject_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 |
| create_principalA | 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).
|
| list_principalsA | 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). |
| license_statusA | 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. |
| revoke_principalA | Admin only. Disable a principal — its API key stops working immediately. Irreversible
(create a new principal to restore access). With |
| list_memoriesA | 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 |
| export_memoryA | 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. |
| purge_expiredA | Retention / storage-limitation (GDPR Art. 5(1)(e)): permanently delete records written more
than |
| audit_logB | The accountability trail (GDPR Art. 5(2)) — recent data operations: who / what / when. Optionally filter by user_id. Not affected by memory erasure. |
| statsA | 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 / …). |
| healthA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.