← Documentation

Agent memory governance

ValGuard does not store customer memory. It checks the tool_calls a model returns for a memory backend before your orchestrator executes them, and writes a metadata-only audit row for every call: rule id, decision, reason and a digest of the arguments, never the content. Every check is deterministic, with no extra model call.

Request headers

All three are optional on /v1/chat/completions. They tell ValGuard who the caller is, so the rules have something to compare the tool call against. Values are trimmed, an empty value counts as absent, and each may be at most 200 characters (longer values answer 400 invalid_memory_header when the agent has a memory policy; agents without one ignore the headers).

  • X-VG-Memory-Tenant-Id: needed for tenant isolation. With strict context (the default), a memory call without this header fails memory_tenant_isolation.
  • X-VG-Memory-User-Id: needed for user scope under strict context, and compared with any user_id in the call.
  • X-VG-Memory-Session-Id: needed for session scope under strict context, and compared with any session_id in the call.

The agent scope needs no header. With strict context off, a missing header skips the check that depends on it.

Modes

Configure a policy per agent under Agents → agent → Memory. Saving needs the admin role.

  • Off (default) injects no memory rules and costs nothing.
  • Shadow delivers the response and records what would be blocked. The request shows as Would block in request logs (status filter Shadow), the response carries X-VG-Validation-Status: shadow and X-VG-Warnings: would_block memory_…. All rules are evaluated, so you see every violation before turning enforcement on.
  • Enforce blocks the response before any memory tool call reaches your orchestrator. Streaming requests are buffered so no tool call leaves early. Evaluation stops at the first rule that blocks, in this order: tool gate, scope, tenant, write safety, so only that rule is reported. Run Shadow first to see all of them. Every call in a blocked response is recorded as blocked, and calls without a violation of their own are marked as collateral.

Edits reach the proxy within about 15 seconds. Agent-level shadow mode keeps working: it turns Enforce blocks into would-block records.

Default policy

  • strict_context: true.
  • allowed_scopes: session, user, agent. The organization scope is opt-in and by default needs provenance_verified: true in the call.
  • allowed_operations: write, read, search, update. delete and share are opt-in.
  • max_ttl_days: 365. A call whose ttl_days exceeds it fails. 0 rejects every call that sets ttl_days above zero, and calls without ttl_days still pass.
  • require_tenant_binding: false. A call that carries no tenant_id passes, because many backends scope the tenant server-side. Turn it on to fail such calls.
  • tool_operations: memory_store and memory_write are writes, memory_update an update, memory_search a search, memory_read a read. A memory tool that is not mapped is denied by the tool gate.

What is checked

  • memory_tool_gate: only mapped memory tools and allowed operations.
  • memory_scope_policy: a scope on every call, allowed scopes, the TTL ceiling, organization provenance, valid JSON arguments, and calls that address another user or session than the caller.
  • memory_tenant_isolation: every tenant reference must equal X-VG-Memory-Tenant-Id exactly (case-sensitive). References are found at any depth: filter.tenant_id, arrays, camelCase spellings (tenantId, org_id, organizationId) and JSON embedded in string values, including double-encoded payloads. The reason names the field path and never repeats the foreign value.
  • memory_write_safety: prompt injection, PII and secrets in write, update and share payloads, including current provider keys (sk-proj-…, GitHub tokens), bearer tokens and JWTs, labelled credentials such as password=…, PESEL numbers with a valid checksum, and Polish phone numbers with a country code or separators. Identifier fields are not scanned.

Every call in a response is checked, including responses that carry both text and tool calls. Preview a draft policy on sample tool calls before saving it.

Audit

Memory governance (Growth+) lists every call with filters for period, agent, decision and rule, plus a CSV export of the same filters. Request detail shows the per-call decisions for that request.