Headless OKF Knowledge Hub & Cloudflare AI Agent

Project Overview

Transitioning the Bossidian vault away from the Obsidian desktop application into a fully decoupled, headless knowledge system. An automated Cloudflare Workers AI edge service manages knowledge ingestion, voice memo transcription, automated GitHub commits, and semantic retrieval, while Quartz v4 on Cloudflare Pages serves as a high-performance, private reading interface.

1. Executive Summary & Design Philosophy

The primary objective is to replace the heavyweight, proprietary-feeling Obsidian workflow with open standards:

1. Storage & Version Control: Authoritative source of truth remains the Git repository (Bossidian-okf) adhering strictly to the Open Knowledge Format (OKF v0.2).
2. Edge Intelligence (Cloudflare Workers AI): Serverless global edge functions listen for incoming text, audio, and search queries, formatting content according to OKF rules and pushing commits via the GitHub API.
3. Capture Interface (Telegram Bot): Frictionless mobile and desktop interface capable of receiving raw thoughts, voice memos, and conversational questions without opening an editor.
4. Reading Layer (Quartz on Cloudflare Pages): Hyper-fast, static, zero-plugin Progressive Web Application (PWA) behind Cloudflare Zero Trust authentication.

2. Target Architecture

flowchart TD
    subgraph Capture["1. Mobile & Ingestion"]
        T1["Telegram Text Message"]
        T2["Telegram Voice Memo (.oga)"]
        S1["Apple Shortcuts / Direct Webhook"]
    end

    subgraph EdgeEngine["2. Cloudflare Edge Engine (Worker)"]
        W1["Router & Auth Guard (Telegram User ID Check)"]
        AI_W["Workers AI Whisper (@cf/openai/whisper)"]
        AI_L["Workers AI Llama 3.3 70B (@cf/meta/llama-3.3-70b-instruct)"]
        V_STORE["Vectorize (Vector Embeddings)"]
        KV_STORE["Cloudflare KV (Vault File Cache)"]
        VAL["OKF Schema Validator & Markdown Formatter"]
    end

    subgraph GitHubStorage["3. Authoritative Storage (GitHub)"]
        GH_API["GitHub REST / Git Database API"]
        REPO["Bossidian-okf (main branch)"]
        GH_HOOK["GitHub Push Webhook"]
    end

    subgraph ReadingUX["4. Reading UX (Cloudflare Pages)"]
        PAGES["Cloudflare Pages (npx quartz build)"]
        ZT["Cloudflare Zero Trust (Email PIN / SSO)"]
        PWA["Mobile & Desktop Browser / PWA"]
    end

    Capture -->|HTTPS Webhook| W1
    W1 -->|Audio Stream| AI_W
    AI_W -->|Transcribed Text| W1
    W1 <-->|Reasoning & Structuring| AI_L
    W1 <-->|Semantic Search| V_STORE
    W1 <-->|Cached Note Retrieval| KV_STORE
    W1 --> VAL
    VAL -->|Atomic Commit| GH_API
    GH_API --> REPO
    REPO -->|Auto Rebuild| PAGES
    REPO -->|Push Event| GH_HOOK
    GH_HOOK -->|Sync Changed Files| KV_STORE
    GH_HOOK -->|Update Embeddings| V_STORE
    PAGES --> ZT
    ZT --> PWA

3. Phased Implementation Roadmap

The deployment follows a reverse build sequence: Core Intelligence & GitHub Sync first, Conversational Bot second, and Static Reading UX third.

Phase 1: Cloudflare Workers AI & GitHub Integration Engine

Objective: Deploy a secure edge worker that communicates bidirectionally with the GitHub repository, executes local model inference, and maintains a local cache of the vault.

• 1.1 Initialise Cloudflare Worker Project

  • Scaffold a TypeScript project using Wrangler on the Cloudflare Free tier: npm create cloudflare@latest okf-edge-agent.
  • Configure wrangler.jsonc with bindings for:
    • Workers AI (env.AI) bound to multilingual @cf/baai/bge-m3 for semantic search.
    • Cloudflare KV (VAULT_KV) for fast local note caching.
    • Cloudflare Vectorize (VAULT_VECTOR_INDEX).
  • Configure secret variables via npx wrangler secret put:
    • GITHUB_TOKEN: Fine-grained personal access token with contents:write and metadata:read.
    • GITHUB_REPO: dainiusluzan/Bossidian-okf.
    • GEMINI_API_KEY: Google AI Studio key for direct multimodal audio processing.
    • TELEGRAM_BOT_TOKEN & TELEGRAM_OWNER_ID: Telegram credentials.

