Note Companion Documentation

Note Companion automates file organization by monitoring a specific inbox folder. When you move files into the inbox, the system uses AI to perform several automated actions.

The Workflow:

1. Ingestion: Move any file or folder from your vault into the NoteCompanion/Inbox directory.
2. Processing: Wait for the AI to process the item (text files are near-instant; audio and images take longer).
3. Automated Actions (if enabled in plugin options):
   • Rename: The document title is updated based on content.
   • Tagging: Tags are added based on connections to existing tagged files.
   • Organization: The file is moved to the most appropriate folder. If no suitable folder is identified, it is moved to NoteCompanion/Processed.

Special File Handling:

• Audio files: A text transcription is appended to the processed document.
• Image files: Annotations are added to the processed document.
• Tagging: Every processed file is automatically tagged with #nc-processed to track its status.

The PreferenceLearner service allows the system to learn user preferences (classification, folder, tags, or templates) based on file patterns. When a user confirms or rejects a suggestion, the learner updates its confidence. If confidence exceeds a threshold (e.g., 70-80%), the system can auto-apply the preference in future processing steps.

interface UserPreference {
  pattern: string; // File pattern (e.g., "*.pdf", "meeting-*")
  classification?: string; // Preferred classification
  folder?: string; // Preferred destination
  tags?: string[]; // Preferred tags
  template?: string; // Preferred template
  confidence: number; // Learning confidence (0-100)
  appliedCount: number; // Times user confirmed this preference
  rejectedCount: number; // Times user rejected this preference
}

class PreferenceLearner {
  private preferences: Map<string, UserPreference> = new Map();

  learnFromAction(
    file: TFile,
    action: {
      type: 'folder' | 'tag' | 'classification' | 'template';
      value: any;
    }
  ) {
    const pattern = this.detectPattern(file);
    const key = `${pattern}_${action.type}`;

    const existing = this.preferences.get(key);
    if (existing && existing.value === action.value) {
      // User confirmed this preference
      existing.appliedCount++;
      existing.confidence = Math.min(100, existing.confidence + 5);
    } else {
      // New preference
      this.preferences.set(key, {
        pattern,
        [action.type]: action.value,
        confidence: 50,
        appliedCount: 1,
        rejectedCount: 0,
      });
    }
  }

  getRecommendation(
    file: TFile,
    type: 'folder' | 'tag' | 'classification' | 'template'
  ) {
    const pattern = this.detectPattern(file);
    const key = `${pattern}_${type}`;
    const pref = this.preferences.get(key);

    if (pref && pref.confidence > 70) {
      return {
        value: pref[type],
        confidence: pref.confidence,
        reason: `Based on ${pref.appliedCount} previous files matching "${pattern}"`,
      };
    }

    return null;
  }

  private detectPattern(file: TFile): string {
    const parts = file.basename.split(/[-_]/);
    if (parts[0].length > 3) {
      return `${parts[0]}-*.${file.extension}`;
    }
    return `*.${file.extension}`;
  }
}

When organizing an Obsidian vault, you can choose between two primary mental models depending on whether your goal is exhaustive documentation or actionable insight.

Approach 1: The Comprehensive Capture Vault

Goal: To cast a wide net and ensure no information is lost.

• Structure: Uses large inbox/ or dump/ folders for rapid capture of quotes, highlights, and thoughts.
• Workflow: Minimal metadata at capture; processing is sporadic or non-existent.
• Best for: Research-heavy projects, creative brainstorming, and archival/compliance needs.
• Risk: Search overload and shallow connections due to unprocessed volume.

Approach 2: The Curated Insight Vault

Goal: To prioritize clarity, connection, and easy retrieval.

• Structure: Purposeful folders like projects/, literature/, and reference/.
• Workflow: Brief capture into an inbox/, followed by regular (e.g., weekly) processing sessions to summarize, distill, and tag notes before moving them to topic-specific folders.
• Best for: Focused writing, professional/student workflows, and maintaining a manageable knowledge base.
• Risk: High maintenance/discipline required; risk of over-pruning useful raw data.

To provide visual feedback when the AI calls a tool, implement a custom tool handler. This component should intercept tool-call message parts and render specific UI based on the toolName.

Pattern:

1. Iterate through message.parts looking for type === 'tool-call'.
2. Use a switch statement on toolInvocation.toolName.
3. For each tool, render a specialized handler that takes the args and state (e.g., 'call' or 'result').
4. When the tool execution completes, call addToolResult (provided by useChat) to feed the result back into the conversation stream.

export const CustomToolHandler: React.FC<CustomToolHandlerProps> = ({ toolInvocation, addToolResult }) => {
  const { toolName, toolCallId, args, state } = toolInvocation;

  switch (toolName) {
    case "searchNotes":
      return (
        <SearchHandler
          args={args}
          state={state}
          onComplete={(result) =>
            addToolResult({ toolCallId, result: JSON.stringify(result) })
          }
        />
      );
    default:
      return <div>Tool: {toolName}</div>;
  }
};

Note Companion automates document transcription and organization through a multi-step pipeline triggered when files are dropped into an inbox folder. The system follows three main phases:

1. Detection & Queuing: An event handler detects file creation/renaming, waits for a 1-second delay, and enqueues the file. The system manages concurrency by limiting media files to 2 concurrent processes and regular files to 5.
2. Processing Steps: The pipeline executes a sequence of up to 15 steps, including content extraction (PDF text, Image OCR, Audio transcription, or YouTube transcripts), classification, folder recommendation, name recommendation, and content formatting.
3. Record Management: Every step is tracked via a RecordManager, which logs the status, errors, and metadata for each file.

Files that fail processing are moved to an Error or Bypass folder, while successful files are moved to their destination folder.

graph TB
    A[User drops file in Inbox] --> B[Event Handler detects creation]
    B --> C[Inbox Queue Manager]
    C --> D{File Type?}
    D -->|Media| E[Media Queue max 2 concurrent]
    D -->|Regular| F[Regular Queue max 5 concurrent]
    E --> G[Processing Pipeline]
    F --> G
    G --> H[Record Manager tracks steps]
    H --> I{Success?}
    I -->|Yes| J[Move to destination folder]
    I -->|No| K[Move to Error/Bypass folder]
    J --> L[Update sidebar UI]
    K --> L