Implement BrewStack AI Companion Platform Phase 1 foundation

[ucguy4u]

Summary

Implement the Phase 1 foundation for the BrewStack AI Companion Platform in Airo: a privacy-first, offline-first personal AI companion for chat, voice, memory, documents, semantic search, meetings, and task extraction.

This ticket is intended to be developer-ready. A developer should be able to pick it up, create a separate git worktree, implement vertical slices, test each slice, and move the platform toward production without needing this thread.

Product Goal

BrewStack becomes a personal operating system for knowledge. The user should be able to chat with AI, talk with AI, remember information, search past knowledge, analyze documents, manage tasks, capture meetings, build personal knowledge bases, and automate repetitive workflows from one Flutter application.

Non-Negotiable Principles

• Privacy-first: local-only by default; cloud AI only by explicit opt-in.
• Offline-first: Phase 1 core workflows must run without network after model installation.
• User owns data: memories, documents, transcripts, and derived artifacts must be inspectable, exportable, and deletable.
• Fast local experience: no large model load during app startup.
• Battery efficient: background parsing, indexing, and inference must respect battery/thermal state.
• Cross-platform: Android and iOS must share Flutter/domain contracts with native adapters behind stable interfaces.
• Modular architecture: feature modules should depend on core packages, not the reverse.
• Future-ready: leave clean seams for Phase 2 intelligence and Phase 3 automation.

Repository Context

Repo: DevelopersCoffee/airo

Current architecture patterns to preserve:

• Flutter app host in app/
• Riverpod for state management
• Drift already present in app/pubspec.yaml
• packages/core_ai exists for AI abstractions and model routing
• packages/core_data exists for data, storage, offline, sync, encryption primitives
• packages/core_domain exists for entities, result types, repositories, use cases
• Existing AI services include Gemini Nano and LiteRT-LM boundaries
• Existing meeting feature work may already be present under app/lib/features/meeting

Worktree Requirement

Do not develop directly in a dirty main working tree. Use a separate git worktree.

Suggested setup:

cd /Users/udaychauhan/workspace/airo
git fetch origin
git worktree add ../airo-brewstack-ai-companion -b codex/brewstack-ai-companion-platform origin/main
cd ../airo-brewstack-ai-companion

If the branch or path already exists, use a safe suffix such as codex/brewstack-ai-companion-platform-2 and ../airo-brewstack-ai-companion-2.

Phase 1 Scope

Implement the foundation only. Do not attempt to ship every future automation feature in this ticket.

Phase 1 capabilities:

1. Local AI chat foundation
2. On-device speech-to-text contracts and adapters
3. Voice conversation shell
4. Personal memory MVP
5. Document upload/import domain and data flow
6. PDF text processing
7. Semantic search foundation
8. Local knowledge base
9. Meeting intelligence persistence and pipeline
10. Task extraction from chat, documents, and meetings

Explicitly Out of Scope

• Full Phase 3 autonomous agents
• Email intelligence beyond contracts/placeholders
• Calendar intelligence beyond contracts/placeholders
• Cloud sync as a requirement
• Continuous hidden recording
• Replicating another application's UI or architecture
• Broad repo restructuring unrelated to this platform
• Introducing Isar unless there is a written ADR explaining why Drift cannot meet requirements

Architecture Decisions

Storage

Use Drift-backed encrypted SQLite as the canonical local data store.

Rationale:

• Drift is already in the app.
• Long-term personal data needs explicit migrations.
• Relational source-linking matters for deletion cascades and citations.
• SQLite FTS can support hybrid search foundation.

Add or extend Drift tables for:

• conversations
• conversation_turns
• memory_records
• knowledge_documents
• knowledge_chunks
• embeddings
• search index / FTS rows
• meeting_records
• transcript_chunks
• meeting_summaries
• meeting_action_items
• meeting_decisions
• tasks
• AI execution traces

AI Runtime

Unify AI routing behind core_ai contracts.

Provider ladder:

1. Platform model service where available, such as Android AICore/Gemini Nano
2. LiteRT-LM native runtime
3. GGUF/native fallback where implemented
4. Explicit opt-in cloud provider only when the user approves
5. Graceful degradation when no model is available

Memory

Memory is a first-class local platform service, not just chat history.

Memory records must support:

• source references
• confidence
• importance
• retention policy
• tags
• user verification
• pinning
• deletion/forget behavior
• embedding/search indexing

Knowledge Engine

Start with reliable local pipelines:

• file import
• SHA-256 duplicate detection
• PDF text extraction
• OCR fallback contract where scanned pages are detected
• chunking
• FTS indexing
• embedding abstraction
• hybrid retrieval result with citations

