Vayl

Vayl normally lets the extractor name its own slots, which suits open-ended memory. The cost, measured on real conversational data: 626 distinct subjects across 638 facts — about 2% reuse. Since the same-slot invariant resolves rivals by exact subject equality, descriptive per-utterance naming means two statements about one thing sit side by side, unreconciled.

For a domain with known fields, declare them (VAYL_SLOT_SCHEMA=/path/slots.json):

{"slots": [
  {"name": "active_medication", "category": "critical", "verbatim": true, "confirm": true,
   "description": "a medication the patient is currently taking, with dose and frequency",
   "aliases": ["meds", "current_medication", "prescribed_medication"]}
]}

A malformed or missing schema raises rather than falling back to empty. Empty by default — declare nothing and behaviour is unchanged. Full example: examples/clinical-slots.json.

Built-in presets — skip the JSON and use a bundled schema: VAYL_SLOT_SCHEMA=preset:coding (also clinical, finance, support, assistant, sales). Pair the clinical/finance presets with VAYL_CRITICAL_CATEGORIES=critical so their critical slots are always surfaced.

Recall is semantic top-k, which is probabilistic. For most memory a fact ranked low is a quality problem. For some it is a safety problem — an allergy that doesn't make the cut isn't ranked low, it is invisible, and the answer comes back confident and incomplete. The safety gates can't catch that either: safe_recall and check_before_act judge the facts they were handed, so a retrieval miss is invisible to them too.

Facts whose category is named as critical skip ranking entirely:

VAYL_CRITICAL_CATEGORIES=allergy,active_medication

remember("Patient is allergic to penicillin", metadata={"category": "allergy"})
recall("summarise the chart", critical_categories="allergy")   # per-call override

If the critical set exceeds the context budget (VAYL_CRITICAL_BUDGET, default 200) the read raises rather than truncating — silently dropping the tail of an always-include set would recreate the exact miss the mechanism exists to prevent. Off unless configured.

Reconciliation is driven by an LLM reading conversational text. For most slots a wrong write is recoverable. For some, the write itself is the hazard: "we should probably stop the warfarin" appearing in a sentence is not an order to stop it.

A slot declared "confirm": true doesn't apply a replacement or removal. It records a proposal, leaves the current value standing, and waits:

pending_changes()                          → #42 REMOVE active_medication: 'warfarin 5mg daily' → …
                                                   said: "stop the warfarin"
confirm_change(42, decided_by="dr_smith")  → applies it
reject_change(42, decided_by="dr_smith")   → discards it; current value unchanged

A first write to a gated slot isn't blocked (nothing to lose yet). A proposal can't be confirmed once the value it would have replaced has itself changed. A rejected proposal is kept as history — that someone proposed stopping a medication is itself worth auditing. And a pending proposal is FLAGGED rather than ACTIVE, so it can never present itself as the current value in a recall.

Facts carry a kind. State holds until something replaces it (we use Postgres) and keeps the same-slot invariant — exactly one active value per slot. Events happened at a point in time (ran a charity race, the customer called) and are exempt: two races are two races, not a correction, so they coexist and never supersede each other. The exemption is enforced in the engine rather than trusted to the extractor — a mislabelled SUPERSEDE on an event is downgraded, so neither a confused model nor a later state fact sharing a subject can delete the record that something happened. Untagged facts default to state.

recall answers from current facts by default. Retired ones aren't merely filtered out of the answer — they're never loaded, so a superseded value cannot come back as current no matter how the model behaves. For questions about the past, opt in:

recall("what monitoring did we use before?", include_history=True)

Retired facts then arrive tagged (history) alongside the current value. Use history(subject) for the full timeline of one slot.

For deep relational questions ("who owns the company Bob works for?"):

pip install ".[graph]"    # + run Neo4j, then set "VAYL_GRAPH": "1" in the server env

Facts mirror into Neo4j as an entity graph; each edge is embedded on write and ranked by a native Neo4j vector index, so recall_related stays 50–230 ms even on high-degree hubs — no whole-graph scan. If the graph isn't enabled (or Neo4j is down), recall_related falls back to slot recall. Edges are namespaced per (user_id, agent_id, run_id), so delete / delete_all purge the graph too.

