48 lines
3.0 KiB
Markdown
48 lines
3.0 KiB
Markdown
## **Architecture Status Report: Memory & Persistence**
|
|
|
|
**Date:** March 6, 2026 (Refactored)
|
|
**Component:** State Management Layer (Drizzle + PGlite)
|
|
|
|
### **1. Memory Architecture (RAM)**
|
|
|
|
The bot utilizes a **Memory-First** strategy for active chat sessions, while persisting critical queue and message data to disk.
|
|
|
|
* **Storage Mechanism**: Active chat contexts are stored in a native `Map<string, ChatContext>` within the `BotContext` object (`src/core/types.ts`).
|
|
* **Lifecycle Management**:
|
|
* **Creation**: Contexts are lazy-loaded via `ensureChatContext` in `src/core/session/context.ts` upon receiving a message.
|
|
* **Retention**: Currently, contexts remain in memory until process termination. History is trimmed during the loop.
|
|
* **Context Trimming**:
|
|
* Executed within `handleLoopStep` in `src/core/loop/scheduler.ts`.
|
|
* Individual channels enforce strict limits: `MAX_ACTIONS_IN_CONTEXT = 50`, `ACTIONS_KEEP_ON_TRIM = 20`.
|
|
* Message history is dynamically fetched from the database (last 10 messages) to keep the LLM context lean.
|
|
|
|
### **2. Persistence Architecture (Database)**
|
|
|
|
The bot has migrated from `lowdb` (JSON) to **PGlite** (PostgreSQL in WASM/Node) with **Drizzle ORM** for robust state management and high-performance I/O.
|
|
|
|
* **Technology**: [PGlite](https://pglite.dev/) + [Drizzle ORM](https://orm.drizzle.team/).
|
|
* **Location**: `data/` directory (configured via `DB_PATH` in `.env.local`).
|
|
* **Schema (`src/lib/schema.ts`)**:
|
|
* `channels`: Metadata for discovered channels (ID, name, platform, self_id).
|
|
* `messages`: Persistent message log with indexing on `channel_id` and `timestamp`.
|
|
* `event_queue`: Persistent queue for incoming Satori events awaiting processing.
|
|
* `unread_events`: Persistent store for events marked as unread for each channel.
|
|
* **Optimized I/O Strategy**:
|
|
* **Incremental Updates**: Unlike the previous "full-rewrite" approach, the bot now uses targeted SQL operations.
|
|
* **Queue Management**: Individual items are added (`pushToEventQueue`) and removed (`removeFromEventQueue`) by ID.
|
|
* **Unread Tracking**: Unread messages are persisted incrementally (`pushToUnreadEvents`) and cleared per channel (`clearUnreadEventsForChannel`).
|
|
* **Migrations**: Managed via `drizzle-kit`. Migrations are automatically applied on startup in `src/lib/db.ts`.
|
|
|
|
### **3. State Consistency & Recovery**
|
|
|
|
The gap between ephemeral memory and persistent disk state has been significantly narrowed.
|
|
|
|
* **Durable Queue**: The `eventQueue` and `unreadEvents` are fully persisted. If the bot crashes, it resumes processing the queue from where it left off.
|
|
* **Message History**: The LLM's conversation history is reconstructed from the indexed `messages` table in the database, ensuring continuity across restarts.
|
|
* **Hard Reset Mitigation**: While `AbortController` handles are still lost on restart, the core task queue and conversation context remain intact.
|
|
|
|
### **4. Configuration**
|
|
|
|
Database settings are managed through `src/config.ts`:
|
|
* `DB_PATH`: Path to the PGlite data directory (default: `data/pglite-db`).
|