Passive Interaction Model & Session Isolation¶

This document outlines how the pi-vault-mind extension implements a passive interaction model inspired by pi-piqo, while resolving the issue of context degradation through intelligent session isolation and subagents.

The Problem with Monolithic Context¶

When a user is researching or reading, they typically take dozens of notes and ask multiple disparate questions:

@agent-Miner summarize this technical claim.
@agent-Broadcaster add this to the study guide.
@agent-Manager review the tone of this paragraph.

If a traditional file-watcher simply appends these tasks to a single, ongoing LLM chat session, the context window quickly becomes polluted. By task #12, the LLM is burdened with the irrelevant thought processes of tasks #1 through #11, leading to degraded performance and hallucination.

The Solution: "Fork & Dispatch" Model¶

Our Dispatcher (Watcher) replaces the monolithic chat session with an asynchronous, multi-agent dispatch system.

1. Marker Detection & Grouping¶

When the user saves an Obsidian file, the Dispatcher scans for @agent-[Role] markers. It debounces file saves (e.g., 1000ms) to allow the user to finish their thought. Instead of sending requests immediately to the active session, it groups the requests by the target agent role.

2. Isolated Subagent Execution¶

For each group, the Dispatcher leverages the pi-subagents extension to execute the tasks in isolation.

{
  "agent": "vault-mind-miner",
  "task": "Extract entities from the following section: ...",
  "context": "fork",
  "async": true
}

Why { context: "fork" }? * Clean State: The subagent branches off from the current session. It inherits the project knowledge and identity established so far, but its execution trace (scratchpad thinking, tool calls, and verbose outputs) is strictly contained within its own [uuid].jsonl session file. * No Pollution: The main chat session (where the user interacts with the Manager) is never polluted with the subagent's internal reasoning.

3. Asynchronous Resolution¶

Because the tasks are dispatched as async: true, multiple subagents can process different notes in parallel without blocking the user's terminal or Obsidian UI.

When a subagent completes: 1. It returns its structured output. 2. The Dispatcher replaces the original @agent marker in the Markdown file with the result. 3. The subagent process terminates.

Continuing the Conversation (Deep Dives)¶

What if the user sees the subagent's result in Obsidian and wants to ask a follow-up question?

If the user writes: @agent-Miner:followup What did you mean by X?

The Dispatcher can recognize the thread identifier. Because the subagent ran in a saved session file, the Dispatcher can revive that specific session using the subagent({ action: "resume", id: "..." }) tool.

This provides a perfectly clean, topic-specific context window. The revived agent has access to its exact reasoning for that specific note, without carrying the baggage of the 14 other notes processed that day.

Summary of Interaction Flow¶

Human: Reads and drops @agent markers in Obsidian.
Dispatcher: Watches, groups, and forks subagents.
Subagent: Inherits context, executes task in isolation, writes to Vault/LanceDB, and terminates.
Human: Reviews the Vault, continuing specific threads if needed via targeted markers.