Commands

Command Reference

These commands are typed into the conversation itself and work on both the proxy path and the REST path. They are detected case-insensitively and intercepted before the request reaches the model.

VCATTACH

VCATTACH <label-or-id>

Reattach the current session to another stored conversation. This is the mechanism for cross-platform memory: build context in one client, then attach from another and both enrich the same conversation.

How it works. VCATTACH writes a durable alias redirecting the current conversation identity to the target. Later requests arriving under the old identity resolve through the alias, so retrieval, compaction and new turns all operate on the target. The old conversation is not deleted; its identity simply routes to the target from then on. Stale markers in older assistant responses keep working because they follow the alias chain.

Attaching is a redirect, not a merge. It does not copy segments or facts between conversations. To combine two conversations’ stored data, use VCMERGE.

Typical uses are cross-platform continuity, several agents sharing one fact base and topic index, and recovering a conversation after its identity detaches through a system prompt change, client truncation or redeploy.

VCLABEL

VCLABEL MyProjectName

Give the conversation a human-readable name, used by VCLIST and the dashboard sessions panel. The label is stored as session metadata and survives restarts on durable storage. Calling it with no argument reports the current label.

VCSTATUS

Reports conversation ID and label, turn count and compaction watermark, context window fill, stored segment count and total tokens, the active working set, and all known tags in the store. The output is structured text the model can relay directly.

VCRECALL

VCRECALL the database migration discussion

Runs lexical and semantic search over stored conversation text, reports the matches, and promotes up to five matched tags into the working set so the next turn’s assembly includes them.

VCCOMPACT

Runs the same compaction pipeline that fires automatically at thresholds, but immediately. Useful before a long stretch of work when you want budget freed up front. Protected recent turns are still preserved.

VCLIST

Lists stored conversations with their labels and turn counts.

VCFORGET

VCFORGET <tag>

Permanently deletes the segments and summaries stored under a tag, for topics that are stale or sensitive. The argument must be an existing tag name, matched case-insensitively; if it is not found, the response lists the available tags.

VCMERGE and VCMERGESTATUS

Where VCATTACH redirects, a merge moves the source conversation’s stored data into the target. VCMERGE PREVIEW <target> previews the operation and VCMERGESTATUS reports progress.

In the standalone proxy these commands are recognized but fail closed with an explanatory message rather than executing, because merge execution requires a deployment that intercepts the command ahead of the proxy, such as the hosted service. Failing closed is deliberate: a merge must never be silently dropped, nor forwarded to the model as ordinary text.

Detection

Commands are matched in the user message text. Detection is case-insensitive, so any capitalization works. The command and its argument must form the whole message, aside from transport metadata the proxy strips automatically. Detection runs on both the proxy path, streaming and non-streaming, and on direct REST calls.

Importing Conversation History

The import command ingests conversation exports from other assistants into the store, so someone migrating to virtual-context arrives with their history already indexed, tagged and retrievable.

virtual-context import --provider chatgpt --input conversation.json
virtual-context import --provider claude  --input ~/exports/     # every *.json inside
virtual-context import --provider grok    --input export.json --compact

--provider is required and takes chatgpt, claude or grok; each adapter parses that service’s native export JSON. --input is required and takes either a single export file or a directory, whose *.json files are imported in sorted order, with empty files skipped and counted. --compact runs compaction after the import; without it, imported turns are ingested and tagged and summarization happens later through the normal thresholds.

Each imported conversation keeps its own ID from the export, so separate source conversations stay separate in the store.

CLI Reference

The virtual-context command line is a separate surface from the in-conversation commands above.

Admin Subcommands

virtual-context admin hosts guarded operational commands for backfilling and repairing stored data. They operate directly on the store, support explicit database targeting, and are designed to be idempotent. Run virtual-context admin <subcommand> --help for the flags each takes.

Common admin flags

Two opposite safety models exist across these commands. Know which one you are invoking. Assuming the wrong one either writes when you expected a report, or reports when you expected a write.

• Write by default, take --dry-run to report instead: backfill-senders, backfill-channels, backfill-actors, backfill-reply-roles, backfill-fact-authors, rebuild-actor-cards, retag-canonical-turns, backfill-session-state-markers.
• Dry-run by default, take --apply to write: reattribute-audience, rebuild-derived-data, resummarize-segments, resequence-canonical-turns, normalize-canonical-actor-ids, reindex-canonical-turn-embeddings.
• backfill-tag-summaries and backfill-fact-embeddings take --force-rebuild to regenerate rows that already exist.

Storage resolution precedence: an explicit storage flag beats -c, which beats the DATABASE_URL environment variable. The environment fallback is consulted only when neither a storage flag nor a config was given, so a bare invocation works inside a container that has the environment set and no config file mounted.

Other notable flags

retrieve and transform take -m for the inbound message and --active-tags to simulate a working set, with transform also accepting --budget. recall takes --limit. init takes --force to overwrite an existing config.