LocalRAGVisualMapSystem

A local-first AI chatbot desktop app (Electron) with structured memory cards, a local RAG knowledge base, a 2D UMAP visualisation of your knowledge base, Gmail sync, and streaming responses. Works with Anthropic Claude or OpenAI. Everything is stored on your machine — no cloud sync, no telemetry.

Minimal light/beige aesthetic. Single-file Electron app, no build step for day-to-day development.

---

Features

Chat

• Streaming responses (token-by-token) with a Stop button
• Markdown rendering + syntax-highlighted code blocks
• Copy / regenerate / good-bad per assistant message
• Voice-to-text dictation (whisper-1)
• File drop / attach (ephemeral context for the current message)
• Conversation history, persisted locally

Memory (structured)

• Memory Cards: each piece of persistent context lives as a categorised card (identity / project / preference / taboo / style / general)
• Parse a free-form text dump into cards via one LLM call
• Cards can be toggled on/off; only enabled cards are injected into the system prompt
• "Firing" visualisation: after each assistant reply, the cards whose embeddings are most similar to the response briefly pulse in the Memory panel — shows you which memories actually influenced the answer

Knowledge Base (local RAG)

• Upload PDF / DOCX / TXT / MD files — chunked and embedded with text-embedding-3-small
• Top-K cosine retrieval per user message
• Per-document list with size & chunk count, delete / clear all

2D Map of your Knowledge Base

• UMAP (1536-D → 2-D) + k-means clustering + LLM-auto-labeled clusters
• Every chunk = one dot; closer dots = more semantically similar
• Enter a query → embeds it, highlights the top-K most similar chunks, dims the rest, draws lines from a pulsing query-point to each hit
• Zoom / pan / fullscreen: mouse-wheel to zoom around cursor, left-click drag to pan, keyboard + / - / 0 / F shortcuts
• Rich hover tooltip: cluster chip + color, chunk #N, doc name, text preview, match% bar when activation is live
• Cluster legend, zoom-% indicator, one-click map rebuild

Gmail Sync

• IMAP-based (uses an app password, not OAuth)
• Fetch recent emails into a preview list, search by subject/from
• One-click "sync N emails to knowledge base" — parses headers + body, chunks and embeds as regular KB documents

Local-first

• All data (conversations, cards, KB vectors, Gmail credentials) stored via electron-store in your OS user-data directory
• Nothing leaves your machine except the API calls you explicitly make (chat + embedding + whisper)

---

Quick Start

Requires Node.js 18+ and an API key from either Anthropic or OpenAI (OpenAI key is also required for embeddings if you want to use RAG / Map, even when chatting with Claude).

git clone https://github.com/<your-username>/LocalRAGVisualMapSystem.git
cd LocalRAGVisualMapSystem
npm install
npm start

On first launch: Settings → paste your API key(s), pick a provider, save.

---

Build a Desktop Installer

npm run dist   # writes to dist/

Produces a .dmg (macOS), .exe (Windows NSIS), or .AppImage (Linux) depending on the host OS.

---

Where data lives

electron-store writes JSON files to your OS user-data directory. No cloud sync.

• macOS: ~/Library/Application Support/minimal-chatbot/
• Windows: %APPDATA%/minimal-chatbot/
• Linux: ~/.config/minimal-chatbot/

Files:

• config.json — settings, API keys, memory cards, Gmail IMAP creds
• conversations.json — full chat history
• kb.json — knowledge-base chunks + embeddings
• kbMap.json — cached UMAP layout + cluster labels

Delete the folder to fully reset.

---

Project Structure

LocalRAGVisualMapSystem/
├── main.js            Electron main process: IPC handlers, API calls,
│                      embedding, UMAP, k-means, Gmail IMAP
├── preload.js         contextBridge API surface
├── renderer/
│   ├── index.html     UI shell (sidebar, modals, composer)
│   ├── styles.css     Light minimal theme
│   └── renderer.js    All UI logic (chat streaming, cards, map, Gmail)
├── package.json
└── README.md

---

Keyboard shortcuts

• Enter — send
• Shift+Enter — newline
• Esc — close modal / stop generation
• ⌘/Ctrl+K — new chat
• ⌘/Ctrl+/ — focus composer
• On the Map tab: + / - zoom, 0 reset, F fullscreen

---

Customising

Theme colors live as CSS custom properties at the top of renderer/styles.css:

:root {
  --bg: #FAF9F6;
  --bg-sidebar: #F3F1EC;
  --user-bubble: #EFEBE2;
  --accent: #1F1E1B;
}

---

License

MIT