• 1.2 Build GitHub API Client with OCC Retry Pattern

  • Port battle-tested Git client from pirkiniu-sarasas/src/lib/server/github.ts:
    • Jittered exponential backoff retry on 409 Conflict.
    • UTF-8 Base64 encoding/decoding.
  • Implement discrete capture committer targeting 00-inbox/captures/YYYYMMDD-HHmmss-[slug].md to eliminate write hotspots.
  • Create deterministic OKF frontmatter validator enforcing type, status: draft, and generated: { by: "gemini-scribe/v1", at: ISO-8601 }.

• 1.3 Implement Vault Mirror & Multilingual Semantic Indexing

  • Implement /webhooks/github that listens for GitHub push events.
  • On commit payload:
    • Sync changed markdown files into Cloudflare KV.
    • Chunk note contents, pass to Workers AI @cf/baai/bge-m3 (multilingual model supporting Lithuanian and English), and upsert into Cloudflare Vectorize.

• 1.4 Implement Direct Multimodal Audio Engine (Gemini Flash)

  • Adopt proven multimodal architecture from pirkiniu-sarasas/src/lib/server/gemini.ts:
    • Receive raw audio buffer (Ogg/Opus, M4A, WAV, MP3).
    • Single-stage inference via Gemini Flash with structured schema output.
    • Native Lithuanian speech recognition, case preservation, and automatic frontmatter generation in ~1.5s.

Phase 2: Conversational Bot & Ingestion Interface

Objective: Build an instant, frictionless mobile capture interface using the Telegram Bot API connected to the Workers AI engine.

• 2.1 Provision Telegram Bot

  • Create bot via @BotFather on Telegram (/newbot).
  • Retrieve bot token and store via npx wrangler secret put TELEGRAM_BOT_TOKEN.
  • Store personal Telegram User ID via npx wrangler secret put TELEGRAM_OWNER_ID.
  • Set webhook pointing to the Worker:

    curl -F "url=https://<worker-domain>/webhooks/telegram" \
         -F "secret_token=<TELEGRAM_SECRET>" \
         https://api.telegram.org/bot<TOKEN>/setWebhook

• 2.2 Implement Security & Async Request Routing

  • Validate X-Telegram-Bot-Api-Secret-Token header.
  • Enforce sender guard: if (update.message.from.id !== Number(env.TELEGRAM_OWNER_ID)) return Response("Forbidden", 403).
  • Immediate Acknowledgment: Return HTTP 200 OK in $<30\text{ms}$ to prevent Telegram retry loops, executing note ingestion asynchronously inside ctx.waitUntil().

• 2.3 Text Capture & Inbox Ingestion

  • Fast capture workflow: Write new discrete capture note to 00-inbox/captures/YYYYMMDD-HHmmss-[slug].md.
  • Classify note into PARA tags or categories using Gemini Flash.
  • Send Telegram confirmation message back via asynchronous sendMessage call with direct commit SHA.

• 2.4 Voice Memo Pipeline

  • Download incoming .oga voice memo from Telegram media servers into memory.
  • Pass audio buffer directly to Gemini Flash multimodal API.
  • Generates structured OKF title, tags, and summary preserving Lithuanian diacritics and technical vocabulary.
  • Commits note and replies to Telegram with confirmation summary.

• 2.5 Conversational Knowledge Search

  • If a message ends with ? or triggers a /ask command:
    • Perform Vectorize semantic search across notes stored in KV.
    • Feed relevant context chunks to Llama 3.3 70B.
    • Return precise answer with source note links.

Phase 3: Reading UX (Cloudflare Pages + Quartz v4)

Objective: Replace the Obsidian desktop/mobile application with a dedicated, zero-maintenance web reader accessible globally.

• 3.1 Set Up Quartz v4 in Repository

  • Initialise Quartz configuration (quartz.config.ts, quartz.layout.ts).
  • Configure Quartz for strict relative link resolution ([Title](./path/note.md)).
  • Enable features:
    • Full-text client-side search (FlexSearch).
    • Table of contents & breadcrumbs.
    • Interactive graph view (optional).
    • Dark mode by default.