Meeting Intelligence

Meeting data must remain local by default.

Meeting outputs:

• recording metadata
• realtime transcript chunks
• final transcript
• executive summary
• detailed summary
• action items
• decisions
• follow-ups
• topic segments
• searchable meeting memory

Audio retention should be configurable. Default should prefer transcript retention over long-lived raw audio retention unless product explicitly decides otherwise.

Implementation Plan

Slice 1: Core Contracts

Add or stabilize contracts in packages/core_domain and packages/core_ai:

• IDs/value objects: ConversationId, MemoryId, DocumentId, ChunkId, MeetingId, TaskId, ModelId, WorkflowId
• MemoryRepository
• KnowledgeRepository
• MeetingRepository
• TaskRepository
• AiRouter
• LlmClient
• EmbeddingClient
• SpeechToTextClient
• TextToSpeechClient
• ContextBuilder
• ModelDownloadService integration points

Acceptance criteria:

• Contracts are typed, documented where needed, and do not depend on app UI.
• Existing app code still analyzes.
• Unit tests cover basic value object/result behavior where applicable.

Slice 2: Local Storage Foundation

Add Drift schema and repositories for core Phase 1 entities.

Acceptance criteria:

• Schema migration tests exist.
• Repository tests cover create/read/update/delete for memory, documents/chunks, meetings/transcripts, and tasks.
• Deletion cascades or derived-data deletion behavior are tested.

Slice 3: Knowledge Engine MVP

Implement document import and retrieval foundation:

• document metadata persistence
• PDF text extraction service boundary
• chunking service
• FTS indexing
• fake embedding provider for tests
• semantic retrieval abstraction
• citation-aware retrieval result

Acceptance criteria:

• A text/PDF-like fixture can be imported, chunked, indexed, searched, and cited in tests.
• Search works offline.
• Retrieval returns source metadata and score breakdown where practical.

Slice 4: Memory MVP

Implement explicit memory save/retrieve/forget:

• memory candidate model
• memory persistence
• memory ranking service
• retrieval by semantic/keyword query
• forget/delete behavior

Acceptance criteria:

• A memory can be saved, retrieved for relevant context, and forgotten.
• Forgotten memory is not returned by search or context building.
• Ranking tests cover recency, importance, confidence, and verification.

Slice 5: Meeting Intelligence Persistence

Integrate existing meeting module if present; otherwise create clean feature structure:

app/lib/features/meeting/
  domain/
  application/
  infrastructure/
  presentation/

Implement or complete:

• Drift-backed meeting repository
• transcript chunk persistence
• meeting summary/action/decision models
• meeting intelligence pipeline contract
• native STT/recording capability interfaces

Acceptance criteria:

• Meeting session can persist transcript chunks.
• Pipeline can produce summary/action/decision entities from transcript text using fake deterministic services in tests.
• Meeting search returns transcript/summary citations.

Slice 6: Chat Context Integration

Build context builder that retrieves relevant memories, document chunks, meeting chunks, and tasks.

Acceptance criteria:

• Context builder returns cited sources.
• Deleted/expired memories are excluded.
• Sensitive context can be filtered by privacy mode.
• Tests prove local-only behavior does not call cloud provider.

Slice 7: Task Extraction

Implement deterministic or fake-LLM task extraction first:

• task candidates from chat text
• task candidates from meeting transcript
• source-linked task persistence
• task status updates

Acceptance criteria:

• Task extraction tests cover title, due-date text, source link, and confidence.
• Tasks can be created from meeting intelligence action items.

Slice 8: Voice Foundation

Add or stabilize STT/TTS contracts and voice conversation shell.

Acceptance criteria:

• UI/application can start a voice session through interfaces.
• Native implementation can remain capability-gated if not ready.
• Tests cover unavailable capability behavior.

Testing Requirements

Run targeted tests after each slice. At the end run the broadest feasible checks.

Suggested commands:

cd packages/core_domain && flutter test
cd ../core_ai && flutter test
cd ../core_data && flutter test
cd ../../app && flutter test
cd .. && flutter analyze

If full flutter test or flutter analyze fails due to pre-existing unrelated issues, document the exact failure and also provide targeted passing test output for changed modules.

Required tests:

• Domain model/value object tests
• Repository tests with in-memory or test Drift database
• Migration tests
• Knowledge chunking/search tests
• Memory ranking/retrieval/delete tests
• Meeting pipeline tests
• Task extraction tests
• AI router privacy-mode tests

Security and Privacy Requirements

