LocalMind/local-ai-database.md

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