Pocket Advisor Operator Guide

Pocket Advisor is a local retrieval-augmented generation system for personal document collections. Ingestion, direct local retrieval, and MCP (stdio and HTTP) all run as one Go binary on the host — none of it runs in Kubernetes. That binary uses one shared store that does run in the local cluster:

• Original files in configured workspace directories are authoritative and read-only.
• PostgreSQL is Tier 2 lineage, Tier 3 vector and lexical indexes, and the durable queue that carries work between ingestion pools.

The binary discovers and ingests documents, retrieves cited evidence, and exposes retrieval as an MCP tool. It does not generate answers itself. An MCP client can read the returned evidence and compose a cited answer.

host                                         local Kubernetes cluster

pocket-advisor
  source discovery        -----------------> configured original files (read-only)
  ingestion and retrieval -----------------> PostgreSQL / pgvector / BM25
  ingestion worker pools   (job queue, in PostgreSQL)
  embedding, reranking,
  query preparation       -----------------> local model endpoint

The pocket-advisor-infra Helm chart deploys only PostgreSQL. The MCP server is built into the pocket-advisor binary and runs locally via mcp stdio or mcp start (HTTP).

1. Concepts

• Every command is scoped to one workspace with --workspace-id.
• PostgreSQL is a shared process, but each workspace has its own database and role — which also holds its job queue — and confined source roots (see §3).
• The registry’s paths and ignore rules define authoritative originals. Historical bytes require source-side versioning or backups.
• Ingestion hashes configured files, preserves content identities across moves and copies, and drains a durable PostgreSQL job queue. Completed unchanged content is not re-extracted or re-embedded.
• PostgreSQL retains normalized text and derived metadata/indexes. Rebuilding requires hash-recoverable originals; restore a database backup when existing UUIDs and evaluation references must survive.
• Ingestion is additive: it scans original files and processes queued work, and never deletes. --reconcile-deletions is the separate, confirmed sweep that removes documents no longer reachable from staged content.
• Retrieval returns cited evidence packets, not generated prose.

The authoritative designs are:

• ingestion
• PDF text extraction
• retrieval
• workspace isolation
• API and interfaces
• answer generation

2. Prerequisites

• OrbStack or another local Kubernetes cluster with a default dynamic StorageClass.
• mise for the pinned Go and CGo environment.
• Tesseract and the required language packs for scanned PDFs and images.