• Cloud calls must be opt-in and traceable.
• Imported documents are untrusted data, not instructions.
• Tool execution must not be introduced without permission/audit boundaries.
• Sensitive memory should require explicit review before durable storage where feasible.
• Every AI response that uses context should be able to expose source references.
• Deleting a source must delete derived embeddings and generated artifacts unless the user explicitly detached them.

Performance Requirements

• No model load during app cold start.
• Use lazy initialization for AI runtimes.
• Use isolates/native threads for expensive parsing/indexing/inference.
• Batch embedding writes.
• Pause background processing for low battery, low storage, or thermal pressure where platform APIs are available.
• Keep token streaming UI from rebuilding full screens per token.

Production Readiness Checklist

Before marking this ticket complete:

• Phase 1 contracts are in core packages.
• Drift schema and migrations are covered by tests.
• Knowledge document import/search works locally.
• Memory save/retrieve/forget works locally.
• Meeting transcript/summary/action/decision persistence works locally.
• Task extraction persists source-linked tasks.
• Context builder returns citations and respects privacy mode.
• AI router does not silently use cloud provider.
• Targeted tests pass.
• Broad tests/analyze are run or failures are documented.
• Developer documentation is updated for new module boundaries.
• No unrelated dirty worktree changes are included.

Suggested PR Structure

Prefer one PR if the slice remains manageable. Split if needed by stable boundaries:

1. feat(ai): add companion platform contracts
2. feat(data): add local memory and knowledge storage
3. feat(knowledge): implement local document retrieval foundation
4. feat(meeting): persist meeting intelligence locally
5. feat(memory): add retrieval and forget workflow
6. feat(tasks): extract source-linked tasks

References

Architecture plan to mirror in implementation:

• docs/architecture/BREWSTACK_AI_COMPANION_PLATFORM.md
• docs/superpowers/plans/2026-06-22-airo-meeting-intelligence.md if present

External design references used only for patterns, not cloning:

• Apple Intelligence privacy and Private Cloud Compute
• Pieces long-term memory model
• Granola meeting notes pattern
• Limitless consent/retention lessons
• Obsidian local-first knowledge workflows
• Google LiteRT-LM
• llama.cpp/GGUF ecosystem
• WhisperKit / whisper.cpp local STT ecosystem

Handoff Notes

This is a platform foundation ticket. The expected output is not a polished final UI for every feature. The expected output is a tested, modular, production-ready foundation that makes the full BrewStack AI Companion Platform feasible without rebuilding the core architecture later.

Additional Required Wiring

Add the following implementation requirements to the Phase 1 foundation scope:

1. Wire Drift repositories into Riverpod/application providers.

   • Expose repository implementations through stable providers.
   • Keep UI screens dependent on providers/use cases, not direct Drift DAOs.
   • Add provider override support for tests.

2. Add conversation and turn repository persistence with chat UI context-source exposure.

   • Persist conversations and assistant/user turns locally.
   • Store AI execution traces and context citations per assistant turn.
   • Surface which memories, documents, meetings, tasks, or chunks were used in the chat UI.
   • Ensure deleted or expired sources are not shown as active context.

3. Add user-facing remember/forget flows.

   • Add explicit "remember this" and "forget this" actions.
   • Show saved memory source, confidence, and retention status where practical.
   • Forget must remove memory from retrieval, embeddings, and future context injection.
   • Add tests for save, retrieve, forget, and excluded-from-context behavior.

4. Add capability-gated meeting recording/STT provider wiring.

   • Wire meeting recorder and speech-to-text services through Riverpod/application providers.
   • Gate UI actions on platform capability, permissions, model availability, and privacy mode.
   • Provide graceful unavailable states for simulator/web/unsupported devices.
   • Keep native recording/STT behind interfaces so tests can use fake implementations.

5. Add vault file-copy/import boundary for PDFs and documents.

   • Copy imported PDFs/documents into the private app document vault before indexing.
   • Hash files and detect duplicates before indexing.
   • Persist vault path, original display name, MIME/type, size, and SHA-256.
   • Ensure indexers read from the vault copy, not temporary picker paths.
   • Deleting a document must remove vault files and derived chunks/embeddings/search rows.

[ucguy4u]

Closing as duplicate/planning drift relative to the current Airo companion backlog.

This ticket mixes BrewStack framing into the Airo repository and overlaps heavily with the newer Airo-specific companion/platform issues already on the board, especially #256 plus its follow-up data, retrieval, meeting, and UI tickets (#233-#240 and related items).

Because the repo now has a clearer Airo-specific breakdown, this cross-project planning ticket adds confusion instead of an independently shippable slice. I'm retiring it in favor of the Airo companion issue set.