# jemuelbjeroham/lisa architecture

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

- Interactive diagram: https://gitdiagram.com/jemuelbjeroham/lisa
- Repository: https://github.com/jemuelbjeroham/lisa

## Overview

LISA is a conversational assistant with general-enquiry and technical-clarification routes. A chat request loads conversation state, adds the user message, invokes the conversation graph, then saves the resulting state and returns or streams the response. Technical clarification plans knowledge retrieval and can use a hypothetical document (HyDE) before grounding its answer. The graph preserves that workflow alongside memory persistence and MCP knowledge access. The README is empty; connections for some unsampled components are omitted where the excerpts do not establish call direction.

Main entry points: [`src/lisa/application.py`](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/application.py) (Chat application), [`src/lisa/graph.py`](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/graph.py) (Conversation graph), [`src/lisa/agents/technical_clarification.py`](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/agents/technical_clarification.py) (Technical clarification), [`src/lisa/infrastructure/postgres/memory_repository.py`](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/infrastructure/postgres/memory_repository.py) (Postgres adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation runtime"]
  node_application["Chat application<br/>[application.py]"]
  node_conversation_store["Conversation store<br/>[store.py]"]
  node_redis_store["Redis store<br/>[redis.py]"]
  node_memory_store["In-memory store<br/>[in_memory.py]"]
  node_serialization["State serialization<br/>[serialization.py]"]
  node_graph["Conversation graph<br/>[graph.py]"]
  node_state["Conversation state<br/>[state.py]"]
  node_stream_events["Stream events<br/>[events.py]"]
end

subgraph group_knowledge["Knowledge and agents"]
  node_general_agent["General enquiry<br/>[general_enquiry.py]"]
  node_technical_agent["Technical clarification"]
  node_retrieval_planner["Retrieval planner<br/>[planning.py]"]
  node_knowledge_retriever["Knowledge retriever<br/>[mcp_retriever.py]"]
  node_mcp_client["MCP client<br/>[client.py]"]
end

subgraph group_models["Models and routing"]
  node_orchestrator["Route orchestrator<br/>[orchestrator.py]"]
  node_routing["Routing policy<br/>[routing.py]"]
  node_model_factory["Model factory<br/>[model.py]"]
  node_model_resilience["Model resilience"]
end

subgraph group_memory["Memory persistence"]
  node_memory_service["Memory service<br/>[service.py]"]
  node_memory_repository["Memory repository<br/>[repository.py]"]
  node_postgres_repository["Postgres adapter"]
  node_postgres[("Postgres database<br/>[database.py]")]
  node_memory_model["Memory model<br/>[models.py]"]
end

node_user(("User"))
node_mcp_server["MCP knowledge server"]

node_user -->|"sends message"| node_application
node_application -->|"loads and saves"| node_conversation_store
node_application -->|"invokes"| node_graph
node_application -->|"creates models"| node_model_factory
node_application -->|"opens session"| node_mcp_client
node_application -->|"configures"| node_knowledge_retriever
node_redis_store -->|"serializes state"| node_serialization
node_redis_store -->|"implements"| node_conversation_store
node_memory_store -->|"stores state"| node_state
node_graph -->|"dispatches routing"| node_orchestrator
node_graph -->|"dispatches"| node_general_agent
node_graph -->|"dispatches"| node_technical_agent
node_graph -->|"passes state"| node_state
node_orchestrator -->|"uses decision type"| node_routing
node_general_agent -->|"streams through"| node_model_resilience
node_general_agent -->|"emits"| node_stream_events
node_technical_agent -->|"plans retrieval"| node_retrieval_planner
node_technical_agent -->|"retrieves knowledge"| node_knowledge_retriever
node_technical_agent -->|"emits"| node_stream_events
node_knowledge_retriever -->|"calls search tool"| node_mcp_client
node_mcp_client -->|"calls tools"| node_mcp_server
node_memory_service -->|"uses repository"| node_memory_repository
node_memory_service -->|"handles memories"| node_memory_model
node_postgres_repository -->|"implements"| node_memory_repository
node_postgres_repository -->|"persists"| node_memory_model
node_postgres_repository -.->|"uses database"| node_postgres

click node_application "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/application.py"
click node_conversation_store "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/store.py"
click node_redis_store "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/redis.py"
click node_memory_store "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/in_memory.py"
click node_serialization "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/serialization.py"
click node_graph "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/graph.py"
click node_state "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/state.py"
click node_stream_events "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/streaming/events.py"
click node_orchestrator "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/orchestrator.py"
click node_routing "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/routing.py"
click node_model_factory "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/model.py"
click node_model_resilience "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/model_resilience.py"
click node_general_agent "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/agents/general_enquiry.py"
click node_technical_agent "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/agents/technical_clarification.py"
click node_retrieval_planner "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/retrieval/planning.py"
click node_knowledge_retriever "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/knowledge/mcp_retriever.py"
click node_mcp_client "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/mcp/client.py"
click node_memory_service "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/memory/service.py"
click node_memory_repository "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/memory/repository.py"
click node_postgres_repository "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/infrastructure/postgres/memory_repository.py"
click node_postgres "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/infrastructure/postgres/database.py"
click node_memory_model "https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/memory/models.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_application,node_conversation_store,node_redis_store,node_memory_store,node_serialization,node_graph,node_state,node_stream_events,node_user toneBlue
class node_general_agent,node_technical_agent,node_retrieval_planner,node_knowledge_retriever,node_mcp_client toneAmber
class node_orchestrator,node_routing,node_model_factory,node_model_resilience,node_mcp_server toneMint
class node_memory_service,node_memory_repository,node_postgres_repository,node_postgres,node_memory_model toneRose
```

## Components

### Conversation runtime

- [Chat application](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/application.py): `src/lisa/application.py`
- [Conversation store](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/store.py): `src/lisa/conversation/store.py`
- [Redis store](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/redis.py): `src/lisa/conversation/redis.py`
- [In-memory store](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/in_memory.py): `src/lisa/conversation/in_memory.py`
- [State serialization](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/conversation/serialization.py): `src/lisa/conversation/serialization.py`
- [Conversation graph](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/graph.py): `src/lisa/graph.py`
- [Conversation state](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/state.py): `src/lisa/state.py`
- [Stream events](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/streaming/events.py): `src/lisa/streaming/events.py`

### Knowledge and agents

- [General enquiry](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/agents/general_enquiry.py): `src/lisa/agents/general_enquiry.py`
- [Technical clarification](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/agents/technical_clarification.py): `src/lisa/agents/technical_clarification.py`
- [Retrieval planner](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/retrieval/planning.py): `src/lisa/retrieval/planning.py`
- [Knowledge retriever](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/knowledge/mcp_retriever.py): `src/lisa/knowledge/mcp_retriever.py`
- [MCP client](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/mcp/client.py): `src/lisa/mcp/client.py`

### Models and routing

- [Route orchestrator](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/orchestrator.py): `src/lisa/orchestrator.py`
- [Routing policy](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/routing.py): `src/lisa/routing.py`
- [Model factory](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/model.py): `src/lisa/model.py`
- [Model resilience](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/model_resilience.py): `src/lisa/model_resilience.py`

### Memory persistence

- [Memory service](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/memory/service.py): `src/lisa/memory/service.py`
- [Memory repository](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/memory/repository.py): `src/lisa/memory/repository.py`
- [Postgres adapter](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/infrastructure/postgres/memory_repository.py): `src/lisa/infrastructure/postgres/memory_repository.py`
- [Postgres database](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/infrastructure/postgres/database.py): `src/lisa/infrastructure/postgres/database.py`
- [Memory model](https://github.com/jemuelbjeroham/lisa/blob/main/src/lisa/memory/models.py): `src/lisa/memory/models.py`

### Other components

- **User**
- **MCP knowledge server**

## Connections

- User → Chat application: sends message (evidence: `src/lisa/application.py`)
- Chat application → Conversation store: loads and saves (evidence: `src/lisa/application.py`)
- Chat application → Conversation graph: invokes (evidence: `src/lisa/application.py`)
- Chat application → Model factory: creates models (evidence: `src/lisa/application.py`)
- Chat application → MCP client: opens session (evidence: `src/lisa/application.py`)
- Chat application → Knowledge retriever: configures (evidence: `src/lisa/application.py`)
- Redis store → State serialization: serializes state (evidence: `src/lisa/conversation/redis.py`)
- Redis store → Conversation store: implements (evidence: `src/lisa/conversation/redis.py`)
- In-memory store → Conversation state: stores state (evidence: `src/lisa/conversation/in_memory.py`)
- Conversation graph → Route orchestrator: dispatches routing (evidence: `src/lisa/graph.py`)
- Conversation graph → General enquiry: dispatches (evidence: `src/lisa/graph.py`)
- Conversation graph → Technical clarification: dispatches (evidence: `src/lisa/graph.py`)
- Conversation graph → Conversation state: passes state (evidence: `src/lisa/graph.py`)
- Route orchestrator → Routing policy: uses decision type (evidence: `src/lisa/orchestrator.py`)
- General enquiry → Model resilience: streams through (evidence: `src/lisa/agents/general_enquiry.py`)
- General enquiry → Stream events: emits (evidence: `src/lisa/agents/general_enquiry.py`)
- Technical clarification → Retrieval planner: plans retrieval (evidence: `src/lisa/agents/technical_clarification.py`)
- Technical clarification → Knowledge retriever: retrieves knowledge (evidence: `src/lisa/agents/technical_clarification.py`)
- Technical clarification → Stream events: emits (evidence: `src/lisa/agents/technical_clarification.py`)
- Knowledge retriever → MCP client: calls search tool (evidence: `src/lisa/knowledge/mcp_retriever.py`)
- MCP client → MCP knowledge server: calls tools (evidence: `src/lisa/mcp/client.py`)
- Memory service → Memory repository: uses repository (evidence: `src/lisa/memory/service.py`)
- Memory service → Memory model: handles memories (evidence: `src/lisa/memory/service.py`)
- Postgres adapter → Memory repository: implements (evidence: `src/lisa/infrastructure/postgres/memory_repository.py`)
- Postgres adapter → Memory model: persists (evidence: `src/lisa/infrastructure/postgres/memory_repository.py`)
- Postgres adapter → Postgres database: uses database
