Mai/.planning/phases/04-memory-context-management/04-01-PLAN.md

---
phase: 04-memory-context-management
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: ["src/memory/__init__.py", "src/memory/storage/sqlite_manager.py", "src/memory/storage/vector_store.py", "src/memory/storage/__init__.py", "requirements.txt"]
autonomous: true

must_haves:
  truths:
    - "Conversations are stored locally in SQLite database"
    - "Vector embeddings are stored using sqlite-vec extension"
    - "Database schema supports conversations, messages, and embeddings"
    - "Memory system persists across application restarts"
  artifacts:
    - path: "src/memory/storage/sqlite_manager.py"
      provides: "SQLite database operations and schema management"
      min_lines: 80
    - path: "src/memory/storage/vector_store.py" 
      provides: "Vector storage and retrieval with sqlite-vec"
      min_lines: 60
    - path: "src/memory/__init__.py"
      provides: "Memory module entry point"
      exports: ["MemoryManager"]
  key_links:
    - from: "src/memory/storage/sqlite_manager.py"
      to: "sqlite-vec extension"
      via: "extension loading and virtual table creation"
      pattern: "load_extension.*vec0"
    - from: "src/memory/storage/vector_store.py"
      to: "src/memory/storage/sqlite_manager.py"
      via: "database connection for vector operations"
      pattern: "sqlite_manager\\.db"
---

<objective>
Create the foundational storage layer for conversation memory using SQLite with sqlite-vec extension. This establishes the hybrid storage architecture where recent conversations are kept in SQLite for fast access, with vector capabilities for semantic search.

Purpose: Provide persistent, reliable storage that serves as the foundation for all memory operations
Output: Working SQLite database with vector support and basic conversation/message storage
</objective>

<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/phases/04-memory-context-management/04-CONTEXT.md
@.planning/phases/04-memory-context-management/04-RESEARCH.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md

# Reference existing models structure
@src/models/context_manager.py
@src/models/conversation.py
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create memory module structure and SQLite manager</name>
  <files>src/memory/__init__.py, src/memory/storage/__init__.py, src/memory/storage/sqlite_manager.py</files>
  <action>
Create the memory module structure following the research pattern:

1. Create src/memory/__init__.py with MemoryManager class stub
2. Create src/memory/storage/__init__.py  
3. Create src/memory/storage/sqlite_manager.py with:
   - SQLiteManager class with connection management
   - Database schema for conversations, messages, metadata
   - Table creation with proper indexing
   - Connection pooling and thread safety
   - Database migration support

Use the schema from research with conversations table (id, title, created_at, updated_at, metadata) and messages table (id, conversation_id, role, content, timestamp, embedding_id).

Include proper error handling, connection management, and follow existing code patterns from src/models/ modules.
  </action>
  <verify>python -c "from src.memory.storage.sqlite_manager import SQLiteManager; db = SQLiteManager(':memory:'); print('SQLite manager created successfully')"</verify>
  <done>SQLite manager can create and connect to database with proper schema</done>
</task>

<task type="auto">
  <name>Task 2: Implement vector store with sqlite-vec integration</name>
  <files>src/memory/storage/vector_store.py, requirements.txt</files>
  <action>
Create src/memory/storage/vector_store.py with VectorStore class:

1. Add sqlite-vec to requirements.txt
2. Implement VectorStore with:
   - sqlite-vec extension loading
   - Virtual table creation for embeddings (using vec0)
   - Vector insertion and retrieval methods
   - Support for different embedding dimensions (start with 384 for all-MiniLM-L6-v2)
   - Integration with SQLiteManager for database connection

Follow the research pattern for sqlite-vec setup:
```python
db.enable_load_extension(True)
db.load_extension("vec0")
CREATE VIRTUAL TABLE IF NOT EXISTS vec_memory USING vec0(embedding float[384], content text, message_id integer)
```

Include methods to:
- Store embeddings with message references
- Search by vector similarity
- Batch operations for multiple embeddings
- Handle embedding model version tracking

Use existing error handling patterns from src/models/ modules.
  </action>
  <verify>python -c "from src.memory.storage.vector_store import VectorStore; import numpy as np; vs = VectorStore(':memory:'); test_vec = np.random.rand(384).astype(np.float32); print('Vector store created successfully')"</verify>
  <done>Vector store can create tables and handle basic vector operations</done>
</task>

</tasks>

<verification>
After completion, verify:
1. SQLite database can be created with proper schema
2. Vector extension loads correctly 
3. Basic conversation and message storage works
4. Vector embeddings can be stored and retrieved
5. Integration with existing model system works
</verification>

<success_criteria>
- Memory module structure created following research recommendations
- SQLite manager handles database operations with proper schema
- Vector store integrates sqlite-vec for embedding storage and search
- Error handling and connection management follow existing patterns
- Database persists data correctly across restarts
</success_criteria>

<output>
After completion, create `.planning/phases/04-memory-context-management/04-01-SUMMARY.md`
</output>