Vault Operator

Attachment Lifecycle

Files dropped into the chat are parsed once and available for the current turn only. From the next turn onwards, the parsed text is removed from the immediate context.

Best Practice for Multi-turn Workflows

If you need an agent to operate on an attachment across multiple turns (e.g., a deep ingestion task), do not rely on the chat attachment. Instead:

1. Save the file to the vault first.
2. Instruct the agent to work against the specific vault path.

Vault Operator organizes capabilities into four distinct buckets within the Skills tab in Settings. While they are managed differently, the agent treats all of them uniformly at runtime by loading them into the system prompt based on relevance.

To prevent large tool outputs from bloating the conversation history, the ResultExternalizer automatically manages results exceeding 2,000 characters.

How it works:

1. Results > 2,000 characters are written to a temporary file in .vault-operator/cache/tmp/{taskId}/.
2. The conversation history is updated with a compact, tool-specific summary instead of the full raw data.
3. The summary includes a path that the agent can use to retrieve the full content if needed.

Example Summary Format:

[search_files] Found 42 matches.
Top files:
  - notes/foo.md
  - notes/bar.md
...
Full results saved to: .vault-operator/cache/tmp/<taskId>/search_files-3.md
Use read_file("...") to see all matches with context.

If the agent requires the full data, it should use the read_file tool with the provided path.

The ToolRepetitionDetector prevents the agent from getting stuck in infinite loops by monitoring tool calls.

• Mechanism: It maintains a sliding window of the last 15 calls.
• Blocking Criteria:
  • If an identical tool:input combination appears 3 or more times.
  • For search tools, if queries have a Jaccard overlap above 0.5 and appear 3+ times.
• Recovery: When a loop is detected, the call is blocked with a recoverable error. This allows the agent to receive the error message and attempt a different strategy. If the agent continues to fail, the consecutiveMistakeLimit in AgentTask acts as a final safety net.

Two runtime safety mechanisms are available to restrict agent behavior:

1. Paranoid mode ("Always ask"): A persisted override. When enabled, the pipeline requires manual approval for every effect except read and ui, ignoring all other toggles, presets, or existing grants.
2. Approval timeout: If an approval card is not answered, the request is automatically denied. The default timeout is 10 minutes, which can be configured via advancedApi.approvalTimeoutMinutes (set to 0 to wait indefinitely).

During Step 2 of a Deep Ingest, you must select an output mode. The agent defaults to conservative modes.

Available Modes:

• source-plus-summary: Creates one dense note covering all chosen topics. Each take-away includes a block-ref to the source.
• source-plus-multi-zettel: Creates one bibliography note plus multiple atomic notes (Luhmann-style). Best for material that should be split into separate ideas.
• source-only: Writes a clean source note and the triage card, but keeps the take-aways in the chat dialog. You can create detailed notes for specific aspects on demand later.
• Stop: Ends the workflow without writing anything (the triage decision is still logged).

Recipes are vetted calls to external CLI programs (e.g., Pandoc export) that the agent can run using the execute_recipe tool. They use fixed, validated parameters to ensure safety.

Comparison with other customization methods:

• Rules: Standing instructions present in every conversation.
• Workflows: Step-by-step instructions inserted per message via a /command.
• Recipes: Specific, validated external tool executions.

Instead of simple filename searching, Vault Operator uses a local semantic index to find notes based on their meaning. It traverses wikilinks and frontmatter to surface connections.

Configuration: The semantic index is opt-in. You can configure it to build:

• Never (default)
• On startup
• On agent switch

Example prompt: "Find all notes related to behavioral economics and show me how they connect."

Vault Operator manages memory via a configurable soft token budget in the system prompt.

• Hot Memory: The ContextComposer fills the system prompt budget greedily using Reciprocal Rank Fusion (RRF) scores. It reallocates this budget dynamically based on the conversation topic (e.g., more coding facts for coding tasks).
• Cold Memory: Facts that are not relevant to the current conversation but are still stored are considered 'cold'. These are not included in the system prompt to save tokens, but they remain accessible via the recall_memory tool, which the agent can call explicitly to search for specific information.