Documentation menu
Reference

Private values and local variables

Knowledge-base text is read by every agent and every member of the workspace, and it can be exported or published. Identifying values do not belong in it. Kvendra gives you two kinds of reference instead of the literal value:

  • a private value, {{cfg:<key>}} — a fact of the project, stored once in the knowledge base;
  • a local variable, {{lvr:<key>}} — a fact of one user on one machine, never stored in the knowledge base.

Keys follow [a-z0-9][a-z0-9._-]{0,127}. Credentials are neither: they go into the CLI vault, never into a knowledge-base entry.

Both are features of the hosted service. Local variables also need the CLI (0.7.0 or later) on each machine.

Private values

Use them for identifiers that must not appear in text — account ids, local paths, profile ids, person names, case numbers. Each is stored once as a CFG private value; everything else refers to it.

  • Write references, never literal values. Enter the value once, ideally from the dashboard editor so it never passes through a language model.
  • Reads never resolve. entity_get, entity_query, entity_search, entity_related and the export return references raw and list them in private_refs. Edit the text and write it back as-is.
  • Resolve only to operate, with config_get or: 
private_value_resolve({ keys: ["<key>", ...], project_id })   // 1–50 exact keys

Resolution needs the cfg:resolve permission, is audited per request (keys and counts, never values) and is served with Cache-Control: no-store. Use the value for the operation and never paste it back into text.

Writes are checked. Text carrying an unescaped display marker is rejected with 400 private_marker_in_text; to mention the syntax literally, escape it with a leading backslash. Two warnings help you keep text clean: private_value_suggested (this looks like a value that should be a reference) and private_ref_undefined (the key you referenced does not exist).

Local variables

Use them for what differs per machine: your workspace path, the AWS profile of this laptop, a local host or port.

  1. Declare the variable in the knowledge base as a CFG with metadata: { kind: "local_var", key, type, description } and no value. type is one of path, host, port, profile_id, string.
  2. Set the value on each machine, by a human in a real terminal: kvendra vars set <key> --type <type>. It lives only in that machine's local vault.
  3. Reference it as {{lvr:<key>}} only where the broker consumes it — a working directory, a profile id, a bounded argument, a URL. The local broker substitutes it inside its primitive, validates it by type and masks it in its output.

The engine never has the value. Referencing a key with no declaration returns the warning local_var_undeclared. When content is published, each local reference is replaced by a placeholder.