Memory (Beta)

Your users comment on and review work inside your app. Memory records every one of those decisions, plus the ones your AI agents make. Add your own guidelines on top, then query all of it over REST.

How it works

Reviews become judgments

Every review decision your users make in your app is recorded as a judgment: the decision, the reasoning, who decided, and what they decided on. This happens automatically. There is no “create judgment” endpoint.

You add knowledge

Ingest your guidelines, standards, and policy docs. Memory converts each file to markdown, extracts rules, and embeds it.

You query both

Use search for raw decision records, ask for a written answer with citations, and suggest for a recommendation on a new item.

Memory derives insights

Reviewer profiles, decision patterns, stats, and alerts build up from those judgments over time.

A new workspace starts empty. ask returns an empty answer with confidence: 0 until enough review history exists. Memory returns nothing rather than inventing an answer.

Quickstart

Every endpoint is a POST under https://api.velt.dev/v2/. The examples below read your API key and Auth Token from $VELT_API_KEY and $VELT_AUTH_TOKEN.

Add a knowledge source

Base64-encode a file and send it. Ingestion runs in the background and returns a sourceId.

curl -X POST https://api.velt.dev/v2/memory/knowledge/ingest \
  -H "x-velt-api-key: $VELT_API_KEY" \
  -H "x-velt-auth-token: $VELT_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "data": {
      "source": "inline",
      "file": {
        "base64": "'"$(base64 -w0 brand-guidelines.pdf)"'",
        "mimeType": "application/pdf",
        "fileName": "brand-guidelines.pdf",
        "fileSize": 184320
      }
    }
  }'
# -> { "result": { "status": "processing", "sourceId": "src_9a8...", "message": "Knowledge ingestion task enqueued." } }

Poll with that sourceId until status is completed or failed:

curl -X POST https://api.velt.dev/v2/memory/knowledge/ingest-status \
  -H "x-velt-api-key: $VELT_API_KEY" \
  -H "x-velt-auth-token: $VELT_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "data": { "sourceId": "src_9a8..." } }'
# -> { "result": { "status": "completed", "extractedRulesCount": 7 } }

Files up to 5 MB go inline. For files up to 30 MB, call Get Upload URL, PUT the bytes to the returned uploadUrl, then ingest with { "source": "fileRef", "fileRef": "<gs:// URI>", "mimeType": "..." }.

Ask a question

You get a written answer, the records it drew on, and a confidence score.

curl -X POST https://api.velt.dev/v2/memory/ask \
  -H "x-velt-api-key: $VELT_API_KEY" \
  -H "x-velt-auth-token: $VELT_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "data": { "question": "How do we handle copy that makes medical claims?" } }'

{
  "result": {
    "answer": "Reviewers reject copy that makes medical claims without a citation...",
    "citations": [ { "recordId": "act_8f3...", "snippet": "Claim 'clinically proven' lacks a citation." } ],
    "confidence": 0.74,
    "recordsSearched": 18
  }
}

Search past decisions

Use search when you want the underlying records instead of a written answer.

curl -X POST https://api.velt.dev/v2/memory/search \
  -H "x-velt-api-key: $VELT_API_KEY" \
  -H "x-velt-auth-token: $VELT_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "data": { "query": "unsupported medical claim", "limit": 5, "filters": { "decision": "rejected" } } }'

Each result carries the reasoning, decision, confidence, who decided (actionUser), and a similarity score.

Get a suggestion

Ask what Memory would recommend for a new item, based on precedent.

curl -X POST https://api.velt.dev/v2/memory/suggest \
  -H "x-velt-api-key: $VELT_API_KEY" \
  -H "x-velt-auth-token: $VELT_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "data": { "query": "Ad copy: clinically proven to reduce wrinkles" } }'

{
  "result": {
    "primary": { "recommendation": "reject", "confidence": 0.78, "basedOn": 12, "topReasons": ["Unsupported medical claim"], "caveats": [] },
    "conflict": null
  }
}

primary is the best-grounded recommendation. conflict is filled in when the evidence is split, so you can show that reviewers disagree.

Narrow your results

Add these fields to search and ask to control what Memory reads.

