AI intelligence

vTilt continuously distils raw events, sessions, conversations, and recordings into structured intelligence. That layer — AI memory — is exposed to your MCP client as five virtual tables you can read through VQL (run_query), plus two dedicated tools (query_ai_memory, get_person_memory) for cases where SQL is the wrong shape.

There is no separate "AI search" tool. Vector semantic search is part of VQL via the :embed('text') macro and the cosineDistance family. The point is composability: combining "find me semantically similar sessions" with "where person is on the enterprise plan and signed up via Twitter" is one query, not two.

#The catalog

run_query and validate_query accept SQL against the following AI memory tables alongside the existing analytics core (events, persons, person_distinct_ids, person_overrides). Call get_query_schema to see the curated column list for each — the column descriptions list the hot ai JSON keys so you don't have to guess what's inside the blob.

#Site knowledge tables (customer website corpus)

Indexed from HTTP crawl + session recordings — not AI memory, but the same :embed('text') pattern. For crawl pipeline, dashboard controls, and when to use site knowledge vs replay transcripts, see Site knowledge. For MCP tools and example queries, see Site knowledge (MCP).

Every table is tenant-scoped automatically — project_id filtering happens server-side. Don't add it to your WHERE clause.

The ai column is JSON. Read keys with JSONExtractString(ai, 'intent_level') / JSONExtractInt(ai, 'engagement_score'). The most-used keys are hoisted in each table's get_query_schema description so you can plan a query without a second round trip.

#Vector semantic search — the :embed('text') macro

VQL exposes a single macro, :embed('your search phrase'). The compiler generates the query embedding once per distinct literal, deduplicates identical calls, and substitutes a native ClickHouse parameter — the float array never appears in the SQL string (so it doesn't bloat your logs or the wide-log).

SELECT
  session_id,
  narrative,
  JSONExtractInt(ai, 'engagement_score') AS engagement,
  cosineDistance(embedding, :embed('rage clicks on checkout')) AS distance
FROM session_summaries
WHERE started_at > now() - INTERVAL 30 DAY
ORDER BY distance ASC
LIMIT 20

Two rules you cannot break:

1. :embed() takes a string literal only. :embed('hot leads') is fine; :embed(some_column) is rejected with embed_invalid_argument. The literal cap is 2 000 characters — past that you get embed_text_too_long. This is deliberate: it stops agents from accidentally embedding a 50 KB blob and burning $0.40 of inference per query.
2. Pair cosineDistance(... :embed(...)) with ORDER BY ... LIMIT N. That's the only pattern that hits the HNSW vector index. A bare WHERE distance < 0.3 predicate causes a full table scan and will hit the 50 M-row read cap on a busy project.

The macro is supported on every embedding column in the catalog (session_summaries, conversation_summaries, recording_summaries, recording_chunks, person_memory_latest).

#Combine vector similarity with filters and joins

This is why the macro lives inside VQL. Compose semantic similarity with whatever WHERE / JOIN you'd write for a normal analytics query:

SELECT
  s.session_id,
  p.public_id,
  JSONExtractString(p.properties, '$initial_utm_source') AS first_utm,
  cosineDistance(s.embedding, :embed('confused about pricing')) AS d
FROM session_summaries s
JOIN persons p ON p.public_id = s.person_id
WHERE JSONExtractString(p.properties, '$initial_utm_source') = 'twitter'
  AND s.started_at > now() - INTERVAL 7 DAY
ORDER BY d ASC
LIMIT 25

Or join two AI memory tables:

SELECT
  r.session_id,
  r.engagement_score,
  r.behavior_pattern,
  JSONExtractString(s.ai, 'sentiment') AS session_sentiment,
  cosineDistance(r.embedding, :embed('deep reading documentation')) AS d
FROM recording_summaries r
JOIN session_summaries s ON s.session_id = r.session_id
WHERE r.engagement_level IN ('deep-read', 'read')
ORDER BY d ASC
LIMIT 20

#Cross-table semantic search

When you want one ranking across multiple tables, use explicit UNION ALL:

SELECT 'session' AS source, session_id AS id,
       cosineDistance(embedding, :embed('integrating with our API')) AS d
FROM session_summaries
UNION ALL
SELECT 'conversation', channel_id,
       cosineDistance(embedding, :embed('integrating with our API'))
FROM conversation_summaries
ORDER BY d ASC LIMIT 30

The two :embed('integrating with our API') calls deduplicate to one embedding API call — the compiler caches identical literals per query.

#Natural-language Q&A — query_ai_memory

When the question is fuzzy and you don't yet know which tables / filters to use, call query_ai_memory instead of guessing a VQL query. The server:

1. Classifies the intent (person snapshot, semantic similarity, lifecycle funnel, cross-table correlation, …).
2. Generates parameterised ClickHouse SQL from a deterministic template per intent.
3. Executes the SQL.
4. Synthesises a prose answer with the project's allowed model tier.

The response contains the synthesised answer, the underlying sql, the raw rows, the intent the planner inferred, and the synthesisModelUsed. The SQL is there so you can iterate via run_query for a different cut, or verify the planner reasoned correctly.

// query_ai_memory({ question: "Who are the hottest leads from Twitter this week?" })
{
  "question": "Who are the hottest leads from Twitter this week?",
  "answer": "Three persons stood out — …",
  "intent": { "target": "person_current", "filters": { "intent_level": "hot" }, ... },
  "sql": "SELECT person_id, ... FROM person_memory_latest FINAL ...",
  "rows": [ ... ],
  "synthesisModelUsed": "openai/gpt-4o-mini"
}

#Canonical person snapshot — get_person_memory

The single most common AI memory question is "tell me everything we know about this person". get_person_memory is the optimised read for exactly that: the latest person_memory_latest row with the hot ai JSON fields hoisted to top level.

// get_person_memory({ id: 'person_abc' })
{
  "personId": "person_abc",
  "version": 7,
  "changedAt": "2026-05-14T13:15:42Z",
  "triggerType": "session_summary",
  "intentLevel": "hot",
  "lifecycleStage": "MQL",
  "engagementScore": 78,
  "recommendedAction": "Schedule a demo — buying signals on pricing page",
  "keyFacts": ["5-person team", "Compares us with PostHog and Mixpanel"],
  "topicsOfInterest": ["session replay", "GDPR", "self-host"],
  "summary": "...",
  "chatSummary": "...",
  "ai": {
    /* full structured blob */
  },
  "sessionsSummarized": 12,
  "conversationsSummarized": 3,
  "modelUsed": "openai/gpt-4o-mini"
}

For everything else on persons — history of all versions, everyone-in-stage-X queries, lifecycle funnels — use run_query against person_memory_latest (or join it with persons for property filters).

#When to use which surface

#Error codes

The macro adds three codes on top of the existing VQL error taxonomy:

The full existing VQL error catalog (parse_error, unknown_table, unknown_function, unsupported_construct, permission_denied, invalid_project) still applies. Self-correction loops: validate_query is free — call it first to fix structural errors before paying for run_query. validate_query also reports embedCount so you can see how many embedding API calls a query will cost before you run it.

#Cost model

Every embedding + LLM call writes a row to ai_usage_log with the operation, model, and token counts so you can audit spend per project.

#Related

• Agent skills (prompts) — slash-command walkthroughs. The /vtilt:ai-memory slash command is the agent's quick-reference version of this page.
• Authentication — how to get a personal API key for MCP.
• OAuth — browser-flow auth for Claude Desktop / Cursor / ChatGPT Connector.