Agents, knowledge & memory¶

An agent is an AI assistant that works inside your instance: it can answer questions about your records, create and update them on request, and carry out small tasks for you. Two companion features make agents more capable — a knowledge base gives an agent reference material it can look things up in, and memory lets an agent remember durable facts about your business and bring them into later conversations.

Like everything else in Victor, all three are ordinary records rendered by the framework — there are no bespoke screens to learn. This page walks through them from a user's point of view. To build your own agent in a module, see Building agents; to find your way around the app in general, see Navigating the app.

Agents: assistants that work with your records¶

Every agent configured in your instance is listed under Settings → Agents. Victor ships a built-in Front Desk assistant, and any app you install can add its own — a helpdesk app might add a Support Assistant, for example.

An agent is defined by a handful of settings, all visible on its form:

Setting	What it does
Model	Which language model powers the agent, written as `provider:model-id` (e.g. `anthropic:claude-sonnet-4-6`).
Thinking level	How much the agent deliberates before answering: `Off`, `Low`, `Medium`, or `High`. Leave it `Off` for quick responders; raise it for agents that plan multi-step work.
Prompt	The agent's instructions — a plain-language job description of what it is for and how to respond.
Tools	The actions the agent is allowed to take (read records, create a record, send an email, and so on). See Tools.
Skills	Reusable instruction sets the agent can draw on for a procedure or policy. See Skills.
Subagents / Capabilities	Other agents this one can hand work to (advanced).

Which agents you can edit

Agents that come from an installed app are shown read-only — the app owns them. Agents you create yourself in Settings → Agents are fully editable. Either way, edits take effect on the agent's next run — there is nothing to redeploy.

Starting a conversation¶

You interact with an agent through a conversation — a back-and-forth thread. You send a message, the agent replies, and you keep going; the agent keeps the context of the whole thread, so later messages can refer back to earlier ones. The Front Desk agent is the front-door assistant your users talk to; specialist agents are usually reached through it rather than directly.

What an agent can actually do in a conversation depends on the tools it has been given. They fall into three broad kinds:

Answer questions — read-only tools let the agent look things up. The built-in Front Desk can search your contacts (search_contacts); a helpdesk agent might read tickets (read_records). Ask "Which open tickets belong to Acme?" and it searches and summarizes.
Create and update records — tools like create_record and update_record let the agent change data on your behalf: "Open a ticket for Acme about a failed login."
Run tasks — other tools let it act, such as send_email to draft and send a message.

A short helpdesk exchange might look like this:

You:    Any open tickets for Acme?
Agent:  Two are open: #1043 "Failed login" and #1051 "Invoice question".
You:    Close #1051 and email the customer that it's resolved.
Agent:  I'll update ticket #1051 to resolved and send a note to the customer —
        please approve the two changes below.

The exact tools an agent has are listed on its form; the full catalog your instance offers lives under Settings → Tools.

When an agent wants to make a change: approvals¶

Reading data is always allowed, but anything that changes data or sends something — creating a record, updating one, sending an email — pauses for a person to approve it first. When the agent decides to run such an action, the conversation stops and shows you what it wants to do. You then either:

Approve — the action runs and the agent continues, or
Reject — the action is skipped; the agent is told you declined and can respond accordingly.

This keeps a human in the loop before an agent ever writes to your instance or reaches the outside world. Read-only questions never pause.

Giving agents reference material: the Knowledge base¶

An agent knows about your records out of the box, but often you also want it to answer from documents — support articles, policies, product manuals. That is what the Knowledge app is for. Install it and you get a place to manage knowledge bases and the documents inside each one.

A knowledge base is a named collection of documents. Its name is the key an agent uses to look things up, so keep it short and stable (e.g. support). A document in a base can be either:

Text you type or paste directly, or
A file you upload — .txt, .md, .pdf, and .docx are supported.

A new document starts as pending and is not searchable yet — Victor does not process it automatically. To make it findable, click the Reindex button on the document: Victor reads its text and processes it so agents can search it by meaning. The document then moves processing → ready; once it is ready an agent can find it. If processing fails the document shows error with a message, and you can re-run it any time with the same Reindex button.

Letting an agent use a knowledge base¶

A knowledge base is just a library — an agent only searches it if you give it the search_knowledge tool. Add that tool to the agent (on its form under Settings → Agents, or in a module-defined agent's tools list), and it can pull the most relevant passages from a base to ground its answers:

from victor import agents


class SupportAssistant(agents.Agent):
    name = "support_assistant"
    label = "Support Assistant"
    model = "anthropic:claude-sonnet-4-6"
    instructions = "Answer support questions using the 'support' knowledge base."
    tools = ["search_knowledge"]

Now when a customer asks "How long is the refund window?", the agent searches your support base for the passage that answers it, instead of guessing. Search is by meaning, not exact keywords, so a question worded differently from the document still matches.

Keep documents current

Editing the source of a document does not re-process it automatically — click Reindex after a change so the agent searches the new text. See Administering your instance for where installed apps like Knowledge appear.

What an agent remembers: Memory¶

Beyond a single conversation, Victor can remember durable things about your business and bring them into future conversations automatically. The Memory menu has two views:

Episodes — a read-only history of every exchange your agents have had. Use it to look back at what was asked and answered.
Facts — the curated things Victor knows about your business, and the part you actively manage.

Facts¶

A fact is one durable statement. Each has:

Field	Meaning
Statement	The thing to remember, in plain language.
Kind	`fact` (something true), `rule` (a policy to follow), or `preference` (how someone likes things done).
Scope	`company` (applies to everyone) or `user` (personal to one person).
Confidence	A 0–100 score for how sure Victor is.
Status	`draft` while awaiting review, then `active` (in use) or `rejected`. A fact can also become `superseded` when a newer fact replaces it.

You don't have to write facts by hand. After conversations, Victor reviews what was said and proposes draft facts for you. You review each one in Memory → Facts and either Confirm it (it becomes active and Victor starts using it) or Reject it (kept for the record, never used). You can also add a fact yourself — it lands as a draft and needs confirming like any other. When a new fact is meant to replace an older one, confirming the newer version marks the old fact superseded so only the current statement stays in use.

Once a fact is active, Victor recalls the ones relevant to the current conversation and takes them into account — so a rule like "Refunds are allowed within 30 days of purchase" shapes how the helpdesk agent answers, without you repeating it every time.

Company vs. personal scope¶

Scope controls who a fact affects:

Company facts apply to every conversation — shared truths and policies about your business.
User facts are personal to one person. A user preference — say "Reply in short, bulleted answers" — only shapes how Victor talks to that person in their own conversations. It never leaks into work done for someone else or into company-wide output.

Memory builds up over time

Nothing becomes a remembered fact until a person confirms it, so Memory stays curated rather than accumulating noise. Review the draft facts in Memory → Facts periodically to decide what Victor should carry forward.

If you want an agent to actively look up company facts mid-conversation (rather than only having the relevant ones recalled for it), give it the search_memory tool the same way you add search_knowledge.

Tuning agents without touching code¶

Because every agent is an editable record, an operator can adjust one from Settings → Agents — change its prompt, swap its model, raise its thinking level, or add a tool or skill — and the change takes effect on the next run. Two instance-wide System Parameters let you override every agent at once, which is handy for switching the whole instance to a cheaper or faster model while testing:

System Parameter	Effect
`agent.model`	Forces every agent's model. Leave unset to use each agent's own.
`agent.reasoning`	Forces every agent's thinking level (`off` / `low` / `medium` / `high`).

Set these under Settings → System Parameters; see Administering your instance for that tab.