Vayl

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

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

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.

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

Fetch one memory by its id (the `#id` shown by `list_memories`) — its value, status, scope, confidence, what it supersedes, and any metadata.

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

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

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

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.

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

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.

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

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.

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.

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

Takes no parameters.

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.

Takes no parameters.

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.

Show the source-aware reconciliation policy configured for a space (default RECENCY if unset).

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.

Approve a proposed change to a confirm-required slot, applying 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.

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.

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.

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

Takes no parameters.

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.

Takes no parameters.

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.

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.

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.

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.

The accountability trail (GDPR Art. 5(2)) — recent data operations: who / what / when. Optionally filter by user_id. Not affected by memory erasure.

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 / …).

Takes no parameters.

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.

Takes no parameters.