Notes & Reminders (Vector RAG)

Chattree features an integrated, privacy-focused subsystem for user notes and reminders with local Vector RAG (Retrieval-Augmented Generation).

This guide details both the user-facing conversational capabilities and the programmatic interfaces exposed to WebAssembly plugins through the Chattree Host API.

Architecture Overview

Conversational Layer:
  User input / Chat ────► AI Engine (local Llama / External Provider)
                               │
                               ├─► Direct commands: /note, /reminder
                               ├─► Intent classification (natural language CRUD)
                               └─► Vector RAG context retrieval
                                      │
                                      ▼
Data Layer:
  Notes Database (SQLite) ◄──► Local Vector Store (Embeddings & Cosine Search)
  Reminders Database (SQLite) ◄──► Android AlarmManager (Exact Alarms via flutter_local_notifications)
                                ▲
                                │
Host API Layer (ChattreeHostApi):
  WASM Plugin ──host_call()──► PermissionGateway ──► Chattree Notes / Reminders Handlers

1. Conversational Chat Commands & Builtin Plugins

Chattree exposes Notes and Reminders through dedicated, official first-class plugins (NotePlugin and ReminderPlugin) registered within PluginRegistry.instance. This architecture ensures unified discovery in the slash-command menu, consistent permission enforcement, and deterministic routing.

Notes (NotePlugin)

• Explicit Slash Command: Users type /note directly for deterministic operations:

  /note
  /note buy coffee beans and milk
  /note project deadline: submit final report on Friday
  /note search student ID
  /note list
  

• Declarative Visual Cards: Typing /note without arguments renders a minimalist monochrome DeclarativeUiBubble card (hideText: true, note icon, list elements with note title and truncated content preview).
• Hybrid Search & rag_search: NotesService and NoteTool combine accent-insensitive tokenized lexical search with on-device RAGService semantic embeddings via Reciprocal Rank Fusion (RRF, k=60). /note also supports the rag_search action and falls back to hybrid search on get lookups when an exact title/ID match is not found, injecting bounded note context (up to 5 notes, 1,200 chars per note, 3,600 chars total).
• Conversational Safety: In standard conversational chat without slash commands, Chattree prioritizes natural conversation. If a note-taking or reminder intent is detected, Chattree transparently guides the user to invoke /note or /reminder, ensuring side-effects are never performed without explicit user consent.
• Confirmation: Destructive actions (such as deletion) require explicit user confirmation. If a request is ambiguous or references multiple notes, the assistant asks for clarification rather than deleting the wrong entry.

Reminders

Reminders handle time-sensitive tasks with scheduled notifications on Android:

• Explicit Slash Command: Typing /reminder without arguments immediately lists all pending reminders inside a minimalist monochrome DeclarativeUiBubble card (hideText: true, alarm icon, key_value items, and action buttons). With arguments, it routes to the assistant:

  /reminder
  /reminder submit tax report next Monday at 9:00 AM
  

• Date & Time Disambiguation: Scheduled reminders require a clear date and time. Ambiguous references (e.g., "in the morning") prompt clarification rather than guessing.
• Background Notifications on Android: Reminders are scheduled directly in the Android system using AlarmManager (exact alarms). When the scheduled timestamp arrives, Android wakes up the notification service to ring the alert on time, even if the phone is locked or Chattree is closed, with zero battery drain.

2. Local Vector RAG (Retrieval-Augmented Generation)

When chatting, if a user query might benefit from saved notes, Chattree can automatically augment the AI prompt with relevant context:

1. Automatic Embedding Generation: Every time a note is created or updated, Chattree awaits SQLite persistence and generates vector embeddings locally using the on-device ONNX embedding model (EmbeddingService and RAGService index notes sequentially in the background to avoid isolate contention).
2. Local Vector Storage & Compact RAM Index: Embeddings are persisted in SQLite (SqliteVectorStore). To minimize memory footprint, SqliteVectorStore keeps only document IDs and float vectors in RAM and fetches text and metadata from SQLite in batches of 500 for matching chunks, with deterministic cache invalidation whenever notes are inserted, updated, or deleted.
3. Semantic & Hybrid Search: When a conversational prompt is submitted (ChatController.sendMessage) while RAG is enabled and initialized, semantic similarity against stored note vectors is computed in milliseconds. Inside /note, NoteTool fuses semantic RAG results with accent-insensitive lexical matching via RRF (k=60).
4. Context Injection: Relevant note excerpts are automatically injected into the prompt context window before local or remote LLM inference.
5. Zero Data Leakage: Vectors, notes, and queries never leave the device. When a note is deleted, its vector embeddings are purged synchronously.
6. Fallback: If RAG is disabled in Settings or returns no high-confidence matches, standard conversation and lexical note search continue without interruption.

3. WebAssembly Plugin Integration

Third-party WASM plugins do not depend on the conversational AI interpretation. Instead, plugins interact directly with Notes and Reminders through programmatic, type-safe Host API operations.

Required Capabilities

To access these services, a plugin must declare the appropriate capabilities in its plugin.json:

"capabilities": [
  "chattree.notes.read",
  "chattree.notes.create",
  "chattree.notes.update",
  "chattree.notes.delete",
  "chattree.notes.search",
  "chattree.reminders.read",
  "chattree.reminders.create",
  "chattree.reminders.update",
  "chattree.reminders.complete",
  "chattree.reminders.delete"
]

Users review and grant these capabilities during plugin installation.

4. Host API Operations

All calls use the standard chattree.host_call interface:

Notes Operations (chattree.notes)

Create Note Example (Request)

{
  "api": "chattree.notes",
  "operation": "create",
  "payload": {
    "title": "Meeting Summary",
    "content": "Discussed Q4 roadmap and WebAssembly plugin engine milestones."
  }
}

Create Note Example (Response)

{
  "success": true,
  "data": {
    "note": {
      "id": "not_9a8b7c6d5e",
      "title": "Meeting Summary",
      "content": "Discussed Q4 roadmap and WebAssembly plugin engine milestones.",
      "createdAt": "2026-10-14T18:00:00.000Z",
      "updatedAt": "2026-10-14T18:00:00.000Z"
    }
  }
}

Reminders Operations (chattree.reminders)

5. Security & Isolation Limits

1. Title Length: Maximum 300 characters for note and reminder titles.
2. Content Length: Maximum 50,000 characters for note bodies.
3. Search Limits: Search queries return at most 100 results per request.
4. Scope Control: Notes and Reminders APIs are completely decoupled from chat history. A plugin with chattree.notes.* cannot read conversation transcripts or AI system prompts.