# wh-violet667/mnemo architecture

> Architecture diagram of the GitHub repository wh-violet667/mnemo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wh-violet667/mnemo
- Repository: https://github.com/wh-violet667/mnemo

## Overview

Mnemo is a personalized RAG assistant: a user chats through Streamlit, FastAPI streams a LangGraph agent’s response, and the agent can retrieve cited knowledge-base evidence and long-term memories. The product also supports document ingestion, session isolation, memory extraction, and memory management. PostgreSQL stores durable records, Milvus serves retrieval indexes, and Redis holds checkpoints and profile cache. The README documents several links among these services; source excerpts clarify selected implementations, but some API and memory-management internals were not sampled.

Main entry points: [`backend/agent.py`](https://github.com/wh-violet667/mnemo/blob/main/backend/agent.py) (LangGraph agent), [`backend/postgresql_client.py`](https://github.com/wh-violet667/mnemo/blob/main/backend/postgresql_client.py) (PostgreSQL), [`backend/api.py`](https://github.com/wh-violet667/mnemo/blob/main/backend/api.py) (FastAPI endpoints), [`backend/retrieval.py`](https://github.com/wh-violet667/mnemo/blob/main/backend/retrieval.py) (Hybrid and agentic retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_ui["Streamlit interface<br/>[app.py]"]
  node_streaming["Stream event reader<br/>[streaming.py]"]
end

subgraph group_application["Conversation and agent"]
  node_api["FastAPI endpoints<br/>[api.py]"]
  node_agent["LangGraph agent<br/>[agent.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_conversations["Conversation helpers<br/>[conversations.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_documents["Document processing"]
  node_hash["Duplicate detection<br/>[hash_storage.py]"]
  node_kb["Knowledge-base index"]
  node_retrieval["Hybrid and agentic retrieval<br/>[retrieval.py]"]
  node_citations["Citation handling<br/>[citations.py]"]
  node_answer_metrics["Answer metrics<br/>[answer_metrics.py]"]
end

subgraph group_memory["Long-term memory"]
  node_memorytask["Scheduled memory extraction"]
  node_memory["Memory retrieval and lifecycle<br/>[memory_manager.py]"]
end

subgraph group_storage["Persistence and models"]
  node_postgres[("PostgreSQL")]
  node_milvus[("Milvus client<br/>[milvus_client.py]")]
  node_redis[("Redis checkpoint and cache<br/>[redis_cache.py]")]
  node_model{{"DashScope models"}}
end

node_user(("User"))

node_user -->|"asks"| node_ui
node_ui -->|"streams chat"| node_api
node_api -->|"invokes"| node_agent
node_agent -->|"calls tools"| node_tools
node_agent -->|"loads profile"| node_postgres
node_agent -->|"checkpoints"| node_redis
node_agent -->|"generates"| node_model
node_agent -->|"streams answer and trace"| node_ui
node_ui -->|"reads events"| node_streaming
node_api -->|"normalizes sessions"| node_conversations
node_api -->|"stores conversations"| node_postgres
node_api -->|"processes uploads"| node_documents
node_documents -->|"checks duplicates"| node_hash
node_hash -->|"reads and writes hashes"| node_postgres
node_documents -->|"stores parent chunks"| node_postgres
node_documents -->|"indexes child chunks"| node_milvus
node_tools -->|"searches knowledge"| node_retrieval
node_retrieval -->|"recalls child chunks"| node_milvus
node_retrieval -->|"loads parent text"| node_postgres
node_retrieval -->|"reranks evidence"| node_model
node_retrieval -->|"formats sources"| node_citations
node_tools -->|"retrieves memories"| node_memory
node_memory -->|"searches memory index"| node_milvus
node_memory -->|"reads and writes records"| node_postgres
node_memorytask -->|"compresses conversations"| node_postgres
node_memorytask -->|"projects memories"| node_milvus
node_memorytask -->|"extracts memories"| node_model
node_ui -.->|"evaluated by"| node_answer_metrics

click node_ui "https://github.com/wh-violet667/mnemo/blob/main/frontend/app.py"
click node_streaming "https://github.com/wh-violet667/mnemo/blob/main/frontend/streaming.py"
click node_api "https://github.com/wh-violet667/mnemo/blob/main/backend/api.py"
click node_agent "https://github.com/wh-violet667/mnemo/blob/main/backend/agent.py"
click node_tools "https://github.com/wh-violet667/mnemo/blob/main/backend/tools.py"
click node_conversations "https://github.com/wh-violet667/mnemo/blob/main/backend/conversations.py"
click node_documents "https://github.com/wh-violet667/mnemo/blob/main/backend/documents_process.py"
click node_hash "https://github.com/wh-violet667/mnemo/blob/main/backend/hash_storage.py"
click node_kb "https://github.com/wh-violet667/mnemo/blob/main/backend/knowledge_base_manager.py"
click node_retrieval "https://github.com/wh-violet667/mnemo/blob/main/backend/retrieval.py"
click node_citations "https://github.com/wh-violet667/mnemo/blob/main/backend/citations.py"
click node_memorytask "https://github.com/wh-violet667/mnemo/blob/main/backend/auto_store_memory_from_psql.py"
click node_memory "https://github.com/wh-violet667/mnemo/blob/main/backend/memory_manager.py"
click node_postgres "https://github.com/wh-violet667/mnemo/blob/main/backend/postgresql_client.py"
click node_milvus "https://github.com/wh-violet667/mnemo/blob/main/backend/milvus_client.py"
click node_redis "https://github.com/wh-violet667/mnemo/blob/main/backend/redis_cache.py"
click node_answer_metrics "https://github.com/wh-violet667/mnemo/blob/main/evals/answer_metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_streaming,node_user toneBlue
class node_api,node_agent,node_tools,node_conversations toneAmber
class node_documents,node_hash,node_kb,node_retrieval,node_citations,node_answer_metrics toneMint
class node_memorytask,node_memory toneRose
class node_postgres,node_milvus,node_redis,node_model toneIndigo
```

## Components

### Chat client

- [Streamlit interface](https://github.com/wh-violet667/mnemo/blob/main/frontend/app.py): `frontend/app.py`
- [Stream event reader](https://github.com/wh-violet667/mnemo/blob/main/frontend/streaming.py): `frontend/streaming.py`

### Conversation and agent

- [FastAPI endpoints](https://github.com/wh-violet667/mnemo/blob/main/backend/api.py): `backend/api.py`
- [LangGraph agent](https://github.com/wh-violet667/mnemo/blob/main/backend/agent.py): `backend/agent.py`
- [Agent tools](https://github.com/wh-violet667/mnemo/blob/main/backend/tools.py): `backend/tools.py`
- [Conversation helpers](https://github.com/wh-violet667/mnemo/blob/main/backend/conversations.py): `backend/conversations.py`

### Knowledge retrieval

- [Document processing](https://github.com/wh-violet667/mnemo/blob/main/backend/documents_process.py): `backend/documents_process.py`
- [Duplicate detection](https://github.com/wh-violet667/mnemo/blob/main/backend/hash_storage.py): `backend/hash_storage.py`
- [Knowledge-base index](https://github.com/wh-violet667/mnemo/blob/main/backend/knowledge_base_manager.py): `backend/knowledge_base_manager.py`
- [Hybrid and agentic retrieval](https://github.com/wh-violet667/mnemo/blob/main/backend/retrieval.py): `backend/retrieval.py`
- [Citation handling](https://github.com/wh-violet667/mnemo/blob/main/backend/citations.py): `backend/citations.py`
- [Answer metrics](https://github.com/wh-violet667/mnemo/blob/main/evals/answer_metrics.py): `evals/answer_metrics.py`

### Long-term memory

- [Scheduled memory extraction](https://github.com/wh-violet667/mnemo/blob/main/backend/auto_store_memory_from_psql.py): `backend/auto_store_memory_from_psql.py`
- [Memory retrieval and lifecycle](https://github.com/wh-violet667/mnemo/blob/main/backend/memory_manager.py): `backend/memory_manager.py`

### Persistence and models

- [PostgreSQL](https://github.com/wh-violet667/mnemo/blob/main/backend/postgresql_client.py): `backend/postgresql_client.py`
- [Milvus client](https://github.com/wh-violet667/mnemo/blob/main/backend/milvus_client.py): `backend/milvus_client.py`
- [Redis checkpoint and cache](https://github.com/wh-violet667/mnemo/blob/main/backend/redis_cache.py): `backend/redis_cache.py`
- **DashScope models**

### Other components

- **User**

## Connections

- User → Streamlit interface: asks (evidence: `README.md`)
- Streamlit interface → FastAPI endpoints: streams chat (evidence: `README.md`)
- FastAPI endpoints → LangGraph agent: invokes (evidence: `README.md`)
- LangGraph agent → Agent tools: calls tools (evidence: `backend/agent.py`)
- LangGraph agent → PostgreSQL: loads profile (evidence: `backend/agent.py`)
- LangGraph agent → Redis checkpoint and cache: checkpoints (evidence: `README.md`)
- LangGraph agent → DashScope models: generates (evidence: `README.md`)
- LangGraph agent → Streamlit interface: streams answer and trace (evidence: `backend/agent.py`)
- Streamlit interface → Stream event reader: reads events (evidence: `frontend/app.py`)
- FastAPI endpoints → Conversation helpers: normalizes sessions (evidence: `backend/api.py`)
- FastAPI endpoints → PostgreSQL: stores conversations (evidence: `README.md`)
- FastAPI endpoints → Document processing: processes uploads (evidence: `backend/api.py`)
- Document processing → Duplicate detection: checks duplicates (evidence: `backend/documents_process.py`)
- Duplicate detection → PostgreSQL: reads and writes hashes (evidence: `backend/hash_storage.py`)
- Document processing → PostgreSQL: stores parent chunks (evidence: `backend/documents_process.py`)
- Document processing → Milvus client: indexes child chunks (evidence: `backend/documents_process.py`)
- Agent tools → Hybrid and agentic retrieval: searches knowledge (evidence: `backend/tools.py`)
- Hybrid and agentic retrieval → Milvus client: recalls child chunks (evidence: `README.md`)
- Hybrid and agentic retrieval → PostgreSQL: loads parent text (evidence: `README.md`)
- Hybrid and agentic retrieval → DashScope models: reranks evidence (evidence: `README.md`)
- Hybrid and agentic retrieval → Citation handling: formats sources (evidence: `backend/retrieval.py`)
- Agent tools → Memory retrieval and lifecycle: retrieves memories (evidence: `README.md`)
- Memory retrieval and lifecycle → Milvus client: searches memory index (evidence: `README.md`)
- Memory retrieval and lifecycle → PostgreSQL: reads and writes records (evidence: `backend/memory_manager.py`)
- Scheduled memory extraction → PostgreSQL: compresses conversations (evidence: `README.md`)
- Scheduled memory extraction → Milvus client: projects memories (evidence: `backend/auto_store_memory_from_psql.py`)
- Scheduled memory extraction → DashScope models: extracts memories (evidence: `README.md`)
- Streamlit interface → Answer metrics: evaluated by