Vss Search Archive

Search archived VSS video

When to Use

• Search archived VSS video that is already registered in a configured deployment, by natural-language, similarity, attribute, object-ID, or lexical tag query.

Not for:

• A fresh visual question about a supplied local clip — vss-ask-video.
• Long-form summarization of a recording — vss-summarize-video.
• Deploying or changing a profile — /vss-build-vision-ai.
• Ingesting or deleting a source — use the deployment's source-management workflow.

Answer from the configured deployment through the installed vss CLI. Do not fall back to raw REST when a CLI command fails.

Hard rule — use the vss CLI for retrieval. vss configure has already pointed the CLI at the deployment, so every search action goes through vss search run and nothing reaches the deployment any other way.

Four things follow:

• use the vss on PATH (see Prerequisites); never docker exec, kubectl exec, a pod shell, or a hand-built /api/v1/search call;
• a named source is resolved with vss vios list before search — never inferred from a display name, and never substituted when missing;
• capture stdout and the exit status separately — never put the command behind if !, which hides the real exit code, and never discard usable exit-6 results;
• a failing command is a finding: report the exit code rather than routing around it, repairing the deployment, or retrying with broadened scope.

Prerequisites

• A running VSS search profile with vss configure already run against its origin. Refresh configuration after first ingestion, once source provisioning has established readiness; lazy raw indexes enable frame enrichment for attribute/fusion.
• The vss CLI on PATH. The OpenClaw and Hermes harness images ship it; anywhere else, install it from the same checkout as this skill so the CLI and the skill match: uv tool install <checkout>/libs/vss/cli.

Bootstrap, exit codes, and common CLI rules live in AGENTS.md.

Source management handoff

For an explicit request to ingest or delete a source, use vss-manage-video-io-storage for vss vios add or vss vios delete, then return to archive search once the source is available. The deployment's mounted notification config owns consumer fan-out; the presence of an Agent tier does not change the VIOS registration path. Check the requested receiver as enabled, absent, or unknown under source management's policy contract. With an enabled receiver, use fan-out; with confirmed absent lifecycle support, report that limitation. Only an explicit tagging request with a confirmed absent streaming tagging receiver and the provisioning prerequisites may use manual tagging. With unknown policy, report unconfirmed fan-out, never unavailable indexing, and do not start manual tagging. If the user only asks to search a named source and it is missing, do not ingest, switch videos, or run an unrestricted search — answer with the reply Search workflow step 1 specifies for zero matches. If no supported source management workflow is available, report that blocker.

Search workflow

1. Resolve a named source. If the request names a file, camera, or sensor, resolve it with vss vios list (it reads the origin vss configure recorded, so it takes no endpoint). Accept an exact name or sensor ID, or one unambiguous normalized match; stop on zero or multiple matches. The listing is {"count", "type", "sensors": [...]}; preserve the matched entry's .sensors[].name and .sensors[].sensor_id, and never infer an identifier from the display name. Below, .name and .sensor_id mean those fields.

Stopping is not the whole answer — the reply has to hand the decision back. On zero matches, the final reply states all three of:

• the requested name is not registered;
• the sources that are registered, from the listing;
• a request that the user clarify which source they meant, or explicitly ask for the missing one to be ingested.

The third is as required as the first two. Refusing to substitute is correct but incomplete: a reply that reports the mismatch and then stops leaves the user with no stated next step. Ingesting, switching to another video, or dropping the source filter and searching everything are all still forbidden (see Source management handoff). On multiple matches, name the candidates and ask which one.

2. Choose one retrieval path. Preserve the user's exact original sentence for --original-query first — critic verification must receive that wording, while retrieval may use the decomposed query, attributes, or object IDs. Then choose exactly one path:

• object — explicit tracked object IDs;
• tag — explicit lexical tag/keyword intent (BM25 over indexed VLM tags), not semantic free text;
• attribute — detectable properties only, no action or relation;
• fusion — a detectable property combined with an action or relation;
• otherwise embed — semantic free text.

--attribute is for properties RT-CV detects on a subject (attire, PPE, color-on-person), not object identity or an object's own color — keep red forklift wholly in --query. worker in a hard hat carrying a cone has a property (hard hat) and an action (carrying a cone): run fusion. Reserve embed for genuinely attribute-free intent, and tag for keyword/tag queries that name no detectable property.

The --video-source value differs by path while the CLI's paths need different identifiers:

For every path an unknown source yields an empty, narrowed result, not an error.

Before attribute or fusion, inspect vss configure show's services.elasticsearch.indices. If no entry starts with mdx-raw-, refresh once with vss configure --base-url using that same record's nonempty base_url, then inspect again. Stop on a configuration failure; if the raw family is still absent, disclose that frame enrichment is unavailable and continue the requested retrieval. Do not construct an origin or poll indexes.

3. Invoke the CLI. Use --query for embed/fusion/tag, repeatable --attribute for attribute/fusion, and repeatable --object-id for object. Use --timestamp-start / --timestamp-end for time bounds. Set --source-type video_file for an uploaded recording or rtsp for a live stream. Source type selects the fixed uploads anchor or the live family wildcard excluding that uploads anchor, independently of source identity and ingestion order. Carry the requested time bounds and --top-k, and run vss search run <path> with no endpoint, index, model, or profile flag — vss configure owns those. Build the invocation as a Bash array and capture stdout and the exit status separately; never clear a previously resolved source array or hide the exit code behind if !: