Electron-based Agent-Memory Explorer

[csmangum]

1. Problem & Goal
   • You have many “memories” generated by an agent, each stored as a JSON object (see sample fields below).
   • You need a desktop tool to quickly browse, search and inspect those memories—without touching a back-end service.

2. Assumed JSON structure (based on typical samples)

   {
     "id": "m_001234",
     "timestamp": "2025-05-19T14:23:11Z",
     "role": "user | assistant | system",
     "content": "The actual remembered text …",
     "importance": 0.73,
     "embedding": [0.12, –0.01, …],      // optional, can be hidden in MVP
     "tags": ["meeting", "project-x"]
   }

   The plan is easily adaptable if your schema varies.

3. Core User Stories for MVP
   US-1 As a user, I can open a memory file (or directory) so that the app loads all JSON objects.
   US-2 As a user, I can see a scrollable list of memories showing timestamp, role icon, and first 50 chars of content.
   US-3 As a user, I can click a memory to see its full details in a side panel.
   US-4 As a user, I can filter memories by date-range, role, or text search.
   US-5 As a user, I can sort the list by timestamp or importance.
   US-6 As a user, I can export the filtered list to a new JSON file.

4. Desktop Architecture
   • Electron: Chromium renderer + Node.js main process (gives FS access).
   • UI layer: React + TypeScript (fast to develop; feel free to swap for Vue/Svelte).
   • Preload script: exposes a small, secure API (openFile, readDir, saveFile) via contextBridge.
   • No database in MVP; everything remains in memory.
   • State management: React Context or Zustand—lightweight, enough for this scope.

5. Key UI Components

   1. TopBar
      – “Open File / Folder” button
      – Search box with debounced input
   2. SideBar (MemoryList)
      – Virtualised list for thousands of records (e.g., react-window).
      – Small coloured dot for role, bold title for tag hit, gray snippet.
   3. MainPanel (MemoryDetail)
      – Full JSON pretty-printed and copyable.
      – Toggle to hide / show large arrays like embedding.
   4. Filters Drawer
      – Date range picker
      – Role multi-select
      – Importance slider
   5. Status-bar
      – “450 / 2 371 memories loaded • 23 filtered”

6. Implementation Roadmap

   Phase 0 – Project Skeleton (½ day)
   • npm create electron-react or equivalent boilerplate.
   • Configure ESLint, Prettier, TypeScript, and electron-builder.

   Phase 1 – File I/O (1 day)
   • Preload exposes openMemoryFile() and returns parsed array.
   • Handle malformed JSON with graceful error popup.

   Phase 2 – Memory List & Detail View (1½ days)
   • React components, list virtualization, item selection.
   • Detail panel with collapsible sections.

   Phase 3 – Search & Filters (1 day)
   • Text search (simple includes or fuse.js fuzzy).
   • Role chips, date-range picker, importance slider.
   • Combined filtering pipeline kept in one util for reuse.

   Phase 4 – Sorting & Export (½ day)
   • Toggle buttons for sort order.
   • “Export current view” writes new JSON.

   Phase 5 – Polishing & Packaging (½ day)
   • Light/dark theme, icons, basic responsive layout.
   • Build Windows installer via electron-builder.

   Total effort: ≈ 4–4½ working days for one developer.

7. Stretch Goals (post-MVP)
   • Embedding visualization (t-SNE / UMAP plot).
   • Tag editing & bulk tagging.
   • GPT-based summarization of selected memories.
   • Live-watch mode that tails a growing JSONL file.

8. Risks & Mitigations
   • Very large files → Use streaming JSON parser or chunk load.
   • Security (Node integration) → Keep contextIsolation on; expose only whitelisted APIs.
   • Performance in list view → Virtualization already planned.
   • Schema drift → Keep memory object typing loose and surface unknown keys dynamically.