Pocket Advisor 是一个用于个人文档收藏的本地检索增强生成系统。摄取、直接本地检索和 MCP（stdio 和 HTTP）都作为主机上的一个 Go 二进制文件运行——这些都不运行在 Kubernetes 中。该二进制文件使用一个共享存储，运行在本地集群中：

• 配置过的工作区目录中的原始文件是权威且只读的。
• PostgreSQL 是二级血缘、三级向量和词汇索引，以及在摄取池之间承载工作的持久队列。

二进制通过发现和导入文档，检索引用证据，并作为MCP工具公开检索功能。它不生成答案。MCP客户端可以读取返回的证据并生成引用答案。

pocket-advisor-infra Helm 图表仅部署 PostgreSQL。MCP 服务器内置于 pocket-advisor 二进制文件中，并通过 mcp stdio 或 mcp start（HTTP）本地运行。

1.概念

• 每个命令都被作用域限定为一个工作区，且 --workspace-id。
• PostgreSQL 是一个共享进程，但每个工作区都有自己的数据库和角色——该角色也包含其作业队列——以及受限的源根（见第3节）。

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.