Vayl is event-sourced — supersede / retract / update keep the old rows (that's the audit trail), so history grows over time. The hot path is separated from history so a long-lived user stays fast:

• load reads only the active working set (ACTIVE + FLAGGED) → cost is O(active facts), not O(total history).
• save is incremental — inserts new rows, updates the few that changed — never a rewrite.
• Vectors stay on disk until a ranking pass needs them, stored as binary float32 (~6 KB vs ~15 KB per 1536-dim vector as JSON).
• Query embeddings are cached (FIFO, VAYL_QUERY_CACHE, default 512).

History is read lazily; with include_history off it is never loaded, which is what makes "a superseded value cannot be returned as current" a structural property rather than something the model is asked to respect. Persistence verified to 20k facts.

Every tool takes optional agent_id / run_id — each (user_id, agent_id, run_id) combination is its own isolated memory space (leave them blank for a single space). remember also takes optional metadata to tag facts.

Full deployment guide: DEPLOY.md · security model: SECURITY.md · EU/GDPR: COMPLIANCE.md.

Two ways to run:

vayl-mcp        # stdio transport — one local user (Claude Desktop / Cursor / Claude Code)
vayl-server     # streamable-HTTP transport — a shared TEAM endpoint, auth required
                # pip install ".[server]"  ·  VAYL_HOST=0.0.0.0 VAYL_PORT=8080 vayl-server

vayl-server requires Authorization: Bearer vayl_sk_… on every request (no/invalid key → 401); /healthz, /readyz, and /metrics (Prometheus) are open for probes/scraping. Bootstrap the first admin over stdio (vayl-mcp → create_principal("you", role="admin")), then hand out keys. Terminate TLS at your reverse proxy / ingress — don't expose the server raw.

Authentication & RBAC. Principals authenticate with an API key (vayl_sk_…); each has a role (admin / member / agent / viewer / auditor) that grants a set of capabilities (read / write / delete / verify / admin), and every tool checks its required capability (fail-closed). Local stdio use runs as a trusted local admin; the remote server resolves the caller from the Bearer credential per request — either an API key or, with an Enterprise license, an OIDC SSO ID token (a JWT verified against your IdP's JWKS with claims mapped to roles). Each deployment is one org (the isolation boundary), with a tenant_id seam in the store for a future hosted edition.

Tenant scoping — read this before a multi-tenant deployment. user_id arrives from the caller. Roles answer "may this key read at all"; they do not answer "whose memory". Give a principal scopes to confine it:

create_principal("support-bot", role="agent", scopes="cust_5521,cust_7788")

Without scopes a principal is unrestricted — correct for single-tenant, wrong the moment one deployment holds several customers' data. An admin is unrestricted regardless. Denials are audited and deliberately do not echo the requested user_id back, so a scoped caller cannot enumerate spaces from error text.

Deploy (self-host, Docker):

docker compose up -d --build
# bootstrap the first admin (one-off) — copy the printed key:
docker compose run --rm vayl python -c "from vayl.api import mcp_server as s; print(s.create_principal('admin', role='admin'))"
curl localhost:8080/healthz        # liveness   ·   curl localhost:8080/metrics  → Prometheus

The container runs as a non-root user; the SQLite DB + encryption/signing keys persist on the vayl-data volume (/data). Configure the LLM and (optional) license via env in docker-compose.yml.

Storage backend. SQLite by default (single node, zero setup). For scale set VAYL_DATABASE_URL=postgresql://… (pip install ".[postgres]", or docker compose --profile postgres up) and Vayl runs on Postgres instead — validated end-to-end on Postgres 17. Multiple vayl-server processes can share one Postgres: same-space writes serialize via a pg_advisory_xact_lock (different spaces run in parallel), so scaling out is safe.

Key custody (KMS). By default the encryption/signing keys are auto-generated files beside the data (VAYL_KMS=file). For production, set VAYL_KMS=vault (+ VAULT_ADDR, VAULT_TOKEN) to use HashiCorp Vault Transit envelope encryption — the master key never leaves Vault, only a wrapped key blob sits on disk. If Vault is unreachable Vayl fails closed (won't start) rather than run unencrypted.

Editions & licensing. Community (default) is free, self-hosted, capped at a few principals. An Enterprise license (a signed, offline-verified blob — no license server, works air-gapped) raises the seat cap and unlocks enterprise features. Set VAYL_LICENSE=<blob or path>. A missing/expired/tampered license degrades softly to Community — it never bricks a running deployment.