miku-discord/readmes/MEMORY_EDITOR_FEATURE.md

Memory Editor UI - Comprehensive CRUD Interface

Overview

Implemented comprehensive memory management UI in the Web Control Panel (Tab 9: Memories) with full CRUD operations. Users can now manually edit, create, delete, and search memories through an intuitive interface.

Features

1. Edit Existing Memories

• Edit Button (✏️) next to each memory/fact
• Modal dialog with textarea for content editing
• Source field for tracking where the memory came from
• Preserves vector embeddings when only metadata changes
• Re-embeds content when text is modified

2. Create New Memories

• "➕ Add Fact" button for declarative memories
• "➕ Add Memory" button for episodic memories
• Modal dialog with:
  • Content textarea
  • Optional User ID (for user-specific memories)
  • Source field (defaults to "manual")
• Automatically generates proper embeddings and metadata

3. Search/Filter Memories

• Search input above each memory list
• Real-time filtering as you type
• Case-insensitive search across content and metadata
• Shows/hides matching items dynamically

4. Delete Operations

• Individual delete (🗑️ button) - single confirmation
• Delete All - multi-step safety flow (unchanged)

Implementation Details

Backend API (bot/api.py)

New Pydantic Models:

class MemoryEditRequest(BaseModel):
    content: str
    metadata: Optional[dict] = None

class MemoryCreateRequest(BaseModel):
    content: str
    collection: str  # "declarative" or "episodic"
    user_id: Optional[str] = None
    source: Optional[str] = None
    metadata: Optional[dict] = None

New Endpoints:

• PUT /memory/point/{collection}/{point_id} - Edit existing memory
• POST /memory/create - Create new memory point

Cat Client (bot/utils/cat_client.py)

New Methods:

update_memory_point(collection, point_id, content, metadata=None):

1. Fetches existing point from Qdrant (includes vector)
2. Checks if content changed
3. If content changed: Re-embeds via Cat's /embedder endpoint
4. If only metadata changed: Preserves existing vector
5. Updates point in Qdrant with new payload
6. Returns True on success

create_memory_point(collection, content, user_id=None, source=None):

1. Generates UUID for new point_id
2. Embeds content via Cat's /embedder endpoint
3. Builds payload with metadata:
   • source: Tracking field (e.g., "manual", "discord", "autonomous")
   • when: Unix timestamp
   • user_id: For declarative memories, identifies user
4. Inserts into Qdrant collection
5. Returns point_id on success, None on failure

Key Details:

• Uses Qdrant REST API: http://cheshire-cat-vector-memory:6333
• Leverages Cat's /embedder endpoint for consistent vector generation
• Proper error handling with try/except blocks
• Async operations with aiohttp

Frontend UI (bot/static/index.html)

Modal Dialogs Added:

Edit Memory Modal:

<div id="edit-memory-modal">
  <textarea id="edit-memory-content"></textarea>
  <input id="edit-memory-source" placeholder="Source">
  <button onclick="saveMemoryEdit()">Save Changes</button>
  <button onclick="closeEditMemoryModal()">Cancel</button>
</div>

Create Memory Modal:

<div id="create-memory-modal">
  <textarea id="create-memory-content"></textarea>
  <input id="create-memory-user-id" placeholder="User ID (optional)">
  <input id="create-memory-source" value="manual">
  <button onclick="saveNewMemory()">Create Memory</button>
  <button onclick="closeCreateMemoryModal()">Cancel</button>
</div>

JavaScript Functions Added:

• showEditMemoryModal(collection, pointId, memoryData) - Open edit modal with data
• closeEditMemoryModal() - Close edit modal
• saveMemoryEdit() - PUT request to update memory
• showCreateMemoryModal(collection) - Open create modal for collection type
• closeCreateMemoryModal() - Close create modal
• saveNewMemory() - POST request to create memory
• filterMemories(listId, searchTerm) - Real-time search/filter

UI Enhancements:

• Added memory-item class to all memory divs for filtering
• Edit button (✏️) styled with blue color (#5599cc)
• Delete button (🗑️) kept in red (#993333)
• Search inputs with oninput handlers for live filtering
• Flex layout for button groups

Usage Guide

Editing a Memory

1. Navigate to Tab 9: Memories in Web UI
2. Load facts or episodic memories
3. Click the ✏️ Edit button next to any memory
4. Modal opens with current content and source
5. Modify the content and/or source
6. Click "Save Changes"
7. Memory is updated in Qdrant and list refreshes

Creating a New Memory

For Declarative Facts:

1. Click "➕ Add Fact" button
2. Enter the fact content (e.g., "Miku's favorite color is cyan")
3. Optionally add User ID (for user-specific facts)
4. Set source (defaults to "manual")
5. Click "Create Memory"
6. Fact is embedded and stored in declarative collection

For Episodic Memories:

1. Click "➕ Add Memory" button
2. Enter the memory content (conversation context)
3. Optionally add User ID
4. Set source (e.g., "manual", "test", "import")
5. Click "Create Memory"
6. Memory is embedded and stored in episodic collection

Searching Memories

1. Type in the search box above the memory list
2. Results filter in real-time
3. Clear the search box to see all memories again
4. Search matches content and metadata

Testing the Feature

Create a Test Fact:

// In browser console or through UI:
// Click "Add Fact" button, enter:
Content: "Miku's favorite color is cyan"
User ID: (leave empty for general fact)
Source: "test"

Verify Through Chat:

User: "What is your favorite color?"
Miku: "My favorite color is cyan!" (should recall the fact)

Edit the Fact:

// Click ✏️ next to the fact, change:
Content: "Miku's favorite color is teal"
Source: "test_edit"

Delete the Fact:

// Click 🗑️ button, confirm deletion

Technical Architecture

Data Flow

Edit Memory:

User clicks ✏️
→ showEditMemoryModal() populates form
→ User edits and clicks "Save"
→ saveMemoryEdit() → PUT /memory/point/{collection}/{id}
→ api.py validates with MemoryEditRequest
→ cat_adapter.update_memory_point()
→ Fetches existing point from Qdrant
→ Re-embeds if content changed
→ Updates point in Qdrant
→ Returns success
→ UI reloads memory list

Create Memory:

User clicks ➕ Add Fact
→ showCreateMemoryModal('declarative')
→ User fills form and clicks "Create"
→ saveNewMemory() → POST /memory/create
→ api.py validates with MemoryCreateRequest
→ cat_adapter.create_memory_point()
→ Generates UUID
→ Embeds content via Cat's /embedder
→ Builds payload with metadata
→ Inserts into Qdrant
→ Returns point_id
→ UI reloads memory list and refreshes stats

Error Handling

Backend:

• Validates collection name (only "declarative" and "episodic" allowed)
• Checks for empty content
• Handles Qdrant connection errors
• Returns proper error messages in JSON

Frontend:

• Shows user-friendly notifications
• Disables buttons during operations
• Reverts button text on error
• Validates required fields before submission

Metadata Structure

Declarative Memories

{
  "source": "manual",
  "when": 1734567890.123,
  "user_id": "user_discord_id_here"  // Optional, for user-specific facts
}

Episodic Memories

{
  "source": "manual",
  "when": 1734567890.123
}

Note: user_id is only used in declarative memories to associate facts with specific users.

Future Enhancements

Potential Features:

1. Batch Operations

   • Select multiple memories with checkboxes
   • Bulk delete selected
   • Bulk export selected

2. Import/Export

   • Export memories as JSON file
   • Import memories from JSON
   • Bulk memory migration

3. Advanced Filtering

   • Filter by date range
   • Filter by source
   • Filter by user_id
   • Sort by similarity score

4. Memory History

   • Track edit history
   • Show who edited and when
   • Ability to revert changes

5. Memory Insights

   • Show most recalled memories
   • Identify unused/stale memories
   • Suggest memory consolidation

6. Rich Text Editing

   • Markdown support in memory content
   • Syntax highlighting for code snippets
   • Preview mode

Testing Checklist

• Backend API endpoints respond correctly
• Cat client methods communicate with Qdrant
• Edit modal opens and populates correctly
• Edit saves and updates memory in Qdrant
• Create modal opens for both fact and memory types
• Create generates proper embeddings and stores in Qdrant
• Search/filter works in real-time
• Delete still works as expected
• UI refreshes after operations
• Error notifications display properly
• Test with actual chat queries to verify LLM recalls edited facts
• Test user-specific facts with user_id parameter
• Performance test with large memory sets (1000+ items)

Related Files

Backend:

• /bot/api.py - Lines 2778-2788 (models), 2918-2968 (endpoints)
• /bot/utils/cat_client.py - Lines 382-541 (new methods)

Frontend:

• /bot/static/index.html - Lines 1613-1781 (UI sections and modals), 5268-5685 (JavaScript functions)

Documentation:

• /readmes/MEMORY_EDITOR_FEATURE.md - This file
• /readmes/AUTONOMOUS_V2_DECISION_LOGIC.md - Memory usage in autonomous system

Notes

• Container must be restarted after API changes: docker restart miku-bot
• Modals use flexbox centering with semi-transparent backdrop
• Memory items use class="memory-item" for filtering
• Edit button uses ✏️ emoji with blue color (#5599cc)
• Create buttons use ➕ emoji
• All operations show loading states (button text changes)
• Success/error notifications use existing showNotification() function