Vantage (RAG)

Vantage is Arkhein's module for managing folder-scoped Retrieval-Augmented Generation (RAG). It allows you to create isolated "Verticals" that only search within a specific, user-authorized directory.

Vantage Lifecycle

Ingestion & Sync

When you create or update a Vantage card, Arkhein begins a multi-step process:

1. Index: The ArchiveService scans the directory, identifying new, modified, or deleted files.
2. Knowledge Persistence: Chunks and their embeddings are stored in the knowledge table within the nativephp SQLite database.
3. Rebuild: MemoryService rebuilds the Vektor index from the SSOT to include the new knowledge.

Scoped Retrieval

Recall in Vantage is strictly folder-scoped. Each interaction is filtered by metadata.folder_id, ensuring the agent only accesses information relevant to the current Vertical context.

Invariants

• Orphan Prevention: When a Vantage Vertical is deleted, Arkhein purges all folder-scoped knowledge for its associated folder_id.
• Managed Folders: Vantage can only interact with directories that have been added to the application's Managed Folders list.
• SSOT Integrity: Deletion of a Vantage Vertical must always be followed by a Vektor index rebuild.

Common Failures

Incomplete Sync

Large directories may take time to index. If the indexing job is interrupted, some files may not be searchable until the next sync is manually triggered.

Permissions

If Arkhein loses access to a managed folder (e.g., if it's on an unmounted drive), indexing will fail.

Missing Metadata

Search results depend on correct folder_id metadata. If a chunk is saved without a folder_id, it will be excluded from folder-scoped retrieval.