OAKENMAIL

Connect an AI client to Oaken Mail's local MCP server: setup, the tools it offers, the confirmation step, untrusted mail text and the privacy note.

A first-time setup of Oaken Mail: install with uv, write config.toml, pull the Ollama models, add an account, store its credential in the keyring, start the daemon, sync, and turn on the MCP server.

How Oaken uses the OS keyring: the service and entry names, the commands that store credentials (oaken gmail auth, oaken imap auth), a quick check that the keyring works, how to inspect entries with Seahorse, and what the no-keyring error means.

Create a Google Cloud OAuth client, publish it so tokens do not expire after 7 days, authorize, configure the Gmail plugin, and run a read-only first sync. Covers scopes, the token design and what to do when Google revokes a token.

oaken settings (get, check, set), storage and vacuum, the enrichment cache, the event log and paged audit log, and the health summary in oaken status.

Configure the SMTP send plugin: host, port, STARTTLS or TLS, the keyring password, what happens to Bcc, how failures are reported, and a first live check.

Configure the IMAP provider: host, port, STARTTLS or TLS, the keyring password, which folders are synced, how changes are found, what is written back, and a first live check.

The core process, thin clients, plugins and the two databases.

The event bus, the durable job queue with leases and retries, and the scheduler.

How Oaken measures token savings: cache savings (model calls skipped) and context savings (mail text kept out of a client's context window), split by CLI, UI, MCP and internal callers, with the formulas, the baseline and the caveats.

The layered map of Oaken Mail's components and their build status.

External agents that lease jobs: opt-in config, scoped tokens, quotas, validated results, and matching Ollama parallelism.

raw.db: content-addressed zstd messages, the LFS folder for large mail, soft deletes, garbage collection, sync cursors and accounts.

The core daemon: startup and shutdown order, the runtime file, the API token, the Host, Origin and content-type guards, event streaming, and the threat model.

The parser, the cleaning rules and why each exists, thread keys, the tokenizer, attachments and quarantine, and every setting that tunes them.

Sieve (RFC 5228) in Oaken: where scripts live, what is supported and refused, how actions map to labels, flags and a disposition, what is stored in raw.db, and the limits that keep hostile mail harmless.

index.db in Oaken: what it holds, how a message is chunked and indexed, how a search query is made safe, how the index is tied to one raw store, and how to rebuild it.

How to write a provider, embedder, LLM backend, enricher, vector store or cache plugin, register it, test it, and what the host guarantees.

How Oaken stores and searches embeddings with sqlite-vec: the tables, filters, model swaps, measured speed and size, and why it was chosen.

The stages mail passes through (store, filter and index, embed, enrich), how each is made idempotent, what happens when a model is down, how tokens are counted, and the quarantine folder.

UntrustedText and delimiters, the prompt builder, structured output and its single repair retry, the per-workspace LLM cache, the secure and insecure workspaces, and the Ollama plugin's rules.

What marks a message read and what never does, the local-first write-back state machine, the audit log and undo, the confirm gate, and the settings.

The sync schedule table, intervals and cron with a timezone, the interval floor, the concurrency cap, catch-up after sleep, backoff, authentication pauses, quiet hours, per-account provider instances and per-folder schedules.

The operation registry, permission classes, the confirm gate and proposals, MCP exposure you control, result limits, plugin operations, the OpenAPI document and what is not built yet.

How hybrid search merges BM25 and vector results with rank fusion, what happens when the vector side is down, how queries are read, and how retrieval is measured.

Every plugin contract: Protocol methods, data types, capabilities and base classes.

Every operation: permission class, MCP exposure, inputs and outputs.

The oaken command-line client: commands, options and exit codes.

Recall, MRR and nDCG for keyword, vector and hybrid search, and the token cost of cited answers, from the latest evaluation run.

The local HTTP API: auth, Host and Origin rules, routes, events.

Set up a development environment and the rules for contributions.

Every architecture decision record, with its status and date.

How to report a security problem.

The Contributor Covenant code of conduct.