devanathandna/vegapunk-multi-tab-persistent-memory-conversational-ai

1. Overall shape: VEGAPUNK is a client-server, local-first AI chat system. The browser UI is a React/Vite frontend, and all AI orchestration, memory persistence, and retrieval happen in the Python backend. The main external dependency is the Google Gemini API; the rest of the system relies on local stores.

2. Frontend boundary: src/ contains a TypeScript React app with a small page layer (Home, VegaChat, NotFound) and chat-focused components (MainChat, SubChat, ChatInput, ChatMessage, sidebars). The UI is mostly presentation and chat interaction; it does not own retrieval or memory logic. The many src/components/ui/* files are a reusable shadcn/ui layer for dialogs, inputs, tabs, sheets, etc.

3. Backend API boundary: backend/app.py is the HTTP entry point and request router. It exposes the chat service to the frontend and delegates actual reasoning to the agent layer. The backend is a Flask REST API, so the diagram should show a clear network boundary between React UI and Flask service.

4. Orchestration core: backend/agent.py is the central runtime coordinator. It handles message intake, query classification, tool/LLM decision-making, retrieval fan-out, answer synthesis, and background memory updates. This is the most important internal subsystem to place at the center of the backend.

5. Hybrid memory architecture: The system fuses three distinct memory stores:

- backend/database.py for episodic memory in SQLite,

- backend/vector_store.py for semantic memory via embeddings/vector search,

- backend/graph_store.py for structural memory using a knowledge graph.

These are independent retrieval paths, not a single monolithic database.

6. Episodic layer: SQLite stores the explicit conversation timeline: sessions, messages, timestamps, and other raw conversational records. This is the “what was said, and when” layer, used when recency and exact history matter more than conceptual similarity.

7. Semantic layer: vector_store.py represents the fuzzy recall path. Messages are embedded and indexed for similarity search, allowing the agent to retrieve related past content even when the wording differs. In the architecture diagram, this is the concept-level memory branch.

8. Structural layer: graph_store.py plus entity_extractor.py form the Graph RAG branch. The backend extracts entities and relationships from messages, then persists them into a weighted knowledge graph. This supports multi-hop reasoning and relationship-based recall that vector search alone would miss.

9. Fusion and ranking: backend/fusion_layer.py combines candidates from the three memory branches into a final relevance score using semantic, structural, and recency components. This layer is the ranking boundary between retrieval and generation; it determines what context the LLM actually sees.

10. Request lifecycle: A chat turn flows from the UI into Flask, then into the agent, which classifies the query and may trigger parallel retrieval across SQLite, vector search, and graph search. The fused top results are then sent to Gemini for final synthesis. Afterward, background entity extraction updates the vector store and graph so the next turn can use the newly learned context.

11. Main chat vs sub chat: The frontend distinguishes a persistent Main Chat from Sub Chat. Main Chat contributes to long-term memory, while Sub Chat is an isolated sandbox for exploratory or debugging conversations that should not contaminate the shared memory stores. That is an important architectural boundary for understanding data persistence.

12. Operational concerns: The backend is designed around multiple Gemini API keys for classification, synthesis, and background extraction, reducing rate-limit pressure on the main response path. The repo also includes test scripts (test_api.py, test_graph_rag.py, test_gemini.py, etc.) and documentation diagrams under docs/, which are useful for validating and visualizing the architecture but are not runtime subsystems themselves.