• 3.2 Connect Cloudflare Pages & Configure Build Filter

  • In Cloudflare Dashboard, create a new Pages project connected to dainiusluzan/Bossidian-okf.
  • Build settings:
    • Framework preset: None
    • Build command: npx quartz build
    • Build output directory: public
  • Quota Protection Filter: Configure Cloudflare Pages Ignored Build Step:

    git diff --quiet HEAD^ HEAD -- 01-projects 02-areas 03-resources 99-start-here index.md || exit 1

    (Skips build if commit is confined to 00-inbox/captures/, preserving the 500 builds/month free quota).

• 3.3 Secure Access with Cloudflare Zero Trust

  • Navigate to Cloudflare Zero Trust $\to$ Access $\to$ Applications.
  • Add self-hosted application on custom domain (e.g. notes.yourdomain.com).
  • Define Access Policy:
    • Rule: Allow if email is your-email@example.com.
  • Authenticate via one-time PIN (OTP) or Google/GitHub OAuth.

• 3.4 Configure Mobile Progressive Web App (PWA)

  • Open authenticated URL in mobile Safari/Chrome.
  • Select “Add to Home Screen”.
  • Confirm full-screen standalone application behaviour and instant search performance.

4. Architectural Alternatives Evaluated

5. Critical Obstacles & Mitigation Strategies

1. Git Race Conditions & Merge Conflicts

• Risk: If a user makes direct edits via mobile GitHub web while the Cloudflare Worker attempts to commit simultaneously, the push will be rejected with an HTTP 409 Conflict.
• Mitigation:
  • Single Writer Domain: All automated edge captures target exclusively 00-inbox/daily-notes/ or generate uniquely timestamped inbox files (00-inbox/captures/YYYYMMDD-HHMMSS.md).
  • Retry with Fresh Ref: The GitHub client must fetch the current latest main commit SHA immediately before pushing a commit tree, retrying up to 3 times on conflict.

2. OKF Schema Integrity & LLM Hallucinations

• Risk: LLMs may hallucinate nonexistent relative file paths or drop required frontmatter fields (status, generated).
• Mitigation:
  • Deterministic Code Guardrails: Never write raw LLM output directly to disk. The Worker parses the LLM output into typed JSON, then passes the object through a deterministic TypeScript formatter that constructs YAML frontmatter and standard relative links according to AGENTS.md.

3. Edge Execution Time Limits

• Risk: Free Cloudflare Workers have a 50ms CPU execution limit and a 30s connection timeout. Processing multi-step agent chains or large audio files could timeout.
• Mitigation:
  • Leverage streaming responses for AI inference.
  • Acknowledge Telegram webhook requests immediately (HTTP 200 OK) and process heavy operations using waitUntil(async () => { ... }) or Cloudflare Queues.

6. Project Checklist & Verification Criteria

• Cloudflare Worker handles GET /health with 200 OK.
• Worker successfully pushes an automated test commit to 00-inbox/captures/ via GitHub API.
• GitHub webhook pushes update Cloudflare KV within 2 seconds of a commit.
• Telegram bot responds to /start and rejects unauthorized users.
• Voice memo in Telegram produces transcribed text note in GitHub within 5 seconds.
• Conversational query in Telegram returns accurate answer cited from existing vault notes.
• Cloudflare Pages deploys Quartz v4 without build errors.
• Cloudflare Zero Trust blocks unauthenticated public access.
• Mobile PWA installed and functional on smartphone.

Ingestion Verification & Live Telemetry Logs

• Telegram Text Ingestion (Verified 2026-10-14 & 2026-10-15): Verified via raw test captures 20261014091349-testas-2.md and 20261015073011-testas-1.md successfully committed to 00-inbox/captures/ via GitHub REST API with OCC retry pattern.
• Telegram Voice Transcription (Verified 2026-10-15): Verified via voice memo 20261015082338-naujas-darbu-irasas.md transcribed via Gemini Flash multimodal inference and committed to 00-inbox/captures/.

Related Notes & References

• AGENTS.md - Vault operational rules and OKF compliance standards.
• LiteLLM on macOS Setup - Local LLM architecture reference.
• Vault Index - Root catalog of the knowledge base.