Field	What it does
`organizationId`	Limits the read to one organization.
`documentId`	Limits the read to one document. Applied only when you also send `organizationId`; without it the field is ignored and the read stays workspace-wide.
`limit`	`search` only. Caps results. 1 to 50, defaults to 10. `ask` sizes its own retrieval and ignores this field.
`filters`	Narrows by `decision`, `judgeType` (`human` or `agent`), `contentType`, `reviewerId`, or `dateRange`. `decision` matches the stored value exactly: `comment`, `resolve`, `approved`, `rejected`, `in_progress`, `agree`, `disagree`, `endorse`, `document_approved`, or `document_rejected`. `dateRange` is `{ start, end }` as either ISO-8601 strings or epoch milliseconds. `excludeDocumentIds` leaves out judgments from up to 20 named documents.
`filters.annotationId`	Reads one comment thread in chronological order. Requires `organizationId`.
`recencyDays`	Returns the last N complete UTC days of activity instead of a semantic match. 1 to 365. Good for digests.

All endpoints

Search and Ask

Search Judgments · Ask Memory · Suggest Decision · Query Judgments

Knowledge

Ingest · Ingest Status · Upload URL · Search · List · Rules · Update · Download · Delete

Insights

Reviewer Profile · Patterns · Stats

Alerts

List · Dismiss · Mark Actioned · Get Config · Update Config

There are two searches, and they read different things. Search Judgments reads past decisions. Search Knowledge Base reads the content of the files you ingested. Pass includeRules: true on the second one to search extracted rules too.

Good to know

Judgments are read-only. They come from your users’ review activity, so a new workspace has none until people start reviewing. Comments from older SDK clients are enriched into Memory too, including a one-time backfill of historical data.
Ingestion is asynchronous. ingest returns processing. Poll ingest-status until it is completed or failed.
Supported file types: PDF, CSV, Excel (.xlsx), and plain text.
File limits: 5 MB inline, 30 MB by reference.
Duplicate uploads report the original source’s status, so a duplicate can stay processing until the original finishes. completed always means safe to download.
Knowledge rate limits, per API key per minute: knowledge/ingest-status 600, knowledge/search 120, knowledge/upload-url 100, knowledge/ingest 30, knowledge/delete 30. Going over returns RESOURCE_EXHAUSTED, so keep bulk imports and status polling under those ceilings.

Errors

Status	Meaning
`INVALID_ARGUMENT`	The request failed validation, or the `x-velt-auth-token` header is missing.
`PERMISSION_DENIED`	The `x-velt-auth-token` is not valid for this API key.
`NOT_FOUND`	Unknown `sourceId`, or an `x-velt-api-key` that does not resolve to a workspace. `knowledge/download` is the exception: an unknown `sourceId` there returns `null` with a `200`.
`ABORTED`	Deleting a source that is still processing, or one that duplicate uploads point at. Poll `ingest-status` until the status is terminal, or delete the duplicates first.
`FAILED_PRECONDITION`	The signed upload URL expired before you called `ingest`, or you called `knowledge/update` on a source that is not rule-based.
`RESOURCE_EXHAUSTED`	Rate limited. Back off and retry.

On a validation error, every memory endpoint returns details.issues alongside message and status, listing each failing field. The most common INVALID_ARGUMENT causes:

filters.annotationId without organizationId.
documentId without organizationId on knowledge/ingest or knowledge/upload-url.
A dateRange whose start is after its end.
An unsupported file type, or an inline file over 5 MB. Use Get Upload URL for larger files.
An unrecognized field on knowledge/ingest, knowledge/upload-url, knowledge/ingest-status, knowledge/delete, or knowledge/search. These five reject unknown keys, so a typo like bas64 fails instead of being ignored. knowledge/search is workspace-wide and rejects organizationId and documentId.

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Memory (Beta)

How it works

Quickstart

Add a knowledge source

Ask a question

Search past decisions

Get a suggestion

Narrow your results

All endpoints

Search and Ask

Knowledge

Insights

Alerts

Good to know

Errors

​How it works

​Quickstart

Add a knowledge source

Ask a question

Search past decisions

Get a suggestion

​Narrow your results

​All endpoints

Search and Ask

Knowledge

Insights

Alerts

​Good to know

​Errors

How it works

Quickstart

Narrow your results

All endpoints

Good to know

Errors