# Local AI Database Strategy (LanceDB + SQLite)

## Overview
A 100% offline-first local database architecture for storing AI memories in a React Native (Expo) application. The solution splits the data into two highly optimized engines:
1. **`expo-sqlite`**: Manages structured text, sessions, dates, and relationships.
2. **`LanceDB`**: Manages the high-dimensional vector embeddings, pointed by SQLite relationship IDs.

> [!WARNING] **Architectural Risk (LanceDB on Mobile)**
> LanceDB relies on robust Apache Arrow and native dependencies. Running it completely on-device in a React Native/Expo environment needs careful validation (e.g., verifying polyfills or WebAssembly compatibility), since most vector DBs are backend/Node.js native.

## Project Type
**MOBILE** (React Native / Expo)

## Success Criteria
- [ ] Both databases can correctly initialize on iOS and Android simulators/devices.
- [ ] A memory string can be successfully indexed (stored in SQLite + embedding stored in LanceDB).
- [ ] A semantic search query returns the correct related memories locally.
- [ ] Application does not crash due to native library incompatibilities.

## Tech Stack
- **`expo-sqlite`**: The official, lightweight SQLite solution for the Expo SDK, providing fully synchronous mapping properties.
- **`@lancedb/lancedb`** (or equivalent mobile-compatible API): Vector store for fast embedding similarity searches locally.
- **`zustand`** (Already installed): State management for caching the queries/memories if needed in the UI.

## File Structure
```
app/
  ...
services/
  db/
    sqliteClient.ts      # SQLite connection and raw queries
    lanceDbClient.ts     # LanceDB vector search and connection
    memoryService.ts     # Unifies both DBs to create the "AI Memories" logic
hooks/
  useAiMemories.ts       # React Hook to expose database queries
types/
  database.d.ts          # TS interfaces for Tables and Documents
```

## Task Breakdown

### Task 1: Environment Research & Setup
- **Agent**: `mobile-developer`
- **Skill**: `mobile-design`
- **INPUT**: Current `package.json`
- **OUTPUT**: Installation of `expo-sqlite` and LanceDB dependencies. Verified bare React Native compatibility for LanceDB.
- **VERIFY**: Running a successful `npx expo start` and `npx expo run:android` without build failures.

### Task 2: Database Schema & Layer
- **Agent**: `database-architect` (simulated by `mobile-developer`)
- **Skill**: `database-design`
- **INPUT**: Dependencies installed.
- **OUTPUT**:
  - `sqliteClient.ts`: `Sessions`, `Messages`, `Metadata` tables.
  - `lanceDbClient.ts`: LanceDB table initialization with vector dimensions (e.g. 384 or 1536).
- **VERIFY**: Launching the app correctly fires the initialization queries (logs "DB Connected").

### Task 3: Unifying Memory Service
- **Agent**: `mobile-developer`
- **Skill**: `clean-code`
- **INPUT**: Initialized Database clients.
- **OUTPUT**: `memoryService.ts` containing functions like `saveMemory(text, embedding)` and `searchSimilar(embedding, limit)`.
- **VERIFY**: Hardcoding a mock vector search and getting the SQLite structured data back.

### Task 4: Hook UI Integration
- **Agent**: `mobile-developer`
- **Skill**: `mobile-design`
- **INPUT**: `memoryService.ts` logic.
- **OUTPUT**: `useAiMemories.ts` hook ready to be plugged into chat components.
- **VERIFY**: Test components renders data from the DB layer.

---

## ✅ PHASE X: Verification Checklist

*To be completed after Phase 4.*

- **Linting:** ⬜ Pass (`npm run lint` & `tsc`)
- **Build (Android):** ⬜ Pass (`npx expo run:android`)
- **Build (iOS):** ⬜ Pass (`npx expo run:ios`)
- **Feature Check:** ⬜ Vector search and relation query works offline.
- **Color/UI Rules:** ⬜ UI follows standard themes (Not applicable for DB layer but required by protocol).
- **Date:** TBD