Use Vornik from any agent¶
Any agent that speaks MCP can use Vornik's project memory (recall,
remember) and hand work to it (delegate, result), with no Vornik
plugin. Claude Code and Codex have plugins; Claude Desktop, Cursor and
opencode have their own guides (Claude Desktop,
Cursor, opencode). This page is for the rest:
Gemini CLI and others, and opencode set up by hand.
What works, measured. On 2026-11-20, Gemini CLI 0.41.2 and opencode 1.14.37, set up as below, each completed remember, recall, delegate, result and memory_correct against Vornik 2026.11.7, in about 100 seconds.
What you do not get. No session digest when a session starts, and no hooks: the agent learns what to do from the instructions you add in step 4.
What you need¶
- A companion key,
sk-vornik-…, minted with a default repo scope. An operator mints it on the Vornik host:
vornikctl companion grant --project=<project> --client=<your-agent> \
--label="$(hostname)/$USER" --memory-all --skill-read \
--workflows=companion-research-gather,companion-report-summarize \
--budget-usd=10 --repo-scope=github.com/ORG/REPO
--repo-scope matters here. An agent without Vornik hooks passes no
repo scope, so without a default every note it stores is unscoped, and
scoped recalls in other sessions may not find it.
- vornikctl on the machine where your agent runs.
1. Store the key and print the entry¶
printf '%s\n' "$VORNIK_COMPANION_TOKEN" | \
vornikctl companion connect generic --print --key-stdin --url https://vornik.example
It checks the key, stores it in a file only you can read, and prints two MCP entries to paste. The key is never printed. It warns when the key has no default repo scope.
- Form 1 runs
vornikctl companion mcp-bridge, which reads the key from that file. Use it when your agent can start a command. - Form 2 is streamable HTTP, with the key read from the
VORNIK_COMPANION_TOKENenvironment variable. An agent started from a desktop does not read your shell profile.
2. Add the entry to your agent¶
Formats as measured on 2026-11-20. Your agent's version may differ: check its own MCP documentation.
Gemini CLI 0.41.2, in .gemini/settings.json (the project) or
~/.gemini/settings.json:
{
"mcpServers": {
"vornik": {
"httpUrl": "https://vornik.example/api/v1/mcp/companion",
"headers": { "Authorization": "Bearer ${VORNIK_COMPANION_TOKEN}" }
}
}
}
- Gemini CLI ignores a project's settings until you trust the folder. Run
geminionce in it and accept, or setGEMINI_CLI_TRUST_WORKSPACE=truefor a headless run. - On the free tier, 0.41.2's default model routing failed: it asked for a
retired model, then for one with no free quota. Pass a model,
gemini -m gemini-3.5-flash, or upgrade the CLI.
opencode 1.14.37, in opencode.json (or let vornikctl companion
connect opencode write a stdio entry, with Vornik's rules, a session digest
and skills: opencode):
{
"mcp": {
"vornik": {
"type": "remote",
"url": "https://vornik.example/api/v1/mcp/companion",
"headers": { "Authorization": "Bearer {env:VORNIK_COMPANION_TOKEN}" }
}
}
}
Any agent that starts a command: paste form 1 from step 1.
3. Check the connection¶
vornikctl companion doctor --client generic --url https://vornik.example
One line per check: the key file, the daemon, the key itself, and its repo scope. It says which key the bridge uses. It cannot see your agent's own settings or environment.
In your agent, list its MCP servers (gemini mcp list, opencode mcp list):
Vornik should show as connected.
4. Tell your agent how to work with Vornik¶
vornikctl companion instructions --write AGENTS.md --url https://vornik.example
(Or export VORNIK_URL once, and leave out --url in every command.)
This writes Vornik's working rules into your AGENTS.md, between
<!-- vornik:start --> and <!-- vornik:end -->. Running it again replaces
that section and leaves the rest of the file alone. The rules come from your
Vornik, so they match its version. They also say two things an agent
without hooks needs:
- call
recent_memorywhen a session starts; - your agent shows Vornik's tools under a prefix: Gemini CLI as
mcp_vornik_recall, opencode asvornik_recall. In one test a small local model (9B parameters) calledrecallwithout the prefix, was refused, and stopped.
Without --write, the command prints the text for an agent that reads its
instructions from somewhere else.
- opencode reads
AGENTS.md. - Gemini CLI reads
GEMINI.mdby default (per its documentation; not measured here). Write there with--write GEMINI.md, or add"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}to its settings.
Skills. The companion skills (how to configure, troubleshoot and
delegate) are Agent Skills folders in the public repository,
contrib/claude-code-companion/skills/. Copy them where your agent reads
skills, if it reads any.
5. Try it¶
Ask your agent to store a test note in Vornik, recall it, and then refute
it. To check the same path without an agent, run the round trip in
AGENTS.md,
Runbook B4.
Disconnect¶
vornikctl companion disconnect generic
It deletes the key file. Remove the entry from your agent's settings
yourself. The key stays valid until the operator revokes it
(vornikctl key revoke <id> --project=<project>).