Sidecar Local Metadata Store
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Sidecar Local Metadata Store is a core component of the KamehaDB architecture, responsible for the persistence of application-level metadata. It operates within the apps/sidecar Node.js process and utilizes a local SQLite database to manage information such as connection profiles, AI settings, and chat history. By keeping this data local, KamehaDB ensures a local-first, private experience where credentials and configuration never leave the user's machine.
The store provides a centralized internal API for the Hono-based sidecar server to perform CRUD operations on metadata while the Desktop app (Tauri/React) interacts with it via the sidecar's HTTP endpoints. This separation ensures that the frontend remains thin and focused on UI, while the sidecar handles the logic for secret management and database persistence.
Sources: AGENTS.md, PLAN.md, README.md
Architecture and Implementation
The metadata store is implemented using better-sqlite3 for high-performance, synchronous SQLite operations. It is designed to initialize the database schema automatically upon startup, creating the necessary tables for the application to function.
Storage Location
The physical location of the SQLite database file (kamehadb.db) is determined by environment variables:
- Default:
./kamehadb.dbrelative to the sidecar's working directory. - Configurable: If
KAMEHADB_DATA_DIRis set, the database is stored at${KAMEHADB_DATA_DIR}/kamehadb.db.
Component Interaction
The following diagram illustrates how the Metadata Store fits into the overall system architecture:
The diagram shows the data flow from the UI through the Sidecar's API to the Metadata Store, which persists data to the local SQLite file.
Sources: AGENTS.md, PLAN.md
Data Models and Schema
The store manages several distinct types of metadata. These models are validated using Zod schemas defined in the shared package to ensure consistency between the sidecar and the desktop frontend.
Connection Profiles
The most critical data stored is the connection profile metadata. While profiles are stored in SQLite, sensitive credentials like passwords are intended to be stored in the OS keychain (macOS Keychain, Windows Credential Manager, etc.) to enhance security.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the connection |
name | String | User-defined display name |
kind | Enum | Database engine (postgres, mysql, sqlite, mongodb, redis, qdrant) |
host | String (Optional) | Database host address |
port | Number (Optional) | Database port |
readonly | Boolean | Safety flag to block destructive SQL |
createdAt | ISO String | Timestamp of creation |
Sources: packages/shared/src/index.ts:10-25, PLAN.md
AI and Chat Metadata
The store also persists AI-related configuration and interaction data:
- AI Settings: Configuration for providers such as OpenAI, Ollama, and 9Router.
- Chat History: Connection-scoped persistent history including timestamps and message content.
Sources: AGENTS.md, README.md, packages/shared/src/index.ts:320-350
Key Functions and Operations
The metadata-store.ts module exposes several functions to manage the application state.
Internal Logic Flow
The initialization and lifecycle of the store follow a specific sequence:
The sequence diagram shows the initialization process of the metadata store during the sidecar startup.
Sources: AGENTS.md, PLAN.md
Core Responsibilities
| Component | Responsibility |
|---|---|
| Connection CRUD | Methods to create, read, update, and delete saved connection profiles. |
| Credential Bridge | Interfaces with the OS keychain to link connection IDs with secure passwords. |
| AI Configuration | Persisting provider selections and API keys. |
| History Management | Storing and retrieving chat messages for the AI assistant. |
Conclusion
The Sidecar Local Metadata Store is the foundation of KamehaDB's local-first philosophy. By utilizing a robust SQLite backend via better-sqlite3, it provides reliable persistence for connection profiles and application settings while offloading sensitive credential storage to the operating system's native secure storage. This architecture ensures that user data remains private, performant, and accessible across application sessions.